Конфиденциальность и обмен сообщениями JavaScript API

Введение

Этот API предоставляет инструменты для взаимодействия с сообщениями, предлагаемыми на вкладке «Конфиденциальность и обмен сообщениями». С его помощью вы можете:

  • запретить обмен сообщениями для любого пользователя
  • запросить статус блокировки рекламы пользователя
  • разрешить пользователю отозвать согласие (если применимо)

Вы также можете использовать эти инструменты для сбора согласия пользователей с использованием некоторых стандартных отраслевых протоколов:

В этих случаях статус согласия передается через эти API.

Вы можете развернуть эту функцию обмена сообщениями с пользователями на своем сайте несколькими способами:

  1. В большинстве случаев вам вообще не нужно переустанавливать теги — ваш существующий тег издателя Google или тег AdSense развертывает пользовательские сообщения, как только сообщение публикуется в соответствующем продукте.
  2. Если вы используете сообщение о восстановлении блокировки рекламы, вам необходимо явно добавить тег блокировки рекламы на свою страницу. Дополнительные сведения см. в инструкциях по добавлению тегов в Менеджере рекламы и AdSense .

googlefc — это глобальное пространство имен, которое функция обмена сообщениями пользователя использует для своего API в Window JavaScript.

Полевые сводки

Имя Тип Определение
googlefc.controlledMessagingFunction функция(!Объект) Функция, которая определяет, следует ли продолжить обмен сообщениями. Эта функция поддерживается для всех типов сообщений.
googlefc.callbackQueue !Массив<!Объект<строка, функция()>> | !Массив<функция()> | !googlefc.CallbackQueue Ссылка на очередь обратного вызова для асинхронного выполнения запросов обмена сообщениями пользователя.
googlefc.CallbackQueue !Объект Тип объекта очереди обратного вызова.
googlefc.AdBlockerStatusEnum !Объект<строка, число> Перечисление для представления состояния блокировщика рекламы пользователя.
googlefc.AllowAdsStatusEnum !Объект<строка, число> Перечисление для представления состояния разрешения рекламы пользователем.
googlefc.ccpa.InitialCcpaStatusEnum !Объект<строка, число> Перечисление для представления начального статуса CPRA пользователя.
googlefc.ccpa.overrideDnsLink неопределенный | логический Логическое значение, для которого можно установить значение true, чтобы использовать пользовательскую ссылку «Не продавать».

Резюме методов

Имя Тип возврата Определение
googlefc.showRevocationMessage() неопределенный Очищает запись о согласии и перезагружает скрипт googlefc , чтобы отобразить сообщение о согласии, применимое к пользователю.
googlefc.getAdBlockerStatus() число Возвращает значение в AdBlockerStatusEnum в зависимости от статуса блокировки рекламы пользователя.
googlefc.getAllowAdsStatus() число Возвращает значение в AllowAdsStatusEnum в зависимости от статуса разрешения рекламы для пользователя.
googlefc.ccpa.getInitialCcpaStatus() число Возвращает значение в InitialCcpaStatusEnum в зависимости от начального статуса CPRA пользователя.
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-адрес страницы.

Когда вы определяете 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 следует подавлять, указав дополнительный параметр для message.proceed() . Этот параметр представляет собой Array типа googlefc.MessageTypeEnum . На сегодняшний день поддерживается только перечисление OFFERWALL , но в будущем могут быть добавлены дополнительные типы сообщений.

Пример: предположим, что у вас есть та же функция determineIfUserIsSubscriber() , что и выше. Это пример использования 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 , выполняются, когда API для поддерживаемых платформ согласия определены и доступны для вызова. С этого момента выполнение любых впоследствии добавленных функций с ключом CONSENT_API_READY является синхронным. См. разделы о платформах IAB ниже для получения подробной информации о конкретных платформах. Низкий
CONSENT_DATA_READY Функции, помещаемые в очередь обратного вызова с ключом CONSENT_DATA_READY , выполняются, когда известно согласие пользователя, полученное в рамках поддерживаемой структуры согласия (либо из предыдущего выполнения, либо после того, как пользователь взаимодействует с сообщением о согласии). С этого момента выполнение любых впоследствии добавленных функций с ключом CONSENT_DATA_READY является синхронным. Высокий
AD_BLOCK_DATA_READY Функции, помещенные в очередь обратного вызова с ключом AD_BLOCK_DATA_READY , выполняются, когда в потоке становятся доступны данные блокировки рекламы. С этого момента выполнение любых добавленных впоследствии функций с ключом AD_BLOCK_DATA_READY является синхронным. Высокий
INITIAL_CCPA_DATA_READY Функции, помещенные в очередь обратного вызова с помощью INITIAL_CCPA_DATA_READY , выполняются, когда данные CPRA становятся доступными в потоке. Обратите внимание, что любой последующий запрос данных CPRA должен быть получен путем прямого вызова US Privacy API ( __uspapi ). Середина

googlefc.CallbackQueue {!Object}

Резюме метода:

Имя Тип Параметр Тип возврата Роль
push(data) число data : пара ключ-значение с ключом в качестве одного из типов доступности данных и значением в виде выполняемой функции JavaScript. Допустимые ключи доступности данных: 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}

Возвращает значение в InitialCcpaStatusEnum в зависимости от статуса CPRA пользователя. Ключ, который должен быть указан для этой функции, — 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 для управления согласием для получения согласия GDPR в рамках IAB TCF v2, вам следует использовать API IAB TCF v2 .

Вы можете использовать CONSENT_API_READY

ключ очереди обратного вызова, чтобы гарантировать, что соответствующие обратные вызовы вызываются только тогда, когда на странице определен API IAB TCF v2. Это следует использовать в сочетании с командой IAB TCF v2 API 'addEventListener' поскольку согласие пользователя, полученное с помощью синхронной команды '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_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>

Использование решений Google для управления согласием с платформой IAB GPP для CPRA

Если вы используете решения Google для управления согласием, чтобы получить отказ от CPRA в рамках IAB GPP, вам следует использовать IAB GPP API .

Из-за того, что правила CPRA предусматривают возможность отказа, вы можете использовать ключ очереди обратного вызова CONSENT_API_READY или CONSENT_DATA_READY , чтобы убедиться, что API IAB GPP доступен для вызова и возвращает данные согласия во время вызова обратного вызова.

<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>

Использование решений Google для управления согласием с платформой IAB GPP для CPRA с настраиваемой ссылкой «Не продавать».

Если вы используете решения Google по управлению согласием для получения отказа от CPRA в рамках IAB GPP, можно предоставить пользовательскую ссылку «Не продавать», установив для флага 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>