このページは Cloud Translation API によって翻訳されました。

プライバシーとメッセージに関する JavaScript API

はじめに

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

特定のユーザーのメッセージを非表示にする
ユーザーの広告ブロックステータスをクエリする
ユーザーが同意を取り消すことを許可する（該当する場合）

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

IAB TCF v2 仕様に基づく GDPR への同意
IAB GPP の CPRA 仕様に沿って CPRA を無効にする

同意ステータスは、このような API を介して通知されます。

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

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

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

注: このリファレンスでは、google-closure タイプのアノテーションを使用します。以下に、例を簡潔に説明します。

boolean: JavaScript のブール値型。
number|string: 共用体のタイプ。値は数値または文字列のいずれかです。
?string: 値が文字列型または null であることを示します。デフォルトでは、文字列型、数値型、ブール値型は null 値非許容です。
Array<string>: 文字列の配列。
googlefc.CallbackQueue: googlefc.CallbackQueue クラスのオブジェクト。
!googlefc.CallbackQueue: 値が null ではなく googlefc.CallbackQueue 型であることを示します。デフォルトでは、すべてのオブジェクトタイプが null 値許容です。
!Array<!googlefc.CallbackQueue>: googlefc.CallbackQueue オブジェクトの配列。各オブジェクトが null でない。配列自体が null でない。
!googlefc.ConsentStatusEnum: ConsentStatusEnum に含まれる数値。
!googlefc.AdBlockerStatusEnum: AdBlockerStatusEnum に含まれる数値。
!googlefc.AllowAdsStatusEnum: AllowAdsStatusEnum に含まれる数値。
!googlefc.ccpa.InitialCcpaStatusEnum: InitialCcpaStatusEnum に含まれる数値。

詳しくは、Google Closure ドキュメントをご覧ください。

フィールドの要約

名前	タイプ	定義
`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()`	数値	ユーザーの allow-ads のステータスに応じて `AllowAdsStatusEnum` 値を返します。
`googlefc.ccpa.getInitialCcpaStatus()`	数値	ユーザーの最初の CPRA ステータスに応じて `InitialCcpaStatusEnum` の値を返します。
`googlefc.ccpa.openConfirmationDialog(function(boolean))`	未定義	デフォルトの [販売しない] リンクがオーバーライドされている場合は、CPRA 確認ダイアログを開きます。

サイトでのテストとデバッグ

[プライバシーとメッセージ] には、実際のサイト上で特定のメッセージ（またはメッセージの組み合わせ）がどのように表示されるかをデバッグおよびテストするための機能が用意されています。

前提条件:

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

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

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

この機能をサイト（foo.com）でプレビューする方法の例を以下に示します。

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

フィールド: 説明と例

googlefc.controlledMessagingFunction {function(!Object)}

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

他のスクリプトを読み込む前にウィンドウで 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>

オファーウォールのクローズドベータ版では、message.proceed() に追加パラメータを指定して、オファーウォールのみを抑制するように指定できます。このパラメータは、googlefc.MessageTypeEnum 型の Array です。現在サポートされている列挙型は OFFERWALL のみですが、今後、メッセージタイプが追加される可能性があります。

例: 上記と同じ determineIfUserIsSubscriber() 関数があるとします。次の例では、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 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`	サポートされている同意フレームワークの API が定義され、呼び出し可能である場合は、`CONSENT_API_READY` キーを使用してコールバックキューに push された関数が実行されます。この時点で、その後に追加される `CONSENT_API_READY` キー関数の実行は同期されています。フレームワーク固有の詳細については、下記の IAB フレームワークをご覧ください。	低
`CONSENT_DATA_READY`	`CONSENT_DATA_READY` キーでコールバックキューに push された関数は、サポートされている同意フレームワーク（以前の実行から、またはユーザーが同意メッセージを操作した時点）で収集されたユーザーの同意が確認されたときに実行されます。それ以降、後から追加された `CONSENT_DATA_READY` キー関数の実行は同期されています。	高
`AD_BLOCK_DATA_READY`	広告ブロックデータがフローで使用可能になると、`AD_BLOCK_DATA_READY` キーを使ってコールバックキューに push された関数が実行されます。この時点で、その後に追加される `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>}

これにより、呼び出されたときに常に空のリストが返されるようになりました。

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}

ユーザーの allow-ads のステータスに応じて、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>

IAB TCF v2 フレームワークの下で GDPR 同意を収集するために Google の同意管理ソリューションを使用している場合は、IAB TCF v2 API を使用してください。

CONSENT_API_READY を使用できます。

コールバックキューキーを使用して、IAB TCF v2 API がページで定義されている場合にのみ、対応するコールバックが呼び出されるようにします。同期 'getTCData' コマンドで取得したユーザーの同意が使用できない可能性があるため、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.0, (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 を使用してアクセスできる場合にのみ、対応するコールバックが呼び出されるようにします。同期メソッドを使用してユーザーの同意ステータスを取得するため、この機能を '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('getTCData', 2.0, (data, success) => {
      // Do something with consent data value.
    })
  });
</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>