Localhostテスト

デフォルトでは、テストデータがアナリティクスを汚染するのを防ぐため、Zenovayはlocalhostおよびその他のローカル環境でのトラッキングをブロックします。開発とテスト用にローカルトラッキングを有効にすることができます。

Localhostトラッキングを有効にする

オプション1：ダッシュボードトグル（推奨）

1. Zenovayダッシュボードに移動します
2. ドメインを開き、サイトをクリックします
3. ドメイン設定で、詳細セクションを開きます
4. **「Localhostを許可」**トグルを有効にします
5. 保存をクリックします

オプション2：スクリプト属性

HTMLを使用して環境ごとにこれを制御する場合は、スクリプトタグにdata-allow-localhost="true"を追加します：

<script defer
data-tracking-code="YOUR_TRACKING_CODE"
data-allow-localhost="true"
src="https://api.zenovay.com/z.js">
</script>

注意: 実際に有効なのは上記のダッシュボード設定です。サーバーはこの設定が有効な場合にのみlocalhostイベントを受け付け、トラッカーの設定取得がこの属性より優先されます。この属性はオフライン開発用（設定取得が完了できない場合）に残してください。本番ドメインでは効果がありません。

オプション3：動的スクリプト読み込み

ReactやNext.jsなどのフレームワークでスクリプトを動的に読み込む場合：

const script = document.createElement('script');
script.src = 'https://api.zenovay.com/z.js';
script.defer = true;
script.setAttribute('data-tracking-code', 'YOUR_TRACKING_CODE');
script.setAttribute('data-allow-localhost', 'true');
document.head.appendChild(script);

動作方法

Zenovayのトラッカーはホスト名をチェックしてローカル環境を検出します：

ローカル環境が検出されたとき、トラッカーは次の2つのことを順番にチェックします：

1. サーバー設定 — トラッカーはZenovay APIからウェブサイトの設定をフェッチします。ダッシュボードでallow_localhostが有効な場合、トラッキングが進みます。
2. スクリプト属性 — APIコールが失敗したか完了していない場合、スクリプトタグのdata-allow-localhost="true"属性がフォールバックとして機能します。

どちらも設定されていない場合、トラッキングはブロックされ、ブラウザコンソールに次のメッセージが表示されます：

[Zenovay] Environment blocked — Localhost blocked (use data-allow-localhost='true' to enable)

動作確認

ブラウザコンソール

DevTools（F12）→コンソールタブを開きます。Localhostトラッキングが有効な場合、次のように表示されます：

Zenovay Analytics loaded { trackingCode: "ZV_...", reason: "Active" }

Localhostがブロックされている場合、次のように表示されます：

[Zenovay] Environment blocked { reason: "Localhost blocked (use data-allow-localhost='true' to enable)" }

ネットワークタブ

DevTools→ネットワークタブを開き、zenovayまたはapi.zenovay.comでフィルタリングします：

1. GET z.js — スクリプトロード（200 OK）
2. GET /api/websites/settings/ZV_... — 設定フェッチ（200 OK、レスポンスにallow_localhost: trueが含まれます）
3. POST /e/ZV_... — ページビューイベント追跡（200 OK）

ステップ3が403を返す場合、ドメイン確認がリクエストをブロックしています。ダッシュボード設定でallow_localhostが有効になっていることを確認してください。

ダッシュボード

Localhostでページをロードした後、Zenovayダッシュボードに移動します。ドメインを開き、サイトを選択して、アナリティクスタブを開きます。ホストの内訳の下に、localhost（または127.0.0.1）がソースとしてリストされているはずです。

デバッグモードとLocalhostを許可の違い

これらは異なる目的を持つ2つの別々の設定です：

開発中に両方を有効にすることで最大限の可視性を得ることができますが、独立して機能します。

• Localhostを許可はトラッキングがLocalhostで実行されるかどうかのみを制御します
• デバッグモードはデバッグ出力がコンソールに表示されるかどうかのみを制御します

ロードエンドポイントでの使用

/loadエンドポイント（本番環境推奨）を使用する場合、Localhostの設定はサーバーによって自動的に注入されます：

<script defer
data-tracking-code="YOUR_TRACKING_CODE"
src="https://api.zenovay.com/load/YOUR_TRACKING_CODE">
</script>

/loadエンドポイントを使用する場合、ダッシュボードで「Localhostを許可」を有効にするだけで十分です。data-allow-localhost属性は不要です。

Localhost上のファーストパーティプロキシ

本番環境のセットアップでファーストパーティプロキシ（例：/api/_z/script.js）を使用する場合、プロキシはapi.zenovay.comに転送するサーバー側ルートであるため、通常、localhostでは機能しません。

ソリューション：

1. Localhost上で直接スクリプトを使用：開発中にhttps://api.zenovay.com/z.jsに切り替える
2. ローカルプロキシをセットアップ：開発サーバーを設定して/api/_z/をhttps://api.zenovay.com/にプロキシする
3. 環境ベースのスクリプトURLを使用：本番環境ではプロキシから読み込み、開発環境では直接読み込む

const isDev = window.location.hostname === 'localhost';
const script = document.createElement('script');
script.src = isDev
? 'https://api.zenovay.com/z.js'
: '/api/_z/script.js';
script.defer = true;
script.setAttribute('data-tracking-code', 'YOUR_TRACKING_CODE');
if (isDev) script.setAttribute('data-allow-localhost', 'true');
document.head.appendChild(script);

トラブルシューティング

Localhost上でトラッキングが機能しない

1. ダッシュボード設定を確認：ドメインを開き、サイトを選択して、詳細セクションを開き、「Localhostを許可」が有効になっていることを確認します
2. ハードリフレッシュ：変更が有効になるまで最大30秒かかります。Ctrl+Shift+Rを実行してキャッシュされたスクリプトをクリアします
3. コンソールを確認：DevToolsを開き、[Zenovay]メッセージを探します
4. スクリプトロードを確認：ネットワークタブでz.jsが200を返しているか確認します
5. 広告ブロッカーを確認：ブラウザ拡張機能がLocalhostでもアナリティクスをブロックする可能性があります

イベントが403を返す

APIがドメイン確認によってトラッキングリクエストを拒否しました。これは以下を意味します：

• ウェブサイト設定でallow_localhostが有効になっていない、または
• 設定がまだ伝播していない（30秒待って再試行してください）

イベントは送信されるがダッシュボードにデータが表示されない

Localhostデータはアナリティクスに本番データと並んで表示されます。次を確認してください：

• ホストタブをアナリティクスで確認 — localhostエントリを探します
• フィルタ — Localhostトラフィックをフィルタリングしていないことを確認します
• 時間範囲 — 本日のデータを見ていることを確認します