3分で読めます

デバッグオーバーレイ

ブラウザの DevTools を開かなくても、Zenovay トラッカーが送信しているすべてのイベント — タイプ、プロパティ、Cookie レスモード、GPC の状態、同意の状態、スクリプトのバージョン — をストリーム表示する、ページ内フローティングオーバーレイです。PII はマスクされます。オーバーレイは二重ゲート式になっており、ウェブサイト設定ページでオプトインかつサイト上の URL に ?zenovay_debug=1 を付与した場合にのみ起動します。

両方のゲートが必須です。 ウェブサイト側の設定だけを有効にしても何も起こりません。?zenovay_debug=1 を付与するだけでも何も起こりません。同じページロードで両方が真である必要があります。これにより、一般訪問者への意図しない露出を防ぎます。

用途

インストールを検証する場面 — ローカル開発、ステージング、本番のスモークテスト — で知りたいのは通常 1 つの事実です:「トラッカーは正しいプロパティを伴って正しいイベントを発火しているか?」。従来の答え方はこうでした: DevTools を開く → ネットワークタブ → /e/ または /api/_z でフィルタ → 各リクエストをクリック → JSON ボディを読む。デバッグオーバーレイはこれを一目で確認できる形に縮約します: トラッカーが送信したすべてのイベントが行として表示され、いずれかの行をクリックすると JSON 全体が表示され、「Copy JSON」をクリックするとサポートチケットに貼り付けられます。

新しいチームメイトのオンボーディング (「これがまさに私たちが送信している内容です」) や、意図された挙動の文書化 (既知の正常なユーザーフロー中にオーバーレイのスクリーンショットを撮り、リグレッションのベースラインとして保存する) にも便利です。

有効化方法

app.zenovay.com にサインインし、ドメイン ページを開きます。
デバッグしたいドメインをクリックします。
設定 → 詳細 を開き、基本設定 セクションまでスクロールします。
「Allow Debug Overlay」をオンに切り替えます。
自分のサイト上で、?zenovay_debug=1 を付与した URL に移動します — 例: https://your-site.com/?zenovay_debug=1 または https://your-site.com/checkout?zenovay_debug=1。

トラッカーがロードされてから約 1 秒後に、オーバーレイが画面右下に表示されます。

キャッシュの伝播: トラッカー設定はトグルを切り替えてから最大 5 分間、エッジでキャッシュされます。オーバーレイがすぐに表示されない場合は、ハードリロード (Cmd/Ctrl + Shift + R) するか、数分待ってください。

表示される内容

オーバーレイには 3 つの領域があります。

ヘッダーチップ は現在のページ上のトラッカーのランタイム状態を表示します:

cookieless ON | OFF — このウェブサイトで Cookie レスモードが有効かどうか。ON はトラッカーが window スコープのインメモリ ID を使用し、Cookie を一切書き込まないことを意味します。OFF は Cookie ベースのセッション/訪問者 ID が使用中であることを意味します。
GPC ON | OFF — 訪問者のブラウザが Global Privacy Control シグナル (Sec-GPC: 1 / navigator.globalPrivacyControl === true) を送信したかどうか。ON のとき、行動エンリッチメント (B2B、スコアリング) はサーバー側でスキップされます。
consent: <state> — トラッカーが最後に観測した同意状態 (opt-in、opt-out、unknown)。同意管理プラットフォームを使用している場合、これは訪問者の選択を反映します。
v<version> — 現在ページで実行されているトラッカースクリプトのバージョン。

イベントリスト は直近 20 件の送信イベントを新しい順に表示します。各行には次が表示されます:

壁時計タイムスタンプ (HH:MM:SS、ブラウザのローカル時刻)
イベントタイプ
最大 4 個の省略表示プロパティキー

いずれかの行をクリックすると JSON モーダルが開きます。

JSON モーダル はイベントの完全な JSON を (PII マスク適用後で) 表示します。Copy JSON ボタンを使うとクリップボードにコピーできます — チームメイトに共有したり、サポートチケットに添付したりするのに便利です。

イベントタイプの読み方

イベントタイプ	意味
`pageview`	新しいページが表示されました。URL、リファラー、UTM パラメータ、デバイスクラス、画面サイズが含まれます。
`heartbeat`	訪問者がまだページに滞在していることを示します。アイドル中は約 2 秒ごとに発火し、ページ滞在時間を正確に算出できるようにします。
`page_exit`	訪問者がタブを閉じる、または別の場所へ遷移しました。ページ滞在時間の最終差分です。
`outbound_link`	`href` が自分のドメイン外を指す `<a>` タグへのクリック。
`goal_completion`	構成済みのゴールが発火しました。ゴール名と任意のカスタムパラメータが含まれます。
`funnel_step`	訪問者が構成済みファネルのステップへ進みました。
`custom_event`	自身のコードからの `zenovay.track('event_name', {...})` 呼び出し。
`error`	トラッカーがキャプチャした JavaScript エラー (プランでエラートラッキングが有効な場合のみ送信されます)。
`core_web_vitals`	現在のページの LCP / CLS / INP 計測値 (メトリクスが安定したらページごとに 1 回送信)。
`session_replay`	セッションリプレイデータの 1 チャンクがアップロードされました。オーバーレイにはチャンクが送信された事実のみが表示されます — 録画内容は決して表示されません。
`frustration_signal`	レイジクリック、デッドクリック、または過剰なスクロールジッターのシグナルが検出されました。

