banner

Редактировать параметры баннера.

Формат запроса

https://adfox.yandex.ru/api/v1
  ? object=banner
  & action=modify
  & actionObject=banner
  & objectID=<integer>
  & [name=<string>]
  & [targetingProfileID=<integer>]
  & [dateStart=<YYYY-MM-DD HH:mm>]
  & [dateEnd=<YYYY-MM-DD HH:mm>]
  & [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>]
  & [videoResolution=<string>]
  & [videoDuration=<float>]
  & [maxImpressions=<integer>]
  & [maxImpressionsPerDay=<integer>]
  & [maxImpressionsPerHour=<integer>]
  & [maxClicks=<integer>]
  & [maxClicksPerDay=<integer>]
  & [maxClicksPerHour=<integer>]
  & [trackingURL=<string>]
  & [showMenu=<integer>]
  & [adLabel=<integer>]
  & [domain=<string>]
  & [sendToErir=<integer>]
  & [token=<string>]
  & [creativeContentType=<integer>]
  & [markingDescription=<string>]
  & [markingKktu=<string>]
  & [markingCommonDescription=<string>]
  & [markingSendRegionsType=<string>]
  & [markingSelectedRegions=<integer>]
  & [targetURL=<string>]
  & [textData[]=<string>]
  & [mediaData[]=<{"url": "media data URL", "description": "string"}>]
  & [sendToErir<ParameterN>=<integer>]
  & [sendToErirContentType<ParameterN>=<string>]
  & [sendToErirDescription<ParameterN>=<string>]

objectID*

ID объекта, над которым производится действие.

name

Название баннера.

Может содержать русские и латинские буквы, цифры и любые символы.

targetingProfileID

ID профиля таргетирования.

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

Как посмотреть список ID профилей, читайте в разделе list-targetingProfile.

dateStart

Дата начала открутки.

Формат передачи даты и времени: YYYY-MM-DD HH:mm.

dateEnd

Дата окончания открутки.

Формат передачи даты и времени: YYYY-MM-DD HH:mm.

priority

Приоритет.

Допустимые значения: 1≤N≤1000, где N — от 1 до 1000 включительно.

status

Статус объекта. Могут быть показаны только объекты, находящиеся в статусе активный.

Допустимые значения:

  • 0 — активный. Объект готов к началу открутки.
  • 1 — приостановленный. Предполагается, что объект временно отключен. По умолчанию фильтры в веб-интерфейсе Adfox показывают приостановленные объекты в списке.
  • 2 — завершенный. Предполагается, что объект завершил свою открутку. По умолчанию фильтры в веб-интерфейсе Adfox скрывают завершенные объекты.

isEvents

Получить ссылки на события.

Допустимые значения:

  • 0 — выключено;
  • 1 — включено.

Значение по умолчанию: 0.

isUnplaced

Отключить размещение баннера на площадках, созданных после добавления баннера.

Допустимые значения:

  • 0 — выключено;
  • 1 — включено.

Функционал зависит от подключенного в аккаунте модуля «Отключение размещения баннеров».

Значение по умолчанию:

  • 0 — если модуль не подключен;
  • 1 — если модуль подключен.

backgroundColor

Цвет фона в формате HEX, например: #FFFFFF.

width

Ширина баннера.

height

Высота баннера.

imageURL

Ссылка на изображение графических баннеров, заглушку flash-баннеров.

hitURL

Ссылка для перехода на сайт рекламодателя.

target

Значение параметра target для ссылки определяет, в каком окне открыть ссылку.

Допустимые значения:

  • _blank — открыть страницу в новом окне браузера;
  • _parent — открыть страницу в текущем окне;
  • _top — открыть страницу в полном окне браузера.

alt

Значение параметра alt для тега img — альтернативный текст для изображения.

userN

Пользовательские параметры, где N — номер используемого параметра от 1 до 25.

В каждом шаблоне определен набор переменных. Получите список используемых переменных шаблона и передайте значения к этим переменным при добавлении или редактировании баннера.

Например, в шаблоне используются два пользовательских параметра: user1 и user3 с типом данных «строка». Значит, при добавлении или редактировании баннера в запросе необходимо передать: user1=text1&user3=text3.

eventN

Названия событий, где N — номер события от 1 до 30.

В каждом шаблоне определен набор используемых событий. Получите список переменных шаблона и передайте названия к этим событиям при добавлении или редактировании баннера.

hitURLN

Укажите URL перехода для событий, где N в названии параметра — номер события от 1 до 30.

videoResolution

