Использование API тем

Предупреждение: Эта функция в настоящее время не поддерживается двумя поставщиками браузеров. Подробности об этом можно найти в разделе Позиции по стандартам ниже.

Примечание: Для использования API тем в ваших приложениях требуется процесс регистрации. Подробности о том, какие подфункции ограничены регистрацией, можно найти в разделе Регистрация.

На этой странице объясняется, как работает API тем и как его можно использовать для создания решения таргетированной рекламы на основе интересов (IBA).

Общий обзор

Предположим, у нас есть платформа для размещения рекламы, ad-tech1.example, которая встраивает объявления через <iframe> на следующие сайты издателей:

yoga.example
knitting.example
football.example

Если содержимое <iframe> с сайта ad-tech1.example реализует функцию, которая включает API тем, при загрузке каждого из сайтов браузер будет:

Определять темы интересов по URL сайта. Темы берутся из стандартной таксономии; для приведенных выше примеров URL это будут "Фитнес", "Волокно и текстильные ремесла" и "Футбол".
Помечать темы как просмотренные, что включает запись записи истории тем для каждой темы в хранилище истории тем. Каждая запись истории тем включает следующую информацию:
- Идентификатор документа (например, идентификатор текущей страницы).
- Данные для расчета тем (например, имя домена страницы).
- Время (с начала эпохи Unix), когда страница была впервые просмотрена.
- Домен(ы), где была просмотрена тема (известные как домены вызова тем).

Выбор тем интересов для влияния на выбор рекламы

Примечание: Различные реализации браузеров могут выбирать темы по-разному. Текст ниже основан на том, как Chrome в настоящее время выбирает темы, для демонстрационных целей.

В непрерывном режиме браузер будет:

Отслеживать частоту наблюдения каждой темы пользователем в каждом новом периоде. Период по умолчанию составляет одну неделю, но его продолжительность можно изменить в тестовых целях (см. Подсказки по тестированию).

Chrome распределяет каждую из 22 корневых тем (те, у которых нет предков) из таксономии по одной из двух категорий, указывая на более высокую или стандартную полезность для всей экосистемы технологий размещения рекламы. Все потомки корневых тем наследуют ту же категорию назначения от своего родителя. Назначение корневых тем категориям основано на информации о полезности, полученной Google от компаний из всей экосистемы.
Выбирать лучшие темы для каждого пользователя в конце каждого периода:
1. Chrome преобразует имена хостов домена вызова из истории посещений пользователя в темы.
2. Эти темы сортируются сначала по категории, а затем по частоте (сколько раз они были сопоставлены в имени хоста). То есть, если две темы находятся в одной категории, но имеют разную частоту, тема с большей частотой сортируется выше.
3. Chrome выбирает пять лучших тем как лучшие темы пользователя за этот период, которые могут быть переданы вызывающим сторонам.
Лучшие темы возвращаются в ad-tech1.example только в том случае, если ad-tech1.example появляется в списке домена вызова для каждой темы, как хранится в записи истории тем.

Примечание: Изначально темы не возвращаются, поэтому <iframe>, скорее всего, отобразит рекламу по умолчанию без таргетинга. Однако после окончания первого периода API начнет возвращать темы, и ad-tech1.example сможет начать показывать более релевантную рекламу на основе просмотренных тем для текущего пользователя.

Затем ad-tech1.example выбирает релевантную рекламу для показа пользователю на основе возвращенных тем.

Какие функции API включают API тем?

Следующие функции имеют двойное назначение — они возвращают лучшие темы пользователя вызывающей стороне и заставляют браузер записывать текущий визит на страницу как просмотренный вызывающей стороной, поэтому имя хоста страницы позже может использоваться в расчетах тем. Для этого их необходимо включить в <iframe> вызывающей платформы технологий размещения рекламы; <iframe> затем необходимо встроить на страницы, где вы хотите наблюдать за темой.

Вы можете указать параметр browsingTopics: true в объекте параметров вызова fetch() на платформу технологий размещения рекламы.
Вы также можете передать browsingTopics: true в объект параметров вызова конструктора Request() и передать полученный объект Request в вызов fetch().
Вы можете установить атрибут browsingtopics на <iframe> одновременно или до установки атрибута src для загрузки источника. Это можно сделать:
- Декларативно в HTML:
```
<iframe browsingtopics src="ad-tech1.example"> ... </iframe>
```
- Программно, установив соответствующее свойство HTMLIFrameElement.browsingTopics в true:
```
const iframeElem = document.querySelector("iframe");
iframeElem.browsingTopics = true;
```

