プライバシーと Messaging JavaScript API

はじめに

この API は、[プライバシーとメッセージ] タブに表示されるメッセージを操作するツールを提供します。Metrics Explorer では次の作業を行うことができます。

  • 特定のユーザーのメッセージを表示しない
  • ユーザーの広告ブロック ステータスを問い合わせる
  • ユーザーが同意を取り消すことができるようにする（該当する場合）

また、これらのツールを使用すると、業界標準のプロトコルを使用してユーザーの同意を収集することもできます。

その場合、同意ステータスがこれらの API を介して通知されます。

このユーザー メッセージ機能は、次の 2 つの方法でサイトにデプロイできます。

  1. ほとんどの場合、タグを再設定する必要はありません。関連するサービスでメッセージが公開されると、既存の Google パブリッシャー タグまたは AdSense タグによってユーザー メッセージがデプロイされます。
  2. 広告ブロックによる損失収益の回復メッセージを使用している場合は、広告ブロック タグをページに明示的に追加する必要があります。詳しくは、アド マネージャーと AdSense のタグ設定手順をご覧ください。

googlefc は、ユーザー メッセージ機能が JavaScript Window の API に使用するグローバル名前空間です。

フィールドの要約

名前 タイプ 定義
googlefc.controlledMessagingFunction function(!Object) メッセージングを進めるかどうかを決定する関数。この機能は、すべてのメッセージ タイプでサポートされています。
googlefc.callbackQueue !Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue ユーザー メッセージ クエリを非同期で実行するためのコールバック キューへの参照。
googlefc.CallbackQueue !Object コールバック キュー オブジェクトの型。
googlefc.AdBlockerStatusEnum !Object<string, number> ユーザーの広告ブロッカーの状態を表す列挙型。
googlefc.AllowAdsStatusEnum !Object<string, number> ユーザーの広告許可状態を表す列挙型。
googlefc.ccpa.InitialCcpaStatusEnum !Object<string, number> ユーザーの初期 CPRA ステータスを表す列挙型。
googlefc.ccpa.overrideDnsLink 未定義|ブール値 カスタムの「販売しない」リンクを使用するために true に設定可能なブール値。

メソッドの概要

名前 戻り値の型 定義
googlefc.showRevocationMessage() 未定義 同意レコードを消去し、googlefc スクリプトを再読み込みして、ユーザーに適した同意メッセージを表示します。
googlefc.getAdBlockerStatus() 数値 ユーザーの広告ブロック ステータスに応じて、AdBlockerStatusEnum に値を返します。
googlefc.getAllowAdsStatus() 数値 ユーザーの広告許可ステータスに応じて、AllowAdsStatusEnum で値を返します。
googlefc.ccpa.getInitialCcpaStatus() 数値 ユーザーの初期 CPRA ステータスに応じて、InitialCcpaStatusEnum に値を返します。
googlefc.ccpa.openConfirmationDialog(function(boolean)) 未定義 デフォルトの「販売しない」リンクがオーバーライドされた場合に、CPRA 確認ダイアログを開きます。

サイトでテストとデバッグを行う

「プライバシーとメッセージ」にはデバッグ機能とテスト機能があり、実際のサイトで特定のメッセージ（またはメッセージの組み合わせ）がどのように表示されるかを確認できます。

前提条件:

  • プレビューするメッセージは、テスト対象のサイトで公開されている必要があります

次のデバッグ URL パラメータを使用すると、サイトでライブ プレビューを表示できます。

デバッグ パラメータ 使用できる値
fc alwaysshow（デバッグ/プレビュー モードをトリガーします）
fctype ab（広告ブロック メッセージ）、ccpa（CPRA オプトアウト メッセージ）、gdpr（GDPR 同意メッセージ）、monetization（Offerwall メッセージ）

これを使用してサイト（foo.com）でプレビューする方法の例:

  • CPRA メッセージのテスト -- http://foo.com/?fc=alwaysshow&fctype=ccpa
  • GDPR メッセージのテスト -- http://foo.com/?fc=alwaysshow&fctype=gdpr

