banner
Добавить баннер.
Формат запроса
https://adfox.yandex.ru/api/v1
? object=account
& action=add
& actionObject=banner
& campaignID=<integer>
& templateID=<integer>
& [name=<string>]
& [targetingProfileID=<integer>]
& [bannerTypeID=<integer>]
& [priority=<integer>]
& [status=<integer>]
& [isEvents=<integer>]
& [isUnplaced=<integer>]
& [backgroundColor=<string>]
& [width=<string>]
& [height=<string>]
& [imageURL=<string>]
& [hitURL=<string>]
& [target=<string>]
& [alt=<string>]
& [userN=<string>]
& [eventN=<string>]
& [hitURLN=<string>]
& [maxImpressions=<integer>]
& [maxImpressionsPerDay=<integer>]
& [maxImpressionsPerHour=<integer>]
& [maxClicks=<integer>]
& [maxClicksPerDay=<integer>]
& [maxClicksPerHour=<integer>]
& [trackingURL=<string>]
& [dateStart=<YYYY-MM-DD HH:mm>]
& [dateEnd=<YYYY-MM-DD HH:mm>]
& [showMenu=<integer>]
& [adLabel=<integer>]
& [domain=<string>]
& [sendToErir=<integer>]
& [token=<string>]
& [creativeContentType=<integer>]
& [okveds[]=<string>]
& [markingDescription=<string>]
& [targetURL=<string>]
& [textData[]=<string>]
& [mediaData[]=<{"url": "URL медиаданных", "description": "string"}>]
& [sendToErir<ParameterN>=<integer>]
|
ID кампании или флайта, в котором будет добавлен баннер. Читайте также: |
|
ID шаблона баннера. Шаблон представляет собой код баннера с переменными и определяет внешний вид и функциональные возможности баннера на сайте. Обратите внимание: если рекламная кампания ( Наличие признака у шаблона можно проверить, получив параметры шаблона (account-list-template) или список шаблонов в типе баннера (bannerType-list-template). Как посмотреть список ID шаблонов, читайте в разделе list-template. |
|
Название объекта. Может содержать русские и латинские буквы, цифры и любые символы. |
|
Профиль таргетирования позволяет объединить настройки нескольких видов таргетирования. При создании кампании или баннера можно указывать профиль, чтобы не тратить время на настройку каждого таргетирования в отдельности. Как посмотреть список ID профилей, читайте в разделе list-targetingProfile. |
|
ID типа баннера. Параметр обязателен, если не задан шаблон баннера ( Читайте также: |
|
Допустимые значения:
Значение по умолчанию: |
|
Статус объекта. Могут быть показаны только объекты, находящиеся в статусе активный. Допустимые значения:
Значение по умолчанию: |
|
Получить ссылки на события. Допустимые значения:
Значение по умолчанию: |
|
Отключить размещение баннера на площадках, созданных после добавления баннера. Допустимые значения:
Функционал зависит от подключенного в аккаунте модуля «Отключение размещения баннеров». Если модуль подключен: значение по умолчанию 1. Если модуль не подключен: значение по умолчанию 0. |
|
Цвет фона в формате HEX, например: |
|
Ширина баннера. |
|
Высота баннера. |
|
Ссылка на изображение графических баннеров, заглушку flash-баннеров. |
|
Ссылка для перехода на сайт рекламодателя. |
|
Значение параметра target для ссылки — определяет, в каком окне открыть ссылку. Допустимые значения:
|
|
Значение параметра |
|
Пользовательские параметры, где N — номер используемого параметра от 1 до 25. В каждом шаблоне определен набор переменных. Получите список используемых переменных шаблона и передайте значения к этим переменным при добавлении или редактировании баннера. Например, в шаблоне используются 2 пользовательских параметра: Значит, при добавлении или редактировании баннера необходимо в запросе передать:
|
|
Названия событий, где N — номер события от 1 до 30. В каждом шаблоне определен набор используемых событий. Получите список переменных шаблона и передайте названия к этим событиям при добавлении или редактировании баннера. |
|
Укажите URL перехода для событий, где N в названии параметра — номер события от 1 до 30. |
|
Максимальное количество показов баннера. Допустимые значения: |
|
Максимальное количество показов в сутки. Допустимые значения: |
|
Максимальное количество показов в час. Допустимые значения: |
|
Максимальное количество кликов всего. Допустимые значения: |
|
Максимальное количество кликов в сутки. Допустимые значения: |
|
Максимальное количество кликов в час. Допустимые значения: |
|
Ссылка на промерочный пиксель. В ссылке на пиксель обычно присутствует переменная, ожидающая на вход случайное число. Это число помогает защитить ссылку от кеширования в браузере. В Adfox существует макрос для подстановки случайного числа к переменной — Например, в ссылках на пиксель Adfox, параметр для подстановки случайного числа
|
|
Дата начала открутки. Значение по умолчанию: сегодня с 00:00. Формат передачи даты и времени: |
|
Дата окончания открутки. Формат передачи даты и времени: |
|
Показывать меню на баннере. Допустимые значения:
Значение по умолчанию: |
|
Показывать метку «Реклама» или «Соцреклама» на баннере. Допустимые значения:
Значение по умолчанию: |
|
Домен рядом с меткой «Реклама». |
|
Передавать данные в ЕРИР. Допустимые значения:
Значение по умолчанию: |
|
Токен баннера, который был получен от стороннего ОРД, в том числе в ОРД Яндекса по API (не через стандартный механизм маркировки в Adfox). Вы можете задать значение параметра В поле Токен можно добавить только значение токена. Не добавляйте другие символы. |
|
Тип креатива. Допустимые значения:
Значение по умолчанию: |
|
Список с ОКВЭД-ами рекламируемых товаров. Поле необязательно для заполнения, если выполняется одно из условий:
Пример передачи двух значений ОКВЭД в запросе: |
|
Описание креатива. |
|
Целевая ссылка. |
|
Массив с текстовыми данными креативов. Поле обязательно для заполнения, если не были указаны параметры |
|
Массив с медиаданными креативов. Поле обязательно для заполнения, если не были указаны параметры
Пример заполнения:
|
|
Включение/отключение для определенной переменной передачи значения параметра (креатива) в ЕРИР. Где Если вы передаете предопределенные переменные, используйте следующие названия параметров:
Чтобы включить пользовательские переменные (user1-user25), используйте Допустимые значения:
Значение по умолчанию: Поле обязательно для заполнения, если не были указаны параметры Если опция передачи параметров не включена на шаблоне (в столбце Маркировка выбрана опция Не использовать в маркировке), параметр передать не получится (ошибка |
* Обязательный параметр
Формат ответа
<response>
<status>
<code>{integer}</code>
<ID>{integer}</ID>
</status>
</response>
Параметры ответа
|
Статус обработки запроса. Значение |
|
Идентификатор объекта. |
Пример запроса и ответа
Запрос:
https://adfox.yandex.ru/api/v1?object=account&action=add&actionObject=banner&name=aptil2022&campaignID=444444
Ответ:
<response> <status> <code>0</code> <ID>456789</ID> </status> </response>
Другие действия с объектом
Читайте также о других действиях с объектом banner
:
- получить список баннеров;
- удалить баннер;
- редактировать баннер;
- получить информацию о размещении баннера;
- редактировать размещение баннера;
- получить статистику по кампаниям/баннерам/площадкам за день
- таргетировать баннер по частоте;
- таргетировать баннер по географии;
- таргетировать баннер по ключевым словам;
- таргетировать баннер по полу, возрасту, доходу;
- таргетировать баннер по пользовательским характеристикам;
- таргетировать баннер по времени.
ID кампании или флайта, в котором будет добавлен баннер.
Читайте также:
Название объекта. Может содержать русские и латинские буквы, цифры и любые символы.
Профиль таргетирования позволяет объединить настройки нескольких видов таргетирования. При создании кампании или баннера можно указывать профиль, чтобы не тратить время на настройку каждого таргетирования в отдельности.
Как посмотреть список ID профилей, читайте в разделе list-targetingProfile.
ID шаблона баннера.
Шаблон представляет собой код баннера с переменными и определяет внешний вид и функциональные возможности баннера на сайте.
Обратите внимание: если рекламная кампания (campaignID
), в которую добавляется баннер, создана с методикой учета показов (impressionsMethodID=2101
или impressionsMethodID=2102
), то шаблон должен иметь признак is_Ims=1
.
Наличие признака у шаблона можно проверить, получив параметры шаблона (account-list-template) или список шаблонов в типе баннера (bannerType-list-template).
Как посмотреть список ID шаблонов, читайте в разделе list-template.
ID типа баннера.
Параметр обязателен, если не задан шаблон баннера (templateID
).
Читайте также:
Системные шаблоны.
Параметр обязателен, если не задан шаблон баннера (templateID
).
Допустимые значения:
XML
— XML-баннер (для XML типов).
Получить ссылки на события.
Допустимые значения:
-
0
— выключено; -
1
— включено.
Значение по умолчанию: 0
.
Получить ссылки на события.
Допустимые значения:
-
0
— выключено; -
1
— включено.
Значение по умолчанию: 0
.
Цвет фона в формате HEX, например: #FFFFFF
.
Ширина баннера.
Высота баннера.
Ссылка на изображение графических баннеров, заглушку flash-баннеров.
Ссылка на flash-ролик для flash-баннеров.
Ссылка для перехода на сайт рекламодателя.
Значение параметра target для ссылки — определяет, в каком окне открыть ссылку.
Допустимые значения:
-
_blank
— открыть страницу в новом окне браузера; -
_parent
— открыть страницу в текущем окне; -
_top
— открыть страницу в полном окне браузера.
Значение параметра alt
для тега img
— альтернативный текст для изображения.
Имя параметра, используемого для передачи ссылки перехода во flash-ролик.
При разработке flash-ролика, в коде, который отвечает за обработку клика, используется параметр, ожидающий на вход ссылку для перехода.
Ссылка для перехода и имя параметра для передачи ссылки в ролик указываются при добавлении баннера в Adfox.
Имя параметра в баннере и во flash-ролике должно совпадать.
Имя параметра, используемого для передачи значения target
во flash-ролик.
При разработке flash-ролика, в коде, который отвечает за обработку клика, используется параметр, ожидающий на вход значение target
.
Ссылка для перехода и имя параметра для передачи значения target
в ролик указываются при добавлении баннера в Adfox.
Имя параметра в баннере и во flash-ролике должно совпадать.
Пользовательские параметры, где N — номер используемого параметра от 1 до 25.
В каждом шаблоне определен набор переменных. Получите список используемых переменных шаблона и передайте значения к этим переменным при добавлении или редактировании баннера.
Например, в шаблоне используются 2 пользовательских параметра: user1
и user3
с типом данных «строка».
Значит, при добавлении или редактировании баннера необходимо в запросе передать:
user1=text1&user3=text3
Названия событий, где N — номер события от 1 до 30.
В каждом шаблоне определен набор используемых событий. Получите список переменных шаблона и передайте названия к этим событиям при добавлении или редактировании баннера.
Укажите URL перехода для событий, где N в названии параметра — номер события от 1 до 30.
В зависимости от типа баннера: HTML-код, либо XML-код, либо JavaScript.
Только для XML-баннеров.
Укажите HTML-код, который покажет XML-баннер в окне предварительного просмотра баннера.
Ссылка на промерочный пиксель.
В ссылке на пиксель обычно присутствует переменная, ожидающая на вход случайное число. Это число помогает защитить ссылку от кеширования в браузере.
В Adfox существует макрос для подстановки случайного числа к переменной — %random%
.
Например, в ссылках на пиксель Adfox, параметр для подстановки случайного числа pr
, подставим к нему макрос:
http://ads.adfox.ru/166283/getCode?p1=borgd&p2=ezjv&pfb=dwsey&pr=%random%
Показывать меню на баннере.
Допустимые значения:
-
0
— не показывать меню; -
1
— показывать меню.
Значение по умолчанию: 1
.
Показывать метку «Реклама» или «Соцреклама» на баннере.
Допустимые значения:
-
0
— метка отключена; -
1
— показывать метку «Реклама»; -
2
— показывать метку «Соцреклама».
Значение по умолчанию: 0
.
Домен рядом с меткой «Реклама».
Передавать данные в ЕРИР.
Допустимые значения:
-
0
— не передавать данные в ЕРИР; -
1
— передавать данные в ЕРИР (маркировка включена).
Значение по умолчанию: 0
.
Токен баннера, который был получен от стороннего ОРД, в том числе в ОРД Яндекса по API (не через стандартный механизм маркировки в Adfox).
Вы можете задать значение параметра token
только в том случае, если sendToErir=0
.
В поле Токен можно добавить только значение токена. Не добавляйте другие символы.
Тип креатива.
Допустимые значения:
-
0
— иное; -
1
— баннер; -
2
— текстово-графический блок; -
3
— текстовый блок; -
4
— видео; -
5
— видеотрансляция в прямом эфире; -
6
— аудиотрансляция в прямом эфире; -
7
— аудиозапись.
Значение по умолчанию: 0
.
Список с ОКВЭД-ами рекламируемых товаров. Поле необязательно для заполнения, если выполняется одно из условий:
-
ОКВЭД-ы указаны на уровне рекламной кампании;
-
заказчик по договору является юридическим лицом РФ (резидентом).
Пример передачи двух значений ОКВЭД в запросе: &okveds[]=88.33&okveds[]=77.54
.
Описание креатива.
Дата начала открутки.
Значение по умолчанию: сегодня с 00:00.
Формат передачи даты и времени: YYYY-MM-DD HH:mm
Дата окончания открутки.
Формат передачи даты и времени: YYYY-MM-DD HH:mm
Целевая ссылка.
Массив с текстовыми данными креативов. Поле обязательно для заполнения, если не были указаны параметры mediaData
и sendToErir<ParameterN>
.
Включение/отключение для определенной переменной передачи значения параметра (креатива) в ЕРИР. Где <ParameterN>
— название переменной.
Если вы передаете предопределенные переменные, используйте следующие названия параметров:
-
sendToErirImageURL
— для переменной Изображение; -
sendToErirGetFLV
— для переменной FLV-ролик.
Чтобы включить пользовательские переменные (user1-user25), используйте <ParameterN>
. Где N — значение от 1 до 25. Например, sendToErirParameter2
— для дополнительной переменной user2.
Допустимые значения:
-
0
— отключить передачу данных в ЕРИР для переменной; -
1
— включить передачу данных в ЕРИР для переменной.
Значение по умолчанию: 0
.
Поле обязательно для заполнения, если не были указаны параметры mediaData
и textData
.
Если опция передачи параметров не включена на шаблоне (в столбце Маркировка выбрана опция Не использовать в маркировке), параметр передать не получится (ошибка Incorrect value (-6)
). Чтобы управлять передачей данных при создании баннера, перейдите в интерфейс Adfox и включите опцию в шаблоне.
Допустимые значения:
1≤N≤1000
, где N — от 1 до 1000 включительно.
Значение по умолчанию: 100
.
Статус объекта. Могут быть показаны только объекты, находящиеся в статусе активный.
Допустимые значения:
-
0
— активный — объект готов к началу открутки; -
1
— приостановленный — предполагается, что объект временно отключен. По умолчанию фильтры в веб-интерфейсе Adfox показывают приостановленные объекты в списке; -
2
— завершенный — предполагается, что объект завершил свою открутку. По умолчанию фильтры в веб-интерфейсе Adfox скрывают завершенные объекты.
Значение по умолчанию: 0
.
Массив с медиаданными креативов. Поле обязательно для заполнения, если не были указаны параметры textData`` и
sendToErir
URL
— ссылка проверяется на доступность перед сохранением.
description
— необязательно для заполнения.
Пример заполнения:
mediaData[]={"url": "https://avatars.mds.yandex.net/get-adfox-content/2462621/221121_adfox_2033661_5594482.379ba05374bcd6b6339273f47b5a1b64.jpeg/optimize.webp", "description": "Text_string"}
Максимальное количество показов баннера.
Допустимые значения: целое число от 1 до 2147483647
.
Максимальное количество показов в сутки.
Допустимые значения: целое число от 1 до 2147483647
.
Максимальное количество показов в час.
Допустимые значения: целое число от 1 до 2147483647
.
Максимальное количество кликов всего.
Допустимые значения: целое число от 1 до 2147483647
.
Максимальное количество кликов в сутки.
Допустимые значения: целое число от 1 до 2147483647
.
Максимальное количество кликов в час.
Допустимые значения: целое число от 1 до 2147483647
.
* Обязательный параметр