Качество видео.

Допустимые значения:

  • 240p
  • 360p
  • 480p
  • 720p
  • 1080p

Значение по умолчанию: 480p.

videoDuration

Длительность видео в секундах.

Можно задать длительность до тысячных долей секунды, например 11.325.

maxImpressions

Максимальное количество показов.

Допустимые значения: целое число от 1 до 2147483647.

maxImpressionsPerDay

Максимальное количество показов в сутки.

Допустимые значения: целое число от 1 до 2147483647.

maxImpressionsPerHour

Максимальное количество показов в час.

Допустимые значения: целое число от 1 до 2147483647.

maxClicks

Максимальное количество кликов всего.

Допустимые значения: целое число от 1 до 2147483647.

maxClicksPerDay

Максимальное количество кликов в сутки.

Допустимые значения: целое число от 1 до 2147483647.

maxClicksPerHour

Максимальное количество кликов в час.

Допустимые значения: целое число от 1 до 2147483647.

trackingURL

Ссылка на промерочный пиксель.

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

В Adfox существует макрос для подстановки случайного числа к переменной — %random%.

Например, подставим макрос к параметру для подстановки случайного числа pr в ссылках на пиксель Adfox:

http://ads.adfox.ru/166283/getCode?p1=borgd&p2=ezjv&pfb=dwsey&pr=%random%

showMenu

Показывать меню на баннере.

Допустимые значения:

  • 0 — не показывать меню;
  • 1 — показывать меню.

adLabel

Показывать метку «Реклама» или «Соцреклама» на баннере.

Допустимые значения:

  • 0 — метка отключена;
  • 1 — показывать метку «Реклама»;
  • 2 — показывать метку «Соцреклама».

domain

Домен рядом с меткой «Реклама».

sendToErir

Передавать данные в ЕРИР.

Допустимые значения:

  • 0 — не передавать данные в ЕРИР;
  • 1 — передавать данные в ЕРИР (маркировка включена).

Примечание

  • При изменении значения параметра с 0 на 1 объект отправляется в ЕРИР.

  • При изменении значения параметра с 1 на 0 маркировка в Adfox отключается. При этом ранее переданные в ЕРИР данные по объекту сохраняются и не удаляются.

token

Токен баннера, который был получен от стороннего ОРД, в том числе в ОРД Яндекса по API (не через стандартный механизм маркировки в Adfox).

Вы можете задать значение параметра token только в том случае, если sendToErir=0.

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

creativeContentType

Форма распространения рекламы.

Допустимые значения:

  • 1 — баннер;
  • 2 — текстово-графический блок;
  • 3 — текстовый блок;
  • 4 — видеоролик;
  • 5 — видеотрансляция в прямом эфире;
  • 6 — аудиотрансляция в прямом эфире;
  • 7 — аудиозапись;
  • 8 — текстовый блок с видео;
  • 9 — текстово-графический блок с видео;
  • 10 — текстовый блок с аудио;
  • 11 — текстово-графический блок с аудио;
  • 12 — текстовый блок с аудио и видео;
  • 13 — текстово-графический блок с аудио и видео;
  • 14 — HTML5-баннер.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

markingDescription

Описание креатива.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

markingKktu

Код справочника ККТУ. Обязательный параметр, если включена маркировка.

Если в параметре markingKktu указано значение 30.15.1, то параметр markingCommonDescription становится обязательным.

Список кодов можно получить с помощью метода bannerKktu.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

markingCommonDescription

Общее описание объекта рекламирования.

Обязательный параметр, если в параметре markingKktu указано значение 30.15.1.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

markingSendRegionsType

Регион показа рекламы.

Допустимые значения:

  • none — значение Не передавать. Информация о регионах показа не будет передаваться в ЕРИР.
  • all — значение Вся Россия. Баннер показывается на всей территории России.
  • selected — значение Указать регионы вручную. При передаче selected обязательно укажите ID выбранных регионов в параметре markingSelectedRegions.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

markingSelectedRegions

ID региона показа рекламы.

Обязательный параметр, если в параметре markingSendRegionsType выбрано значение selected.

Если нужно задать несколько регионов, добавьте несколько markingSendRegionsType в параметрах запроса. Пример для регионов показа рекламы с кодами 9, 21 и 63:

&markingSendRegionsType=9&markingSendRegionsType=21&markingSendRegionsType=63

Список регионов можно получить с помощью метода erirRegions.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

targetURL

