Запрос

Ad Placement API может быть вызван как со стороны клиента, так и со стороны сервера.

При использовании реализации на стороне клиента браузер может выполнить предварительный запрос. Если вы хотите избежать этого, в заголовке запроса используйте Content-Type: text/plain. Это гарантирует, что браузер квалифицирует запрос как "простой" и, следовательно, пропустит предполётный запрос.

Кроме того, при вызове API на стороне клиента, IP не требуется, так как может быть сложно определить IP с помощью фронтенда и Javascript. Вместо этого наш API определяет IP из соединения при выполнении запроса.

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

Независимо от того, используется ли клиент или сервер, если передается IP-адрес, он будет приоритетнее того, который мы обнаружим.

Для того чтобы выполнить запрос к API размещения рекламы, вам необходимо передать два объекта: user и zones. Запрос выполняется в формате JSON с помощью HTTP POST.

пользователь

Параметр	Требуется?	Описание
id	Нет	Идентификатор пользователя
ip	Рекомендуем	IP-адрес пользователя.
ua	Да	Агент пользователя: Строка, содержащая информацию о браузере/приложении и устройстве/ОС пользователя.
язык	Нет	Устанавливает язык запроса, используя стандартный двухсимвольный код ISO плюс дополнительный двухсимвольный код региона. Например, en-us для английского языка Соединенных Штатов.
реферер	Нет	Адрес сайта, на котором будет показано объявление.
el	Нет	Электронная почта пользователя в Base64-кодировке.
разрешение экрана	Нет	Разрешение экрана устройства, используемого пользователем
ориентация окна	Нет	Этот параметр должен быть "портретным", если сайт имеет мобильную верстку, и "ландшафтным", если это десктопная версия.
gdpr	Нет	Расширения, рекомендуемые для защиты конфиденциальности (Объект).

user.gdpr

Параметр	Описание
gdpr	Этот параметр должен быть 0, если звонящий считает, что пользователь не подпадает под GDPR, и 1, если пользователь подпадает под GDPR.
согласие	Это строка согласия, требуемая стандартами IAB.

зоны

Параметр	Требуется?	Описание
id	Да	Идентификатор рекламной зоны
суб	Нет	Sub ID рекламной зоны
ключевые слова	Нет	Любые ключевые слова, связанные с трафиком, которые могут соответствовать определенному типу рекламы. Если ключевые слова отсутствуют, для подбора будет использоваться URL сайта
пользовательский_таргетинг	Нет	Пользовательские значения зон (Объект)

zones.custom_targeting

Параметр	Описание
ex_av	Это должно быть 0, если возраст не определен, 1, если возраст подтвержден, и 2, если возраст не подтвержден

Пример

В одном запросе можно запросить множество рекламных зон. Каждая зона будет иметь свой ID, как показано в примере ниже.

{
    "user": {
        "id": "abdef8u9",
        "ip": "10.42.0.1",
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "language": "en-US",
        "referer": "https://blabla.com",
        "gdpr" : {
                "gdpr" : 1,
                "consent": "CPAoZRHPArq3hBcADBENBJCgAAAAAAAAAAqIHKQAAOUgAAAA"
        }
    },
    "zones": [
        {
            "id": 4031007,
            "sub": 111,
            "keywords": "humour, general"
        },
        {
            "id": 4031015,
            "sub": 222 
        },
        {
            "id": 4031019,
            "sub": 222             
        }
    ]
}