フィールド: 説明と例

googlefc.controlledMessagingFunction {function(!Object)}

メッセージを表示するかどうかを決定する関数。これを使用して、サブスクライバーのステータスやページ URL など、パブリッシャーが指定した条件でメッセージ レンダリングを制限できます。

他のスクリプトが読み込まれる前に Window で googlefc.controlledMessagingFunction を定義すると、message.proceed(boolean) を呼び出すまでメッセージは表示されません。message.proceed(true) を呼び出すとメッセージは通常どおりに処理され、message.proceed(false) を呼び出すと該当のページビューでメッセージが表示されなくなります。

たとえば、ページにこのスクリプトが配置されていて、ログインしているユーザーが定期購読者かどうかを確認する非同期関数 determineIfUserIsSubscriber() が定義されているとします。

<head>
  <script>
    window.isSubscriber = undefined;
    function determineIfUserIsSubscriber() {
      if (isSubscriber !== undefined) {
        return isSubscriber;
      }
      return new Promise(resolve => {
        setTimeout(() => {
          // Change this to true if you want to test what subscribers would see.
          window.isSubscriber = false;
          resolve(window.isSubscriber);
        }, 1000);
      });
    }
  </script>
</head>

これは、googlefc.controlledMessagingFunction を使用してサブスクライバー以外のユーザーにのみメッセージを表示する方法の例です。

<head>
  <script>
    // Define googlefc and the controlled messaging function on the Window.
    window.googlefc = window.googlefc || {};
    googlefc.controlledMessagingFunction = async (message) => {
      // Determine if the user is a subscriber asynchronously.
      const isSubscriber = await determineIfUserIsSubscriber();

      if (isSubscriber) {
        // If the user is a subscriber, don't show any messages.
        message.proceed(false);
      } else {
        // Otherwise, show messages as usual.
        message.proceed(true);
      }
    }
  </script>
</head>

また、この機能の拡張版として、Offerwall のクローズド ベータ版に参加しているパブリッシャーは、Offerwall のみを非表示にするように指定できます。この機能が有効になっていても、他のメッセージ タイプは影響を受けません。

Offerwall 固有の制御されたメッセージを実現するには、googlefc.MessageTypeEnum 型の Array である message.proceed() に追加のパラメータを渡します。

例: 次の例では、googlefc.controlledMessagingFunction を使用して、サブスクライバーに対する Offerwall の配信のみを抑制し、他のメッセージ タイプは抑制しています。

<head>
  <script>
    // Define googlefc and the controlled messaging function on the Window.
    window.googlefc = window.googlefc || {};
    googlefc.controlledMessagingFunction = async (message) => {
     // Determine if the Offerwall should display or not.
     const shouldDisplayOfferwall = await determineIfUserIsSubscriber();
     const applicableMessageTypes = [];

     if (!shouldDisplayOfferwall) {
       // Do not show the Offerwall, but allow other message types to display.
       applicableMessageTypes.push(window.googlefc.MessageTypeEnum.OFFERWALL);
       message.proceed(false, applicableMessageTypes);
     } else {
       // Otherwise, show messages as usual.
       message.proceed(true);
     }
    }
  </script>
</head>

googlefc.callbackQueue {!Array<!Object<string, function()>> | !Array<function()> | !googlefc.CallbackQueue}

メッセージ関連の呼び出しを非同期で実行するためのグローバル コールバック キューへの参照。関数を呼び出す方法としてサポートされている唯一の方法は、callbackQueue に追加することです。

異なる種類のデータが利用可能になるタイミングが異なるため、次の文字列のいずれかをキー、実行する関数を値として、関数をマップとして追加する必要があります。

サポートされている鍵:

