На этой странице описаны детали реализации API тем для отслеживания и доступа к темам. Прежде чем начать реализацию решения, убедитесь, что ваш браузер настроен правильно . Подробнее о том, как пользователи отслеживают и получают доступ к темам других пользователей, можно узнать в разделе «Обзор» .
Просматривайте и изучайте темы.
Существует два способа отслеживать и получать доступ к темам пользователя: HTTP-заголовки и JavaScript API .
HTTP-заголовки
Использование HTTP-заголовков — рекомендуемый подход для отслеживания и доступа к пользовательским темам. Этот подход может быть гораздо более производительным, чем использование JavaScript API. С HTTP-заголовками URL-адрес запроса предоставляет регистрируемый домен, который записывается как домен вызывающей стороны. Именно этот домен, как считается, отслеживал темы пользователя.
Инициировать запрос
Существует два способа использования разделов «Темы» с заголовками:
- Путем доступа к заголовкам запроса и ответа в запросе
fetch(), содержащем опциюbrowsingTopics: true. - Путем доступа к заголовкам элемента iframe, содержащего атрибут
browsingtopics.
Инициируйте запрос с помощью команды fetch.
При использовании функции fetch, вызывающий API отправляет запрос, в параметре options которого содержится {browsingTopics: true} . Источником параметра URL запроса fetch является источник, который, как считается, наблюдал темы.
fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
.then((response) => {
// Process the response
});
Инициировать запрос с помощью iframe
Добавьте атрибут browsingtopics к элементу <iframe> . Браузер включит заголовок Sec-Browsing-Topics в запрос iframe, указав в качестве вызывающего элемента источник iframe.
<iframe src="https://adtech.example" browsingtopics></iframe>
Интерпретация значений заголовка запроса
В обоих подходах (fetch и iframe) темы, наблюдаемые для пользователя, можно получить на сервере из заголовка запроса Sec-Browsing-Topics . API тем автоматически включает темы пользователя в заголовок при вызове fetch() или iframe. Если API возвращает одну или несколько тем, запрос fetch к источнику, с которого были получены темы, будет включать заголовок Sec-Browsing-Topics следующего вида:
(325);v=chrome.1:1:1, ();p=P000000000
Если API не возвращает никаких тем, заголовок будет выглядеть следующим образом:
();p=P0000000000000000000000000000000
Перенаправления будут выполняться, и темы, отправляемые в запросе на перенаправление, будут специфичны для URL-адреса перенаправления. Значения заголовка Sec-Browsing-Topics дополняются, чтобы снизить риск того, что злоумышленник узнает количество тем, доступных вызывающей стороне, исходя из длины заголовка.
Обработка ответа на стороне сервера
Если ответ на запрос содержит заголовок Observe-Browsing-Topics: ?1 , это означает, что браузер должен пометить темы из соответствующего запроса как наблюдаемые и включить текущее посещение страницы в расчет тем следующего периода времени для пользователя. Включите заголовок Observe-Browsing-Topics: ?1 в ответ в вашем серверном коде:
res.setHeader('Observe-Browsing-Topics', '?1');
fetch() . Делитесь наблюдаемыми темами с партнерами.
Поскольку SSP присутствуют только на стороне издателя, DSP могут захотеть поделиться темами, которые они наблюдают на сайтах рекламодателя, со своими партнерскими SSP. Они могут сделать это, отправив запрос fetch() с заголовком topics к SSP из контекста верхнего уровня рекламодателя.
const response = await fetch("partner-ssp.example", {
browsingTopics: true
});
Отслеживайте и получайте доступ к темам с помощью JavaScript.
Метод JavaScript API Topics document.browsingTopics() предоставляет способ как отслеживать, так и получать интересующие пользователя темы в среде браузера: - Запись наблюдения: информирует браузер о том, что вызывающая сторона наблюдала за посещением пользователем текущей страницы. Это наблюдение учитывается при расчете тем для вызывающей стороны в будущих эпохах. - Доступ к темам: извлекает темы, которые вызывающая сторона ранее отслеживала для пользователя. Метод возвращает массив, содержащий до трех объектов тем, по одному для каждой из последних эпох, в случайном порядке.
Мы рекомендуем вам создать форк демонстрационного примера Topics JavaScript API и использовать его в качестве отправной точки для вашего кода.
Доступность API
Перед использованием API убедитесь, что он поддерживается и доступен:
if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
console.log('document.browsingTopics() is supported on this page');
} else {
console.log('document.browsingTopics() is not supported on this page');
}
Встроить iframe
Для вызова необходимо использовать iframe, обращающийся к другому источнику, поскольку контекст, из которого вызывается API, используется для обеспечения того, чтобы браузер возвращал темы, соответствующие вызывающей стороне. Добавьте элемент <iframe> в свой HTML-код:
<iframe src="https://example.com" browsingtopics></iframe>
Также можно динамически создавать iframe с помощью JavaScript:
const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://adtech.example/');
document.body.appendChild(iframe);
Вызовите API из iframe.
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() также заставляет браузер записывать текущее посещение страницы, зафиксированное вызывающей стороной, чтобы впоследствии использовать эту информацию при расчете тем. Методу можно передать необязательный аргумент, чтобы пропустить запись посещения страницы: {skipObservation:true} .
// current page won't be included in the calculation of topics:
const topics = await document.browsingTopics({skipObservation:true});
Понять ответ
Возвращается максимум три темы: одна или ноль за каждую из последних трех недель, в зависимости от того, наблюдались ли темы или нет. Возвращаются только темы, наблюдаемые вызывающей стороной для текущего пользователя. Вот пример того, что возвращает API:
[{
'configVersion': chrome.2,
'modelVersion': 4,
'taxonomyVersion': 2,
'topic': 309,
'version': chrome.2:2:4
}]
- configVersion : строка, определяющая версию конфигурации алгоритма тем браузера.
- modelVersion : строка, определяющая классификатор машинного обучения, используемый для определения тем.
- taxonomyVersion : строка, определяющая набор тем, используемых браузером.
- Тема : число, идентифицирующее тему в таксономии.
- version : строка, объединяющая
configVersion,taxonomyVersionиmodelVersion. Параметры, описанные в этом руководстве, и подробности API (такие как размер таксономии, количество тем, рассчитываемых в неделю, и количество тем, возвращаемых за один вызов) могут изменяться по мере учета отзывов экосистемы и доработки API.
Посетите страницу «Тестирование и запуск», чтобы узнать, какого отклика ожидать и как использовать темы в качестве дополнительного сигнала для более релевантной рекламы.
Следующие шаги
Тестируйте и работайте
Оснастка
См. также
Ознакомьтесь с нашими ресурсами, чтобы лучше понять API Topics в Интернете.
- Ознакомьтесь с демонстрациями Topics, совместными видеороликами и пошаговыми руководствами .
- Ознакомьтесь со списком флагов Chrome , которые позволяют разработчикам настраивать API тем для тестирования.
- Узнайте, как пользователи и разработчики могут управлять API.
- Ознакомьтесь с ресурсами, где можно найти технические пояснения и поддержку. Задавайте вопросы, участвуйте и делитесь отзывами.