クロスオリジンiframe内の同意:__tcfapiLocatorと__gppLocatorのパターン
問題:同意はトップウィンドウにある
CMPはページ上、つまり最上位のウィンドウで動作します。しかし、広告の多くはそうではありません。ディスプレイのクリエイティブ、リッチメディア、ヘッダー入札のレンダラー、多くのサードパーティウィジェットは、しばしば異なるオリジンのiframe内で動作します。クロスオリジンのiframe内のコードは、親ページの関数を直接呼び出せないため、単純に__tcfapiや__gppを呼び出して訪問者の選択を読み取ることはできません。
IABのフレームワークは、小さく明確に定義されたメッセージングの規約でこれを解決しています。フレーム内で動作する広告製品、埋め込み、計測スクリプトを構築する場合、あるいはそうした広告スタックをデバッグする場合は、その仕組みを正確に知っておく価値があります。
ロケーターフレーム
JavaScript APIに加えて、TCF対応のCMPは、__tcfapiLocatorという名前の空で見えないiframeを最上位のページに追加します。GPP対応のCMPも、__gppLocatorという名前のフレームで同じことを行います。これらのフレームにはコンテンツがありません。唯一の役割は見つけられることです。どの入れ子のフレーム内のスクリプトも、ウィンドウ階層を上にたどり、各階層でその名前のフレームが存在するかを確認できます。
フレーム名はwindow.framesを通じてオリジンをまたいで見えるため、深く入れ子になったクロスオリジンのiframe内のスクリプトは、そのページの他の何にもアクセスすることなく、CMPをホストするウィンドウを特定できます。
フレーム内のスクリプトがCMPを見つける方法
- 現在のウィンドウから始めます。__tcfapiがローカルに存在すれば、それを直接使います。スクリプトがフレーム内にないか、フレームがCMPを共有しています。
- そうでなければ、上方向にループします。現在のウィンドウに__tcfapiLocatorという名前のフレームがあるかを確認し、なければwindow.parentに移って再び確認します。最上位のウィンドウで停止します。
- ロケーターが見つかったら、それを含むウィンドウがCMPのウィンドウです。以降の通信はpostMessageを通じて行われます。
ブラウザやサンドボックスの設定によってはクロスオリジンのプロパティアクセスで例外がスローされるため、各アクセスをtry/catchで囲み、window.parentが現在のウィンドウと等しくなったらループを止めてください。
メッセージの形式
TCFの場合、フレーム内のスクリプトは、__tcfapiCallプロパティを持つオブジェクトを含むメッセージをCMPのウィンドウに送信します。その中には4つのフィールドがあります。
- command — たとえばgetTCData、ping、addEventListener
- parameter — コマンドが必要とする引数、またはnull
- version — APIのバージョン。TCF v2では2
- callId — 呼び出し側が生成する一意の値
CMPはこれらのメッセージを待ち受け、コマンドを実行し、returnValue、success、同じcallIdを含む__tcfapiReturnプロパティを持つオブジェクトを送り返します。呼び出し側は、callIdをキーとする保留中のコールバックのマップを保持し、messageイベントを待ち受け、各戻り値を適切なコールバックに振り分けます。GPPも、__gppCallと__gppReturnで同じパターンに従います。
多くの連携では、小さなプロキシを書きます。フレーム内に__tcfapiという名前のローカル関数を置き、呼び出しをメッセージに変換するものです。これにより、トップウィンドウ向けに書かれたコードが、フレーム内でも変更なしに動作します。
フレームをまたぐイベントリスナー
postMessageで送信されたaddEventListenerの呼び出しは、一度きりのリクエストではありません。CMPは同意状態が変わるたびに、すべて同じcallIdを持つ戻りメッセージを送信します。そのため、ディスパッチャーは最初のレスポンスの後にコールバックを削除せず、登録したままにしておく必要があります。これを忘れるのは典型的なバグで、フレーム内のスクリプトは同意を一度だけ読み取り、後の撤回に気づきません。
セキュリティ上の考慮事項
- メッセージの形を検証する。 期待するプロパティを含まないメッセージは無視し、文字列のペイロードは慎重にパースします。実装によっては、オブジェクトではなくJSON文字列を送るものがあるためです。
- 盲目的に信頼しない。 どのページもあなたのフレームにメッセージを送れます。レスポンスは、認証されたデータではなく、尊重すべき同意のシグナルとして扱い、特権的な操作の引き金にしてはいけません。
- 可能な限り特定のターゲットオリジンを使う。 CMPのオリジンがわかっている場合は、すべてのオリジンではなくそこに送信します。
このパターンが届かない場所
一部の広告環境は、クリエイティブをより厳密に隔離します。SafeFrameコンテナ、適切な権限のないサンドボックス化されたiframe、別のドキュメントでレンダリングされるクリエイティブは、フレームツリーをたどったりメッセージを受信したりできない場合があります。そのような場合、同意シグナルは通常、明示的に渡す必要があります。たとえば、広告リクエストのパラメータや、多くの広告タグが対応するgdprやgdpr_consentパラメータのように、広告サーバーがクリエイティブに渡す値としてです。
デバッグのチェックリスト
- トップウィンドウのDevToolsで、Elementsパネルにロケーターフレームが存在することを確認する。
- コンソールのコンテキストをiframeに切り替え、そこからロケーターに到達できるかを確認する。
- 両方のウィンドウで受信したmessageイベントをログに出力し、呼び出しと戻りが流れていることを確認する。
- バナーで同意を変更し、フレーム内のリスナーが更新を受け取ることを確認する。
- CMPの読み込みが遅れた状態でテストし、フレーム内のコードがすぐに諦めずにリトライまたは待機することを確認する。
重要なポイント
- クロスオリジンのフレームは、__tcfapiLocatorと__gppLocatorのフレームを通じてCMPに到達する。
- 呼び出しと戻りは、__tcfapiCall/__tcfapiReturnまたはGPPの対応するものを使ったpostMessageで行われ、callIdで対応付けられる。
- リスナーのコールバックを登録したままにして、後の同意の変更が届くようにする。
- すべてのメッセージを検証し、信頼できる入力として扱わない。
- フレームが完全に隔離されている場合は、広告リクエストで同意を明示的に渡す。