キーの名前 使用量 相対レイテンシ
CONSENT_API_READY CONSENT_API_READY キーを使用してコールバック キューに push された関数は、サポートされている同意フレームワークの API が定義され、呼び出し可能になると実行されます。この時点から、後から追加された CONSENT_API_READY キーの関数は同期的に実行されます。フレームワーク固有の詳細については、 IAB フレームワークのセクションをご覧ください。 低
CONSENT_DATA_READY CONSENT_DATA_READY キーでコールバック キューに push された関数は、サポートされている同意フレームワークでユーザーの同意が得られたことが判明した時点で（以前の実行から、またはユーザーが同意メッセージを操作した後で）実行されます。この時点から、後から追加された CONSENT_DATA_READY キーの関数は同期的に実行されます。 高
AD_BLOCK_DATA_READY AD_BLOCK_DATA_READY キーを使用してコールバック キューにプッシュされた関数は、広告ブロック データがフローで使用可能になると実行されます。この時点から、後から追加された AD_BLOCK_DATA_READY キーの関数は同期的に実行されます。 高
INITIAL_CCPA_DATA_READY INITIAL_CCPA_DATA_READY を使用してコールバック キューに push された関数は、フローで CPRA データが使用可能になると実行されます。CPRA データに対する後続のリクエストはすべて、US Privacy API（__uspapi）を直接呼び出して取得する必要があります。 中

googlefc.CallbackQueue {!Object}

メソッドの概要:

名前 タイプ パラメータ 戻り値の型 ロール
push(data) 数値 data: データ可用性タイプの 1 つをキーとする JavaScript 関数の値を含む Key-Value ペア。使用可能なデータ可用性キーは、CONSENT_API_READY、CONSENT_DATA_READY、AD_BLOCK_DATA_READY、INITIAL_CCPA_DATA_READY です。 これまでに追加されたコマンドの数。配列の現在の長さを返します。 渡された関数を、データが利用可能になる順に実行します。次に、これらの関数がキューに追加される順序で実行します。

例:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      if (googlefc.getAdBlockerStatus() == googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER) {
        // Handle a non-ad blocking user.
      }
    }
  });
</script>

googlefc.AdBlockerStatusEnum {!Object<string, number>}

ユーザーのさまざまな広告ブロック状態を表します。状態には次のものがあります。

googlefc.AdBlockerStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // The user was running an extension level ad blocker.
  EXTENSION_AD_BLOCKER: 1,
  // The user was running a network level ad blocker.
  NETWORK_LEVEL_AD_BLOCKER: 2,
  // The user was not blocking ads.
  NO_AD_BLOCKER: 3,
};

googlefc.AllowAdsStatusEnum {!Object<string, number>}

ユーザーのさまざまな広告ブロックの広告許可ステータスを表します。その状態には次のものがあります。

googlefc.AllowAdsStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // User is currently using an ad blocker, was never using an ad blocker, or
  // allowed ads, but not because they saw the Privacy & messaging message.
  ADS_NOT_ALLOWED: 1,
  // User is no longer using an ad blocker after seeing the ad blocking message.
  ADS_ALLOWED: 2,
};

googlefc.ccpa.InitialCcpaStatusEnum{!Object<string, number>}

ユーザーのさまざまな広告ブロックの広告許可ステータスを表します。その状態には次のものがあります。

googlefc.ccpa.InitialCcpaStatusEnum = {
  // Something failed, in an unknown state.
  UNKNOWN: 0,
  // CPRA does not apply to this user.
  CCPA_DOES_NOT_APPLY: 1,
  // CPPA applies to this user, and the user has not opted out yet.
  NOT_OPTED_OUT: 2,
  // CPPA applies to this user, and the user has opted out.
  OPTED_OUT: 3,
};

googlefc.ccpa.overrideDnsLink{undefined|boolean}

デフォルトの「販売しない」リンクを非表示にしてカスタムの「販売しない」リンクを使用するには、このフィールドを true に設定します。

例:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  // Signals that the default DNS link will be overridden.
  googlefc.ccpa.overrideDnsLink = true;
</script>

手法: 説明と例

googlefc.getConsentStatus(): {number}

googlefc.getConsentedProviderIds(): {!Array<string>}

  1. これは、呼び出されたときに常に空のリストを返すようになりました。

