Регистрация для получения API выбора рекламы

API выбора объявлений предоставляет релевантную для пользователей рекламу на вашем сайте без использования сторонних файлов cookie. См. статью Обзор выбора объявлений в репозитории privacy-preserving-ads .

API выбора объявлений можно использовать следующими способами:

• Продавцы , использующие платформу на стороне предложения (SSP), которые могут использовать API для предоставления высококачественной рекламы своим издателям.
• Покупатели , использующие платформу на стороне спроса (DSP), которые могут использовать API для повышения эффективности рекламных кампаний.

Чтобы приступить к использованию API выбора объявлений и протестировать комплексный поток, зарегистрируйтесь для получения ограниченной предварительной версии API выбора рекламы.

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

• Зарегистрируйтесь для ограниченной предварительной версии API выбора рекламы, зарегистрировавсь для получения пробной версии источника.
• Завершите аттестацию API, опубликовав JSON-файл аттестаций.
• Настройте среду оценки с помощью поддерживаемого поставщика облачных служб.
• Ознакомьтесь с документацией по API выбора объявлений.
• Подготовьте функции User-Defined (определяемые пользователем функции).
• Развертывание служб в Azure.
• Протестируйте API выбора рекламы на сайте.

Регистрация аттестации и альфа-регистрация

Когда и где доступна предварительная версия?

Версии Microsoft Edge, начиная с версии 130.0.2808.0 , поддерживают API выбора рекламы в ограниченной предварительной версии для разработчиков за пределами Европейской экономической зоны (ЕЭЗ) и Соединенного Королевства (Великобритания).

Флаги для тестирования

Чтобы изменить функции платформы API выбора объявлений на компьютере разработчика, используйте тестовые флаги API выбора рекламы по адресу edge://flags#edge-ad-selection-api:

Флаг API выбора рекламы включает API выбора объявлений и связанные с ним функции, такие как:

• Отчеты об атрибуции.
• Огражденные рамки.
• Общее хранилище.
• Частное агрегирование.

Требования к регистрации и аттестации и процесс

Разработчики, заинтересованные в альфа-тестировании, могут присоединиться к пробной версии для API выбора рекламы. Эта пробная версия источника позволяет комплексное тестирование функций API выбора рекламы, охватывающих использование API и развертывание защищенных образов контейнеров.

Для каждого домена верхнего уровня, который вы планируете использовать с API выбора объявлений, заполните форму регистрации пробной версии origin для этого домена, а затем отправьте форму.

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

1. Откройте пробную регистрацию источника API выбора рекламы в Microsoft Edge в новом окне или вкладке.

2. Нажмите кнопку Начать сейчас .

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

   

4. В текстовом поле Домен введите один домен верхнего уровня:

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

   • Один домен, например https://example.com, без поддержки его поддоменов.
   • Один поддомен, например https://beta.example.com.
   • Домен, например https://example.com, и его поддомены, например https://beta.example.com.

   Конечные пути и параметры запроса не поддерживаются. Если введен универсальный код ресурса (URI), имеющий конечный путь или параметр запроса, например https://example.com/path/new-feature, корневой домен (например https://example.com, ) или поддомен будут зарегистрированы, игнорируя все параметры конечного пути или запроса.