При отправке запроса, связанного с одной из вышеперечисленных функций:

Заголовок Sec-Browsing-Topics отправляется вместе с запросом, содержащим лучшие темы для текущего пользователя.
Сервер технологий размещения рекламы выбирает релевантное объявление для отображения в <iframe> на основе этих тем и отправляет необходимые данные для его отображения в ответе.
Заголовок Observe-Browsing-Topics должен быть установлен в ответе на запрос — это заставляет браузер записывать текущий визит на страницу как просмотренный поставщиком вызывающей платформы технологий размещения рекламы, поэтому соответствующие темы будут записаны в записи истории тем и впоследствии будут использоваться в выборе тем.

Примечание: Важно уточнить, что это не записывает лучшие темы, отправленные в заголовке Sec-Browsing-Topics, как просмотренные. Это записывает темы, полученные из URL вызываемого сайта (т. е. сайта, где встроен <iframe> технологий размещения рекламы) как просмотренные.

Метод `browsingTopics()`

В качестве альтернативы, встроенный <iframe> может вызвать Document.browsingTopics() для возврата текущих лучших тем пользователя, которые затем могут быть возвращены платформе технологий размещения рекламы в последующем запросе fetch. Это не зависит от заголовков HTTP, но несколько менее производительно. Рекомендуется использовать один из вышеперечисленных методов с заголовками HTTP, переходя к browsingTopics() только в ситуациях, когда заголовки изменить нельзя.

Примечание: Поскольку метод browsingTopics() не зависит от заголовков HTTP, заголовок Observe-Browsing-Topics не используется для обозначения тем как просмотренных и записи/обновления записей истории тем; браузер делает это автоматически при вызове метода.

Приватные наборы тем

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

Если платформа ad-tech1.example имеет <iframe>, встроенную на tennis.example, которая включает функцию API тем, они будут наблюдать темы, такие как "Спорт" и "Теннис", для пользователя, который посещает этот сайт.
Если другая платформа технологий размещения рекламы, ad-tech2.example, имеет функцию API тем <iframe>, встроенную на «gardening.example», они будут наблюдать тему «Садоводство».

Эти платформы технологий размещения рекламы получат только темы для пользователя, которого они наблюдали. В этом примере ad-tech1.example не получит «Садоводство», а ad-tech2.example не получит «Теннис».

Другими словами, вызывающие стороны, такие как платформы технологий размещения рекламы, получают темы только для страниц, где они присутствуют. Более важно, что записанные темы интересов — это единственная информация, доступная через этот API; в отличие от файлов cookie отслеживания, никакая другая информация не может быть раскрыта.

Примеры

Использование `Document.browsingTopics()`

// Get an array of topics for this user
const topics = await document.browsingTopics();

// Request an ad creative
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

Передача параметра `browsingTopics` в `fetch()`

// Request an ad creative
const response = await fetch("https://ads.example/get-creative", {
  browsingTopics: true,
});

// Get the JSON from the response
const creative = await response.json();

// Display ad

Включение атрибута `browsingtopics` в `<iframe>`

<iframe browsingtopics src="ad-tech1.example"> ... </iframe>

Полные примеры

Демонстрация API тем: Демонстрирует, как можно использовать вызовы document.browsingTopics() для наблюдения за темой, а затем доступа к ней (см. исходный код).
Демонстрация заголовка API тем: Демонстрирует, как можно использовать запрос fetch() с заголовком Sec-Browsing-Topics для наблюдения за темой, а затем доступа к ней (см. исходный код).

Подсказки по тестированию

Chrome

Длительность эпохи по умолчанию для наблюдения за темами составляет одну неделю, что слишком долго для тестирования кода, использующего API тем. Чтобы сократить это для целей тестирования, в Chrome вы можете открыть браузер с флагом функции следующим образом:

BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s

См. Запуск Chromium с командными переключателями для получения дополнительной информации о том, как это сделать.

Вы также можете протестировать свой код API тем локально без регистрации, включив следующий флаг разработчика Chrome:

chrome://flags/#privacy-sandbox-enrollment-overrides

См. также

API тем на developers.google.com (2023)

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Topics_API/Using