PII マスキング

オーバーレイは画面に表示する前に、すべてのイベントへ表示側のマスクを適用します。マスクは 2 つのケースをカバーします。

フィールド名 (キー) の一致 — 次のいずれかのキー名を持つプロパティは [MASKED] に置き換えられます:

email、phone、first_name、last_name、name、customer_id、user_id、ip、ip_address、client_ip、user_agent、useragent、ua

値のパターン一致 — キー名が一致しなくても適用されます:

メール形式 ([email protected]) に一致する文字列は部分的に伏字化されます (a***@b***.tld)。
IPv4 (1.2.3.4) に一致する文字列は [IP] に置き換えられます。
80 文字を超え、Mozilla|WebKit|Chrome|Safari|Firefox を含む文字列は切り詰められて [UA truncated] のラベルが付きます。

マスキングはオーバーレイの表示レイヤーでのみ行われます。トラッカーが実際に Zenovay に送信する生のイベントペイロードは変更されません — それがダッシュボードを動かすデータです。マスクは画面に表示される内容のみに影響するため、オーバーレイのスクリーンショットや JSON のコピー & ペーストは安全に共有できます。

プライバシーとコンプライアンス

オーバーレイはどの環境でも安全に有効化できるよう設計されていますが、何を行い何を行わないかを正確に理解しておく必要があります:

Cookie ゼロ、localStorage ゼロ。 イベントバスは window 上のプレーンな JavaScript 配列 (window._zenovayDebugBus) です。タブを閉じると消滅します。
リモートロギングなし。 オーバーレイはネットワーク呼び出しを一切行いません。表示されるすべてのデータは、ブラウザのメモリにすでにあるものから描画されます。
遅延ロード。 オーバーレイ UI は別の HTTP リソース (/debug-overlay.js) であり、両方のゲートが満たされた場合にのみダウンロードされます。URL パラメータを持たない訪問者は、オーバーレイのバイトを 1 つもダウンロードしません。
Cookie レストラッカーの不変条件は維持されます。 ウェブサイトが Cookie レスモードである場合、オーバーレイを有効にしてもトラッカーの挙動は変わりません — Cookie は書き込まれず、同じ window スコープの一時 ID が使用され、ヘッダーの cookieless チップは ON と表示されます。
GPC は常に尊重されます。 オーバーレイはトラッカー設定から GPC の状態を読み取りますが、それを迂回することはありません。

トラブルシューティング

「?zenovay_debug=1 を付けたのに何も起きません。」

ウェブサイト設定がオンであることを再確認してください。両方のゲートが真である必要があります。
ハードリロード (Cmd/Ctrl + Shift + R) を実行してください — トラッカー設定はトグル切り替え後、最大 5 分間キャッシュされます。
DevTools を開いて window.ZENOVAY_TRACKER_CONFIG を実行し、トラッカーのバージョンがオーバーレイに対応していることを確認してください — トグルがオンなのに allowDebugOverlay が false の場合は、まだキャッシュが破棄されていません。
サイトの Content-Security-Policy が api.zenovay.com からのスクリプトをブロックしていないか確認してください。

「オーバーレイは表示されるがイベントが出ません。」

ページ上で操作 (リンククリック、スクロール、遷移) を行い、トラッカーに何かを発火させてください。
それでも何も表示されない場合、トラッカーが送信していない可能性があります — サーバー側から同じ経路をプローブするインストール状態と照合してください。

「SPA のルート遷移でオーバーレイが消えます。」

オーバーレイはルート遷移をまたいで自動的に再マウントされるはずです。そうならない場合は、document.body の子要素を積極的に削除するフレームワーク特有の既知のエッジケースです — help.zenovay.com で再現手順をご報告ください。

「ページに Zenovay トラッカーが複数あります。」

マウントされるオーバーレイは 1 つだけです。最初に初期化されたトラッカーが勝ちます (window._zenovayDebugOverlayMounted ガード)。

「意図的に送信したフィールドが [MASKED] と表示されます。」

これは想定どおりです。マスクは一般的な PII キー名のリストに対して無条件に適用されます。機微に見える名前を持つ非 PII フィールドを表示する必要がある場合 (例: 個人情報ではないラベルに name を使用していた場合)、プロパティ名を変更して再テストしてください。

「オーバーレイが UI の重要な部分を覆ってしまいます。」

ヘッダーの × をクリックすると、次のページロードまでオーバーレイが非表示になります。

無効化のタイミング

インストールを検証し終えたら、本番では Allow debug overlay トグルをオフにすることを推奨します。二重ゲートにより一般訪問者 (?zenovay_debug=1 を付与しない) への意図しない露出は防げますが、デフォルトでウェブサイト側のフラグをオフにしておくと第 2 要素が完全に取り除かれ、開発者が誤ってデバッグ URL を共有した場合でも意図しない露出が起こり得なくなります。

ブラウザサポート

オーバーレイはエバーグリーンブラウザすべて (Chrome、Firefox、Safari、Edge) で動作し、URLSearchParams を持たない古いブラウザや制限の厳しい CSP 環境では適切にフェイルセーフします — ホストページ内で未処理エラーを投げることはありません。

デバッグ オーバーレイ

用途