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

Введение

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

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

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

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

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

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

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

Сводные данные о полях

Имя Тип Определение
googlefc.controlledMessagingFunction функция(!Объект) Функция, которая определяет, следует ли продолжать обмен сообщениями. Эта функция поддерживается для всех типов сообщений.
googlefc.callbackQueue !Array<!Object<строка, функция()>> | !Array<функция()> | !googlefc.CallbackQueue Ссылка на очередь обратного вызова для асинхронного выполнения запросов обмена сообщениями пользователей.
googlefc.CallbackQueue !Объект Тип объекта очереди обратного вызова.
googlefc.AdBlockerStatusEnum !Object<строка, число> Перечисление, представляющее состояние блокировки рекламы пользователя.
googlefc.AllowAdsStatusEnum !Object<строка, число> Перечисление, представляющее состояние разрешения рекламы для пользователя.
googlefc.ccpa.InitialCcpaStatusEnum !Object<строка, число> Перечисление, представляющее начальный статус 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. Другие типы сообщений не затрагиваются, когда эта функция действует.

Контролируемый обмен сообщениями, специфичный для Offerwall, достигается путем передачи дополнительного параметра в message.proceed() , Array типа googlefc.MessageTypeEnum .

Пример. Это пример использования 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 должен быть получен путем прямого вызова 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"  () => 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 должен быть получен путем прямого вызова 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. Его следует использовать вместе с командой 'addEventListener' API IAB TCF v2.

Пример:

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

Использование решений 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>