Целевые ссылки. Допустимо указывать несколько ссылок в поле через разделитель \n, в URL он кодируется как %0A. Каждая ссылка должна начинаться с протокола. Длина одной ссылки не может превышать 2000 символов.

Пример:

`targetURL=http://site1.ru%0Ahttp://site2.ru`

Или же можно передавать с помощью изменения названия переменной:

`&targetURL[]=http://site1.ru`

`&targetURL[]=http://site2.ru`

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

textData[]

Массив с текстовыми данными креативов. Поле обязательно для заполнения, если не были указаны параметры mediaData и sendToErir<ParameterN>.

Действия с массивом:

  • Добавление элемента: передайте все предыдущие элементы и все новые элементы.
  • Удаление элемента: передайте все элементы, кроме удаляемого.
  • Полная очистка массива: передайте массив с пустым значением, например textData[]=.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

mediaData[]

Массив с медиаданными креативов. Поле обязательно для заполнения, если не были указаны параметры textData и sendToErir<ParameterN>.

URL-ссылка проверяется на доступность перед сохранением. Поле description необязательно для заполнения.

Пример заполнения:

mediaData[]={"url": "https://avatars.mds.yandex.net/get-adfox-content/2462621/221121_adfox_2033661_5594482.379ba05374bcd6b6339273f47b5a1b64.jpeg/optimize.webp", "description": "Text_string"}

Действия с массивом:

  • Добавление элемента: передайте все предыдущие элементы и все новые элементы.
  • Удаление элемента: передайте все элементы, кроме удаляемого.
  • Полная очистка массива: передайте массив с пустым значением, например mediaData[]=.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

sendToErir<ParameterN>

Включение/отключение для определенной переменной передачи значения параметра (креатива) в ЕРИР, где <ParameterN> — название переменной.

Если вы передаете предопределенные переменные, используйте следующие названия параметров:

  • sendToErirImageURL — для переменной Изображение;
  • sendToErirGetFLV — для переменной FLV-ролик.

Чтобы включить пользовательские переменные (user1-user25), используйте <ParameterN>, где N — значение от 1 до 25. Например, sendToErirParameter2 — для дополнительной переменной user2.

Допустимые значения:

  • 0 — отключить передачу данных в ЕРИР для переменной;
  • 1 — включить передачу данных в ЕРИР для переменной.

Значение по умолчанию: 0.

Поле обязательно для заполнения, если не были указаны параметры mediaData и textData.

Ошибка Incorrect value (-6)

Не включена опция передачи параметров на шаблоне (в столбце Маркировка выбрана опция Не использовать в маркировке) — параметр передать не получится (ошибка Incorrect value (-6)). Чтобы управлять передачей данных при создании баннера, перейдите в интерфейс Adfox и включите опцию в шаблоне.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

sendToErirContentType<ParameterN>

Тип файла, загруженного в переменную с включенной передачей в ЕРИР.

Список допустимых значений:

  • image
  • video
  • audio
  • zip

При выборе image параметр с описанием объекта креатива sendToErirDescription<ParameterN> становится обязательным.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

sendToErirDescription<ParameterN>

Описание объекта креатива для той переменной, в которую загружен файл. Обязательный параметр, если в параметре sendToErirContentType<ParameterN> указано значение image.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

Формат ответа

<response>
<status>
  <code>{integer}</code>
</status>
</response>

Параметры ответа

code

Статус обработки запроса. Значение 0 — запрос выполнен успешно. Расшифровку смотрите в разделе Обработка ошибок.

Пример запроса и ответа

Запрос:

https://adfox.yandex.ru/api/v1?object=banner&action=modify&actionObject=banner&objectID=234532

Ответ:

<response>
<status>
  <code>0</code>
</status>
</response>

Другие действия с объектом

Читайте также о других действиях с объектом banner:

ID объекта, над которым производится действие.

Название объекта.

Может содержать русские и латинские буквы, цифры и любые символы.

ID профиля таргетирования.

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

Как посмотреть список ID профилей, читайте в разделе list-targetingProfile.

Дата начала открутки.

Формат передачи даты и времени: YYYY-MM-DD HH:mm.

Значение по умолчанию: сегодня с 00:00.

Дата окончания открутки.

Формат передачи даты и времени: YYYY-MM-DD HH:mm.

Приоритет.

Допустимые значения: 1≤N≤1000, где N — от 1 до 1000 включительно.

Статус объекта. Могут быть показаны только объекты, находящиеся в статусе активный.

