Руководство разработчика API тем

Узнайте, как реализовать API Topics для наблюдения за интересующей пользователя темой и доступа к ней с помощью примеров кода.

Статус реализации

  • API Topics прошел стадию публичного обсуждения и в настоящее время доступен 99 процентам пользователей с возможностью масштабирования до 100 процентов.
  • Чтобы оставить свой отзыв об API тем, создайте проблему в объяснителе тем или примите участие в обсуждениях в бизнес-группе улучшения веб-рекламы . У объяснителя остается ряд открытых вопросов, которые еще требуют дальнейшего уточнения.
  • В графике Privacy Sandbox указаны сроки реализации Topics API и других предложений Privacy Sandbox.
  • API Topics: в последних обновлениях подробно описаны изменения и улучшения API Topics и их реализации.

Попробуйте демо

Существует две демо-версии API Topics, которые позволяют опробовать Topics в качестве одного пользователя.

Вы также можете запустить совместную работу Topics, чтобы опробовать модель классификатора Topics.

Используйте API JavaScript для доступа к темам и записывайте их в соответствии с наблюдениями.

API Topics JavaScript имеет один метод: document.browsingTopics() . Это имеет две цели:

  • Укажите браузеру, чтобы он записал текущее посещение страницы как наблюдаемое для вызывающего абонента, чтобы позже это можно было использовать для расчета тем для пользователя (для вызывающего абонента).
  • Доступ к темам пользователя, которые наблюдал вызывающий абонент.

Метод возвращает обещание, которое разрешается в массив из трех тем, по одной для каждой из трех последних эпох , в случайном порядке. Эпоха — это период времени, равный одной неделе в реализации Chrome.

Каждый объект темы в массиве, возвращаемом document.browsingTopics() имеет следующие свойства:

  • configVersion : строка, идентифицирующая текущую конфигурацию API тем, например chrome.2
  • modelVersion : строка, идентифицирующая классификатор машинного обучения, используемый для определения тем для сайта, например 4
  • taxonomyVersion : строка, определяющая набор тем, используемых браузером, например 2
  • topic : номер, идентифицирующий тему в таксономии , например 309
  • version : строка, объединяющая configVersion , taxonomyVersion и modelVersion , например chrome.2:2:4

Параметры, описанные в этом руководстве, и детали API (например, размер таксономии, количество тем, рассчитываемых в неделю, и количество тем, возвращаемых за один вызов) могут быть изменены по мере того, как мы учитываем отзывы экосистемы и совершенствуем API.

Обнаружение поддержки document.browsingTopics

Прежде чем использовать API, проверьте, поддерживается ли он браузером и доступен ли он в документе:

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
 console.log('document.browsingTopics() is supported on this page') :
 console.log('document.browsingTopics() is not supported on this page');

Доступ к темам с помощью JavaScript API

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

try {
  // Get the array of top topics for this user.
  const topics = await document.browsingTopics();
  
  // Request an ad creative, providing topics information.
  const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
  })
  
  // Get the JSON from the response.
  const creative = await response.json();
  
  // Display ad.

} catch (error) {
  // Handle error.
}

Доступ к темам без изменения состояния

document.browsingTopics() возвращает темы, наблюдаемые вызывающей стороной для текущего пользователя. По умолчанию этот метод также заставляет браузер записывать текущее посещение страницы, наблюдаемое вызывающим объектом, поэтому его позже можно использовать при вычислении тем. В Chrome 108 методу можно передать необязательный аргумент, чтобы пропустить запись посещения страницы: {skipObservation:true} .

Другими словами, {skipObservation:true} означает, что вызов метода не приведет к включению текущей страницы в расчет тем.

Используйте заголовки для доступа к темам и отмечайте их как наблюдаемые.

Вы можете получить доступ к темам, а также отметить посещения страниц как наблюдаемые с помощью заголовков запросов и ответов .

Использование подхода с заголовком может быть гораздо более производительным, чем использование API JavaScript, поскольку API требует создания iframe с перекрестным происхождением и выполнения из него вызова document.browsingTopics() . (Для вызова необходимо использовать iframe с перекрестным происхождением, поскольку контекст, из которого вызывается API, используется для обеспечения того, чтобы браузер возвращал темы, соответствующие вызывающему объекту.) В объяснителе тем есть дальнейшее обсуждение: Должен ли быть способ отправлять темы, используя Fetch в качестве заголовка запроса? .

Доступ к темам можно получить из заголовка Sec-Browsing-Topics запроса fetch() или XHR .

Установка заголовка Observe-Browsing-Topics: ?1 в ответе на запрос заставляет браузер записывать текущее посещение страницы, наблюдаемое вызывающим абонентом, поэтому его позже можно использовать при вычислении тем.

Доступ к темам и их просмотр с помощью HTTP-заголовков можно получить двумя способами:

  • fetch() : добавьте {browsingTopics: true} в параметр options запроса fetch() . Демо-заголовок темы показывает упрощенный пример этого.
  • Атрибут iframe : добавьте атрибут browsingtopics к элементу <iframe> или установите эквивалентное свойство JavaScript iframe.browsingTopics = true . Регистрируемый домен источника iframe — это домен вызывающей стороны: например, для <iframe src="https://example.com" browsingtopics></iframe> : вызывающая сторона — example.com .

Некоторые дополнительные примечания о заголовках:

  • Перенаправления будут отслеживаться, а темы, отправленные в запросе на перенаправление, будут специфичными для URL-адреса перенаправления.
  • Заголовок запроса не изменит состояние вызывающего объекта, если не существует соответствующего заголовка ответа. То есть без заголовка ответа посещение страницы не будет записано как наблюдаемое, поэтому оно не повлияет на расчет темы пользователя для следующей эпохи.
  • Заголовок ответа учитывается только в том случае, если соответствующий запрос включал заголовок темы.
  • URL-адрес запроса предоставляет регистрируемый домен, который записывается как домен вызывающего абонента.

Отказаться от вашего сайта

Вы можете отказаться от расчета тем для определенных страниц вашего сайта, включив на странице заголовок Permissions-Policy: browsing-topics=() Permissions-Policy, чтобы предотвратить расчет тем только для всех пользователей на этой странице. Последующие посещения других страниц вашего сайта это не повлияет: если вы установите политику блокировки Topics API на одной странице, это не повлияет на другие страницы.

Вы также можете контролировать, какие третьи лица имеют доступ к темам на вашей странице, используя заголовок Permissions-Policy для управления доступом третьих лиц к API тем. В качестве параметров заголовка используйте self и любые домены, которым вы хотите разрешить доступ к API. Например, чтобы полностью отключить использование API тем во всех контекстах просмотра, за исключением вашего собственного источника и https://example.com , установите следующий заголовок ответа HTTP: 

Permissions-Policy: browsing-topics=(self "https://example.com")

Следующие шаги

См. также

Ознакомьтесь с нашими ресурсами, чтобы лучше понять API Topics в Интернете.