5. В разделе Поддержка поддомена нажмите кнопку Да или Нет :

   • Чтобы использовать пробную версию источника в домене (например https://example.com, ) без поддержки его поддоменов (например, https://beta.example.com), выберите Нет.
   • Чтобы использовать исходную пробную версию только в определенном поддомене (например, https://beta.example.com), выберите Нет.
   • Чтобы использовать исходную пробную версию в домене (например, https://example.com) и его поддоменах (например, https://beta.example.com), выберите Да.

6. В текстовом поле Адрес Email укажите действительный контакт разработчика для домена.

7. Нажмите кнопку Отправить .

   Маркер пробной версии источника создается для домена верхнего уровня и отправляется вам.

8. Создайте файл с именем ad-selection-attestations.jsonи разместите его в домене верхнего уровня в каталоге /.well-known/ . Например:

   https://contoso.example/.well-known/ad-selection-attestations.json

   Файл ad-selection-attestations.json должен быть опубликован в течение 30 дней после получения маркера OT. Размещение этого JSON-файла требуется, чтобы завершить аттестацию и разрешить коду доступ к API выбора объявлений, чтобы протестировать API выбора рекламы с поддерживаемыми клиентами Microsoft Edge.

Пример JSON-файла

JSON-файл аттестаций должен иметь имя ad-selection-attestations.jsonи соответствовать приведенным ниже стандартам. Ниже приведен пример ad-selection-attestations.json файла:

{
    "ad_selection_api_attestations": [
        {
            "attestation_parser_version": "2",
            "attestation_version": "2",
            "privacy_policy": [
                "https://contoso.example/privacy/"
            ],
            "ownership_token": "<Your Unique Token Here>",
            "enrollment_site": "https://contoso.example/",
            "platform_attestations": [
                {
                    "platform": "edge",
                    "attestations": {
                        "ad_selection_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "attribution_reporting_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "shared_storage_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "private_aggregation_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        }
                    }
                },
                {
                    "platform": "android",
                    "attestations": {}
                }
            ]
        }
    ]
}

Важные поля и значения

• Файл ad-selection-attestations.json должен содержать маркер пробной версии источника, который был создан и отправлен вам для этого домена верхнего уровня. "ownership_token": — это маркер пробной версии источника, который был создан при регистрации этого домена для пробной версии источника API ad Selection .

• "platform_attestations": В разделе "platform": должен иметь значение "edge" или "android".

• Файл должен содержать список API -интерфейсов (функций, связанных с API служб рекламы). "platform_attestations": В разделе допустимые члены"attestations"::

  • "ad_selection_api":— API main для логики частного аукциона.
  • "attribution_reporting_api": — Отчеты об атрибуции.
  • "shared_storage_api": — общее хранилище.
  • "private_aggregation_api": — Частное агрегирование.
  • Требования:
    • Каждая "..._api": запись должна иметь одно поле "ServiceNotUsedForIdentifyingUserAcrossSites":со значением true или false . true означает, что эта служба не используется для идентификации пользователя на разных сайтах. false означает, что эта служба используется для идентификации пользователя на разных сайтах.

Развертывание служб API выбора объявлений

API выбора объявлений использует доверенную среду выполнения (TEE) для обеспечения уровня надежности целостности данных, конфиденциальности данных и целостности кода; См . раздел Конфиденциальные вычисления: Hardware-Based доверенное выполнение для приложений и данных. Службы, предоставляемые API выбора объявлений, должны работать в TEE для защиты данных, используемых этими службами.

Службы Ad Selection Services, работающие в TEE, должны быть развернуты на облачной платформе, поддерживающей необходимые функции безопасности. Изначально службы можно развертывать в Azure с помощью конфиденциальных контейнеров ACI; См. раздел Конфиденциальные контейнеры на Экземпляры контейнеров Azure.

API выбора объявлений предоставляет различные службы, которые должны быть развернуты продавцами или покупателями.

Образы для развертывания служб

Добавьте функции User-Defined (определяемые пользователем функции) в предоставленные образы служб. Функции User-Defined могут выполнять пользовательскую бизнес-логику. Функции User-Defined выполняются в частных контейнерах в развернутых службах.

Каждый образ определяет одну службу. Некоторые образы не содержат определяемые пользователем функции и полностью состоят из предопределенного кода. Некоторые образы содержат определяемые пользователем функции в виде функций с пустым текстом или начальным кодом, которые являются соответствующими User-Defined Функций для этой службы. Заполните текст функций User-Defined на этих изображениях собственным пользовательским кодом.

Корпорация Майкрософт предоставляет образ для каждой службы, который можно развернуть у поставщика облачных служб. Это общедоступные образы, которые необходимо использовать для развертывания. Только официальные изображения от Корпорации Майкрософт могут проводить частные аукционы.

Образы для развертывания:

• Продавцов
  • Служба внешнего интерфейса продавца выбора рекламы
  • Служба аукциона по выбору объявлений
• Покупателей
  • Служба внешнего интерфейса покупателя выбора рекламы
  • Служба объявлений о выборе объявлений
  • Служба выбора объявлений K-Anonymity Service
• Продавцы и покупатели
  • Служба "Значение ключа выбора объявлений"

Услуги для продавцов

Служба	Описание
SellerFrontEnd	Предоставляет конечную точку /SelectAd HTTPS, которая получает запросы от ненадежной службы рекламы продавца для запуска потока аукциона защищенной аудитории.
Аукцион	Предоставляет конечную точку /ScoreAds , которая получает запросы от службы SellerFrontEnd , содержащей ставки, участвующие в аукционе. Возвращает значение оценки, которое используется службой SellerFrontEnd для выбора победителя.
Ключ или значение	Получает запросы от службы SellerFrontEnd , которые содержат ключи подстановки от предложений покупателей (например ad_render_urls, ). Возвращает сигналы оценки в режиме реального времени, необходимые для аукциона. Выполняется в режиме использования собственной службы (BYOS), поэтому продавцу не нужно развертывать эту службу в доверенной среде выполнения (TEE), а вместо этого можно использовать образ, предоставленный корпорацией Майкрософт.

Услуги для покупателей

Служба	Описание
BuyerFrontEnd	Предоставляет конечную точку /GetBids , которая получает запросы от службы SellerFrontEnd для запуска потока торгов.
Предложение цены	Предоставляет конечную точку /GenerateBids , которая получает запросы от службы BuyerFrontEnd для обработки торгов и создания ставки. Создает ставку, выбирает победителя и выбирает баннер для отрисовки.
Ключ или значение	Получает запросы от службы BuyerFrontEnd и возвращает данные покупателя в режиме реального времени, необходимые для торгов, соответствующие ключам поиска из Группы процентов. Такой запрос выполняется один раз для каждого рабочего процесса. Выполняется в режиме использования собственной службы (BYOS).
Ключ или значение & выбора для торгов	Получает запросы от службы торгов на выбор и возврат дополнительных рекламных баннеров (кандидатов), которые могут участвовать в торгах. Служба "Ключ-значение" & "Выбор торгов " также может возвращать дополнительные сигналы, необходимые для торгов. Служба "Ставки" может отправлять несколько запросов в службу "Выбор для торгов" & "ключ-значение " или может не отправлять запросы, так как & служба "Ключ-значение" является необязательной . Служба "Ключ и значение" & выбора торгов должна быть развернута в доверенной среде выполнения (TEE).
K-Анонимность	Собирает счетчики k-анонимности и проверяет, что победивший рекламный креатив проходит K-анонимность проверка.

Пользовательские функции

Продавцам и покупателям необходимо предоставить собственный пользовательский код в виде функций User-Defined , которые выполняются в частных контейнерах в развернутых службах. Эти функции User-Defined могут выполнять пользовательскую бизнес-логику.

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

• SellerFrontEnd и Аукцион.
• BuyerFrontend, Bidding и K-Anonymity.

Некоторые из этих служб принимают входные данные, которые являются рабочим файлом JavaScript, определяющим функции User-Defined.

Функции User-Defined для продавцов

Определяемая пользователем функция	Служба, в которой выполняется определяемая пользователем функция	Описание
scoreAd()	Аукцион	Создает оценку для ставки каждого покупателя или отклоняет ставку. Затем эта оценка используется службой SellerFrontEnd , чтобы выбрать победителя из всех покупателей.
reportResult()	SellerFrontEnd	Для создания отчетов на уровне событий. Выполняется в службе SellerFrontEnd после выбора окончательного победителя. Уведомляет продавца о победившего участнике и предоставляет стоимость предложения.

функции User-Defined для покупателей

Определяемая пользователем функция	Служба, в которой выполняется определяемая пользователем функция	Описание
generateBids()	Предложение цены	Создает ставку и выбирает баннер, который будет отображаться.
reportWin()	SellerFrontEnd	Для создания отчетов на уровне событий. Выполняется в службе SellerFrontEnd , если ставка покупателя выигрывает аукцион. Уведомляет покупателя о том, что он выиграл аукцион, и создает URL-адреса уведомлений, которые будут активированы позже, например во время отрисовки баннера или других событий клиента.
getValues()	Ключ или значение & выбора для торгов	Выполняется в службе "Ключ-значение" & выбор торгов , если покупатель использует ее. Позволяет выполнять пользовательский код для поиска и выбора данных.

Руководство по развертыванию

Чтобы развернуть службу API выбора объявлений в Azure, выполните следующие действия.

1. Создайте учетную запись Azure и подписку в Microsoft Azure.

2. Выберите параметр Конфиденциальные контейнеры ACO .

3. Перейдите к скриптам развертывания Terraform в новом окне или вкладке, а затем скачайте скрипты развертывания Terraform и просмотрите документацию по развертыванию. Заметка: Убедитесь, что хэш загруженного образа соответствует хэшу в скачаемом скрипте.

4. Скрипты Terraform уже содержат ссылки на общедоступные изображения, предоставляемые корпорацией Майкрософт. Выберите необходимые службы и разверните их, выполнив действия, описанные в пакете readme.md.

   1. Установите все определенные флаги для своей среды, включая расположения рабочих листов аукциона.

   2. Настройте все предварительные требования и подготовьте все средства для развертывания.

   3. Создайте ресурсы Azure и запустите скрипт Terraform, который завершит развертывание.

5. Разработка рабочих модулей, включая user-defined-function (UDF) и запуск служб API выбора объявлений.

Использование API выбора объявлений на веб-сайте

Чтобы начать использовать API выбора рекламы, продавцам и покупателям необходимо изменить код JavaScript своих веб-сайтов, который выполняется, когда браузер является Microsoft Edge.

• Продавцы. Чтобы проводить частные аукционы, получать группы интересов и создавать отчеты, обновите код на веб-сайтах издателей.

• Покупатели. Чтобы создать группы интересов и сохранить их в браузере, обновите код на веб-сайтах ваших рекламных партнеров. Механизм делегирования можно использовать для ограничения и разрешения создания группы интересов в сторонних доменах.

Дополнительные сведения о доступных методах API и примеры кода см. в разделе Сведения об API выбора рекламы.

Предоставьте отзыв о пробной версии источника

Чтобы оставить отзыв о пробной версии api выбора рекламы, создайте новую проблему в репозитории WICG/privacy-preserving-ads GitHub:

• Чтобы просмотреть существующие проблемы, перейдите на вкладку Проблемы репозитория WICG/privacy-preserving-ads.

• Чтобы отправить новую проблему, перейдите в форму новой проблемы.

См. также

Пробные версии источника:

• Пробная регистрация источника API выбора рекламы в Microsoft Edge
• Использование пробных версий источника в Microsoft Edge

Проектная и техническая документация:

• Обзор выбора рекламы
• Предложение по API выбора рекламы
• Сведения об API выбора рекламы

Образы для развертывания:

• Продавцов
  • Служба внешнего интерфейса продавца выбора рекламы
  • Служба аукциона по выбору объявлений
• Покупателей
  • Служба внешнего интерфейса покупателя выбора рекламы
  • Служба объявлений о выборе объявлений
  • Служба выбора объявлений K-Anonymity Service
• Продавцы и покупатели
  • Служба "Значение ключа выбора объявлений"

Сценарии развертывания:

• Скрипты развертывания Terraform

Доверенная среда выполнения (TEE):

• Конфиденциальные вычисления: Hardware-Based доверенное выполнение для приложений и данных

Лазурный:

• Microsoft Azure
• Конфиденциальные контейнеры в Экземпляры контейнеров Azure