Допустимые значения:

  • 0 — активный. Объект готов к началу открутки.
  • 1 — приостановленный. Предполагается, что объект временно отключен. По умолчанию фильтры в веб-интерфейсе Adfox показывают приостановленные объекты в списке.
  • 2 — завершенный. Предполагается, что объект завершил свою открутку. По умолчанию фильтры в веб-интерфейсе Adfox скрывают завершенные объекты.

Получить ссылки на события.

Допустимые значения:

  • 0 — выключено;
  • 1 — включено.

Значение по умолчанию: 0.

Отключить размещение баннера на площадках, созданных после добавления баннера.

Допустимые значения:

  • 0 — выключено;
  • 1 — включено.

Функционал зависит от подключенного в аккаунте модуля «Отключение размещения баннеров».

Значение по умолчанию:

  • 0 — если модуль не подключен;
  • 1 — если модуль подключен.

Цвет фона в формате HEX, например: #FFFFFF.

Ширина баннера.

Высота баннера.

Ссылка на изображение графических баннеров, заглушку flash-баннеров.

Ссылка для перехода на сайт рекламодателя.

Значение параметра target для ссылки определяет, в каком окне открыть ссылку.

Допустимые значения:

  • _blank — открыть страницу в новом окне браузера;
  • _parent — открыть страницу в текущем окне;
  • _top — открыть страницу в полном окне браузера.

Значение параметра alt для тега img — альтернативный текст для изображения.

Пользовательские параметры, где N — номер используемого параметра от 1 до 25.

В каждом шаблоне определен набор переменных. Получите список используемых переменных шаблона и передайте значения к этим переменным при добавлении или редактировании баннера.

Например, в шаблоне используются два пользовательских параметра: user1 и user3 с типом данных «строка». Значит, при добавлении или редактировании баннера в запросе необходимо передать: user1=text1&user3=text3.

Названия событий, где N — номер события от 1 до 30.

В каждом шаблоне определен набор используемых событий. Получите список переменных шаблона и передайте названия к этим событиям при добавлении или редактировании баннера.

Укажите URL перехода для событий, где N в названии параметра — номер события от 1 до 30.

Максимальное количество показов баннера.

Допустимые значения: целое число от 1 до 2147483647.

Максимальное количество показов в сутки.

Допустимые значения: целое число от 1 до 2147483647.

Максимальное количество показов в час.

Допустимые значения: целое число от 1 до 2147483647.

Максимальное количество кликов всего.

Допустимые значения: целое число от 1 до 2147483647.

Максимальное количество кликов в сутки.

Допустимые значения: целое число от 1 до 2147483647.

Максимальное количество кликов в час.

Допустимые значения: целое число от 1 до 2147483647.

Ссылка на промерочный пиксель.

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

В Adfox существует макрос для подстановки случайного числа к переменной — %random%.

Например, подставим макрос к параметру для подстановки случайного числа pr в ссылках на пиксель Adfox:

http://ads.adfox.ru/166283/getCode?p1=borgd&p2=ezjv&pfb=dwsey&pr=%random%

Показывать меню на баннере.

Допустимые значения:

  • 0 — не показывать меню;
  • 1 — показывать меню.

Показывать метку «Реклама» или «Соцреклама» на баннере.

Допустимые значения:

  • 0 — метка отключена;
  • 1 — показывать метку «Реклама»;
  • 2 — показывать метку «Соцреклама».

Домен рядом с меткой «Реклама».

Передавать данные в ЕРИР.

Допустимые значения:

  • 0 — не передавать данные в ЕРИР;
  • 1 — передавать данные в ЕРИР (маркировка включена).

Тип файла, загруженного в переменную с включенной передачей в ЕРИР.

Список допустимых значений:

  • image
  • video
  • audio
  • zip

При выборе image параметр с описанием объекта креатива sendToErirDescription<ParameterN> становится обязательным.

Описание объекта креатива для той переменной, в которую загружен файл. Обязательный параметр, если в параметре sendToErirContentType<ParameterN> указано значение image.

Токен баннера, который был получен от стороннего ОРД, в том числе в ОРД Яндекса по API (не через стандартный механизм маркировки в Adfox).

Вы можете задать значение параметра token только в том случае, если sendToErir=0.

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

Форма распространения рекламы.

Допустимые значения:

  • 1 — баннер;
  • 2 — текстово-графический блок;
  • 3 — текстовый блок;
  • 4 — видеоролик;
  • 5 — видеотрансляция в прямом эфире;
  • 6 — аудиотрансляция в прямом эфире;
  • 7 — аудиозапись;
  • 8 — текстовый блок с видео;
  • 9 — текстово-графический блок с видео;
  • 10 — текстовый блок с аудио;
  • 11 — текстово-графический блок с аудио;
  • 12 — текстовый блок с аудио и видео;
  • 13 — текстово-графический блок с аудио и видео;
  • 14 — HTML5-баннер.