googlefc.showRevocationMessage(): {undefined}

現在の同意レコードを消去し、このユーザーに適用される同意メッセージを表示します。この関数に指定する必要があるキーは CONSENT_DATA_READY です。

例:

<button type="button" onclick="googlefc.callbackQueue.push({'CONSENT_DATA_READY': () => googlefc.showRevocationMessage()});">
  Click here to revoke
</button>

googlefc.getAdBlockerStatus(): {number}

ユーザーの広告ブロック ステータスに応じて、AdBlockerStatusEnum の値を返します。この関数に指定する必要があるキーは AD_BLOCK_DATA_READY です。

例:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      switch (googlefc.getAdBlockerStatus()) {
          case googlefc.AdBlockerStatusEnum.EXTENSION_LEVEL_AD_BLOCKER:
          case googlefc.AdBlockerStatusEnum.NETWORK_LEVEL_AD_BLOCKER:
            // Insert handling for cases where the user is blocking ads.
            break;
          case googlefc.AdBlockerStatusEnum.NO_AD_BLOCKER:
            // Insert handling for cases where the user is not blocking ads.
            break;
          case googlefc.AdBlockerStatusEnum.UNKNOWN:
            // Insert handling for unknown cases.
            break;
      }
    }
  });
</script>

googlefc.getAllowAdsStatus(): {number}

ユーザーの広告許可ステータスに応じて、AllowAdsStatusEnum で値を返します。この関数に指定する必要があるキーは AD_BLOCK_DATA_READY です。

例:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'AD_BLOCK_DATA_READY':
    () => {
      switch (googlefc.getAllowAdsStatus()) {
        case googlefc.AllowAdsStatusEnum.ADS_NOT_ALLOWED:
          // Insert handling for cases where the user has not allowed ads.
          // The user may have never been an ad blocker.
          break;
        case googlefc.AllowAdsStatusEnum.ADS_ALLOWED:
          // Insert handling for cases where the user saw the ad blocking
          // message and allowed ads on the site.
          break;
        case googlefc.AllowAdsStatusEnum.UNKNOWN:
          // Insert handling for unknown cases.
          break;
      }
    }
  });
</script>

googlefc.ccpa.getInitialCcpaStatus(): {number}

ユーザーの CPRA ステータスに応じて、InitialCcpaStatusEnum に値を返します。この関数に指定する必要があるキーは INITIAL_CCPA_DATA_READY です。後続の CPRA データリクエストは、US Privacy API（__uspapi）を直接呼び出して取得する必要があります。

例:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  googlefc.callbackQueue.push({
    'INITIAL_CCPA_DATA_READY':
    () => {
      switch (googlefc.ccpa.getInitialCcpaStatus()) {
        case googlefc.ccpa.InitialCcpaStatusEnum.CCPA_DOES_NOT_APPLY:
          // Insert handling for cases where the user is not CPRA eligible.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT:
          // Insert handling for cases where the user is CPRA eligible and has
          // not opted out.
          break;
        case googlefc.ccpa.InitialCcpaStatusEnum.OPTED_OUT:
          // Insert handling for cases where the user is CPRA eligible and has
          // opted out.
          break;
      }
    }
  });
</script>

googlefc.ccpa.openConfirmationDialog(function(boolean)): {undefined}

デフォルトの「販売しない」リンクがオーバーライドされた場合に CPRA 確認ダイアログを開きます。ユーザーが確認ダイアログを操作すると、指定されたコールバック関数が、ユーザーがオプトアウトした場合には true で呼び出され、オプトアウトした場合には false で呼び出されます。

例:

<script>
// This callback will be called with the user CPRA decision.
const ccpaCompletionCallback = (userOptedOut) => {
  // Insert handling for user opt-out status here.
}
// Invoke the CPRA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
  "click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>

Google の同意管理ソリューションを使用して、IAB TCF v2 フレームワークに基づいて GDPR 同意を収集する場合は、IAB TCF v2 API を使用する必要があります。

CONSENT_API_READY コールバック キューキーを使用すると、IAB TCF v2 API がページで定義されている場合にのみ、対応するコールバックが呼び出されるようにできます。これは、IAB TCF v2 API の 'addEventListener' コマンドと組み合わせて使用する必要があります。

例:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback using the CONSENT_API_READY key on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_API_READY':
    () => __tcfapi('addEventListener', 2.2, (data, success) => {
      // Do something with consent data value; this callback may be invoked
      // multiple times as user completes consent flow.
    })
  });
</script>

CONSENT_DATA_READY コールバック キューキーを使用すると、ユーザーの同意が収集され、IAB TCF v2 API を使用してアクセスできる場合にのみ、対応するコールバックが呼び出されるようになります。これは 'addEventListener' コマンドと組み合わせて使用できます。指定したコールバックの最初の呼び出しで提供されるデータには、ユーザーの同意の選択が含まれます（TCF v2 がこのユーザーに適用される限り）。なお、TCF v2.2 のリリースに伴い、'getTCData' コマンドは非推奨になりました。

例:

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback using the CONSENT_DATA_READY key on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __tcfapi('addEventListener', 2.2, (data, success) => {
      // Do something with consent data value; this callback may be invoked
      // multiple times if user consent selections change.
    })
  });
</script>

CPRA 用の IAB GPP フレームワークで Google の同意管理ソリューションを使用する

Google の同意管理ソリューションを使用して、IAB GPP フレームワークに基づいて CPRA のオプトアウトを収集する場合は、IAB GPP API を使用してください。

CPRA 規則はオプトアウトの性質を持つため、コールバックが呼び出されたときに IAB GPP API が呼び出し可能で同意データを返すようにするために、CONSENT_API_READY または CONSENT_DATA_READY コールバック キューキーを使用できます。

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Queue the callback on the callbackQueue.
  window.googlefc.callbackQueue.push({
    'CONSENT_DATA_READY':
    () => __uspapi('getUSPData', 1, (data, success) => {
      // Do something with consent data value.
    })
  });
</script>

CPRA 用の IAB GPP フレームワークと Google の同意管理ソリューションを、カスタムの「販売禁止」リンクとともに使用している

Google の同意管理ソリューションを使用して、IAB GPP フレームワークで CPRA のオプトアウトを収集する場合は、googlefc.ccpa.overrideDnsLink フラグを true に設定することでカスタムの「販売しない」リンクを提供できます。

<script>
  // Make sure that the properties exist on the window.
  window.googlefc = window.googlefc || {};
  window.googlefc.ccpa = window.googlefc.ccpa || {}
  window.googlefc.callbackQueue = window.googlefc.callbackQueue || [];

  // Signals that the default DNS link will be overridden.
  window.googlefc.ccpa.overrideDnsLink = true;

  // Register the callback for the initial CPRA data.
  window.googlefc.callbackQueue.push({
      'INITIAL_CCPA_DATA_READY': () => {
        if (googlefc.ccpa.getInitialCcpaStatus() ===
            googlefc.ccpa.InitialCcpaStatusEnum.NOT_OPTED_OUT) {
          // TODO: Display custom CPRA Do Not Sell link here.
        }
      }
    });
</script>

これにより、デフォルトの [販売しない] リンクは表示されなくなります。CPRA を遵守するには、独自の「販売しない」リンクをレンダリングする必要があります。次に、CPRA 確認ダイアログを呼び出して、「販売しない」カスタムリンクに対するユーザー インタラクションを処理します。

<script>
// This callback will be called with the user CPRA decision.
const ccpaCompletionCallback = (userOptedOut) => {
  if (userOptedOut) {
    // TODO: Hide custom CPRA Do Not Sell link here.
  }
}
// Invoke the CPRA confirmation dialog when the user clicks the link.
document.getElementById("your-custom-ccpa-do-not-sell-link").addEventListener(
  "click", () => googlefc.ccpa.openConfirmationDialog(ccpaCompletionCallback));
</script>