Качество видео.

Допустимые значения:

  • 240p
  • 360p
  • 480p
  • 720p
  • 1080p

Значение по умолчанию: 480p.

Длительность видео в секундах.

Можно задать длительность до тысячных долей секунды, например 11.325.

Описание креатива.

Код справочника ККТУ. Обязательный параметр, если включена маркировка.

Если в параметре markingKktu указано значение 30.15.1, то параметр markingCommonDescription становится обязательным.

Список кодов можно получить с помощью метода bannerKktu.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

Общее описание объекта рекламирования.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

Регион показа рекламы.

Допустимые значения:

  • none — значение Не передавать. Информация о регионах показа не будет передаваться в ЕРИР.
  • all — значение Вся Россия. Баннер показывается на всей территории России.
  • selected — значение Указать регионы вручную. При передаче selected обязательно укажите ID выбранных регионов в параметре markingSelectedRegions.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

ID региона показа рекламы.

Обязательный параметр, если в параметре markingSendRegionsType выбрано значение selected.

Если нужно задать несколько регионов, добавьте несколько markingSendRegionsType в параметрах запроса. Пример для регионов показа рекламы с кодами 9, 21 и 63:

&markingSendRegionsType=9&markingSendRegionsType=21&markingSendRegionsType=63

Список регионов можно получить с помощью метода erirRegions.

Целевые ссылки. Допустимо указывать несколько ссылок в поле через разделитель \n, в URL он кодируется как %0A. Каждая ссылка должна начинаться с протокола. Длина одной ссылки не может превышать 2000 символов.

Пример:

`targetURL=http://site1.ru%0Ahttp://site2.ru`

Или же можно передавать с помощью изменения названия переменной:

`&targetURL[]=http://site1.ru`

`&targetURL[]=http://site2.ru`

Массив с текстовыми данными креативов. Поле обязательно для заполнения, если не были указаны параметры mediaData и sendToErir<ParameterN>.

Действия с массивом:

  • Добавление элемента: передайте все предыдущие элементы и все новые элементы.
  • Удаление элемента: передайте все элементы, кроме удаляемого.
  • Полная очистка массива: передайте массив с пустым значением, например textData[]=.

Массив с медиаданными креативов. Поле обязательно для заполнения, если не были указаны параметры textData и sendToErir<ParameterN>.

URL-ссылка проверяется на доступность перед сохранением. Поле description необязательно для заполнения.

Пример заполнения:

mediaData[]={"url": "https://avatars.mds.yandex.net/get-adfox-content/2462621/221121_adfox_2033661_5594482.379ba05374bcd6b6339273f47b5a1b64.jpeg/optimize.webp", "description": "Text_string"}

Действия с массивом:

  • Добавление элемента: передайте все предыдущие элементы и все новые элементы.
  • Удаление элемента: передайте все элементы, кроме удаляемого.
  • Полная очистка массива: передайте массив с пустым значением, например mediaData[]=.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

Включение/отключение для определенной переменной передачи значения параметра (креатива) в ЕРИР, где <ParameterN> — название переменной.

Если вы передаете предопределенные переменные, используйте следующие названия параметров:

  • sendToErirImageURL — для переменной Изображение;
  • sendToErirGetFLV — для переменной FLV-ролик.

Чтобы включить пользовательские переменные (user1-user25), используйте <ParameterN>, где N — значение от 1 до 25. Например, sendToErirParameter2 — для дополнительной переменной user2.

Допустимые значения:

  • 0 — отключить передачу данных в ЕРИР для переменной;
  • 1 — включить передачу данных в ЕРИР для переменной.

Значение по умолчанию: 0.

Поле обязательно для заполнения, если не были указаны параметры mediaData и textData.

Ошибка Incorrect value (-6)

Не включена опция передачи параметров на шаблоне (в столбце Маркировка выбрана опция Не использовать в маркировке) — параметр передать не получится (ошибка Incorrect value (-6)). Чтобы управлять передачей данных при создании баннера, перейдите в интерфейс Adfox и включите опцию в шаблоне.

Примечание

Изменение значения параметра приведет к повторной отправке баннера на проверку в ЕРИР.

Обязательный параметр.

Предыдущая
targeting
Следующая
event