add

Создает объявления.

  1. Ограничения
  2. Запрос
  3. Ответ

Ограничения

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

Не допускается добавление объявлений в архивную кампанию.

Не более 1000 объявлений в одном вызове метода.

Ограничение на количество объявлений в группе для рекламодателя можно получить с помощью метода Clients.get или AgencyClients.get (элемент ADS_TOTAL_PER_ADGROUP массива Restrictions).

Запрос

Структура запроса в формате JSON:

{
  "method": "add",
  "params": { /* params */
    "Ads": [{  /* AdAddItem */
      "TextAd": {  /* TextAdAdd */
        "Title": (string), /* required */
        "Title2": (string),
        "Text": (string), /* required */
        "Href": (string),
        "Mobile": ( "YES" | "NO" ), /* required */
        "DisplayUrlPath": (string),
        "VCardId": (long),
        "AdImageHash": (string),
        "SitelinkSetId": (long),
        "AdExtensionIds": [(long), ... ],
        "VideoExtension": {  /* VideoExtensionAddItem */
          "CreativeId": (long)
        }  
      },
      "DynamicTextAd": {  /* DynamicTextAdAdd */
        "Text": (string), /* required */
        "VCardId": (long),
        "AdImageHash": (string),
        "SitelinkSetId": (long),
        "AdExtensionIds": [(long), ... ]
      },
      "MobileAppAd": {  /* MobileAppAdAdd */
        "Title": (string), /* required */
        "Text": (string), /* required */
        "TrackingUrl": (string),
        "Features": [{  /* MobileAppAdFeatureItem */
          "Feature": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */
          "Enabled": ( "YES" | "NO" ) /* required */
        }, ... ],
        "Action": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | "UPDATE" | "PLAY" | "BUY_AUTODETECT" ), /* required */
        "AgeLabel": ( "AGE_0" | ... | "AGE_18" ),
        "AdImageHash": (string)
      },
      "TextImageAd": {  /* TextImageAdAdd */
        "Href": (string), /* required */
        "AdImageHash": (string) /* required */
      },
      "MobileAppImageAd": {  /* MobileAppImageAdAdd */
        "TrackingUrl": (string),
        "AdImageHash": (string) /* required */
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "Href": (string) /* required */
      },
      "MobileAppAdBuilderAd": {  /* MobileAppAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "TrackingUrl": (string)
      },
      "CpcVideoAdBuilderAd": {  /* CpcVideoAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "Href": (string) /* required */
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */      
        "Href": (string), /* required */
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        }
      },
      "AdGroupId": (long) /* required */ 
    }, ... ] /* required */
  } 
}
ПараметрТипОписаниеОбязательный
Структура params (для JSON) / AddRequest (для SOAP)
Adsarray of AdAddItem

Объявления, которые требуется добавить.

Да
Структура AdAddItem
AdGroupIdlongИдентификатор группы, в которую добавляется объявление.Да
TextAdTextAdAddПараметры текстово-графического объявления. См. Тип объявления.Либо TextAd, либо MobileAppAd, либо DynamicTextAd, либо TextImageAd, либо MobileAppImageAd, либо TextAdBuilderAd, либо MobileAppAdBuilderAd, либо CpcVideoAdBuilderAd, либо CpmBannerAdBuilderAd
MobileAppAdMobileAppAdAddПараметры объявления для рекламы мобильных приложений.
DynamicTextAdDynamicTextAdAddПараметры динамического объявления.
TextImageAdTextImageAdAddПараметры графического объявления, создаваемого на основе изображения (при добавлении в группу текстово-графических объявлений).
MobileAppImageAdMobileAppImageAdAddПараметры графического объявления, создаваемого на основе изображения (при добавлении в группу для рекламы мобильных приложений).
TextAdBuilderAdTextAdBuilderAdAddПараметры графического объявления, создаваемого на основе креатива (при добавлении в группу текстово-графических объявлений).
MobileAppAdBuilderAdMobileAppAdBuilderAdAddПараметры графического объявления, создаваемого на основе креатива (при добавлении в группу для рекламы мобильных приложений).
CpcVideoAdBuilderAdCpcVideoAdBuilderAdAddПараметры видеообъявления.
CpmBannerAdBuilderAdCpmBannerAdBuilderAdAddПараметры медийного объявления.
Структура TextAdAdd
Titlestring

Заголовок 1.

Не более 35 символов без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Да
Title2string

Заголовок 2.

Не более 30 символов без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Нет
Textstring

Текст объявления.

Не более 81 символа без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 23 символов. В случае использования шаблона символы # не учитываются в длине.

Да
MobileYesNoEnumПризнак того, что объявление является мобильным: YES или NO. См. раздел Мобильные объявления помощи Директа.Да
Hrefstring

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Href или VCardId (могут присутствовать оба)
VCardIdlongИдентификатор виртуальной визитки. Визитка должна принадлежать той же кампании, что и объявление.
AdImageHashstring

Хэш изображения.

Для текстово-графических объявлений подходят только изображения с типом REGULAR и WIDE, см. Тип изображения.
Нет
SitelinkSetIdlongИдентификатор набора быстрых ссылок. Допускается только при наличии параметра Href.Нет
DisplayUrlPathstring

Отображаемая ссылка. Допускается только при наличии параметра Href. Не более 20 символов. В случае использования шаблона символы # не учитываются в длине.

Может содержать буквы, цифры, символы -, №, /, %, #. Запрещены пробел, символ _, двойные символы --, //.

См. раздел Отображаемая ссылка помощи Директа.

Нет
AdExtensionIdsarray of longИдентификаторы расширений. Не более 50 элементов в массиве.Нет
VideoExtensionVideoExtensionAddItem

Видеодополнение.

См. раздел Видеодополнения помощи Директа.

Нет
Структура VideoExtensionAddItem
CreativeIdlong

Идентификатор креатива.

Получить идентификатор креатива можно с помощью метода Creatives.get.

Да
Структура MobileAppAdAdd
Titlestring

Заголовок.

Не более 33 символов с учетом «узких». Каждое слово не более 22 символов. В случае использования шаблона символы # не учитываются в длине.

Да
Textstring

Текст объявления.

Не более 75 символов с учетом «узких». Каждое слово не более 23 символов. В случае использования шаблона символы # не учитываются в длине.

Да
TrackingUrlstringТрекинговая ссылка для отслеживания установок приложения. Не более 1024 символов. Должна содержать протокол и доменное имя.Нет
Featuresarray of MobileAppAdFeatureItemДополнения, которые требуется автоматически загружать из магазина приложений и отображать в объявлении.Нет
AgeLabelMobAppAgeLabelEnumВозрастное ограничение. Значение по умолчанию — AGE_18.Нет
ActionMobileAppAdActionEnum

Надпись на кнопке:

  • DOWNLOAD — «Загрузить»

  • GET — «Скачать»

  • INSTALL — «Установить»

  • MORE — «Подробнее»

  • OPEN — «Открыть»

  • UPDATE — «Обновить»

  • PLAY — «Играть»

  • BUY_AUTODETECT — надпись зависит о цены приложения: «Купить», если цена отлична от нуля, или «Бесплатно», если цена равна нулю.

Да
AdImageHashstring

Хэш изображения.

Для рекламы мобильных приложений подходят только изображения с типом WIDE, см. Тип изображения.

Нет
Структура MobileAppAdFeatureItem
FeatureMobileAppFeatureEnum

Тип дополнения:

  • PRICE — цена;
  • ICON — иконка;
  • CUSTOMER_RATING — рейтинг;
  • RATINGS — количество оценок (отображается, только если включено отображение рейтинга).

Если тип дополнения отсутствует в массиве Features, дополнение не отображается.

Да
EnabledYesNoEnum

Отображать ли дополнение в объявлении.

Примечание.
  • Если дополнение не удалось загрузить из магазина приложений, для него допустимо значение YES, однако это дополнение не отображается при показе объявления.
  • Количество оценок отображается только вместе с рейтингом: если для типа CUSTOMER_RATING задано NO, а для RATINGS — YES, количество оценок не отображается.
Да
Структура DynamicTextAdAdd
Textstring

Текст объявления.

Не более 81 символа без учета «узких» плюс не более 15 «узких» символов. Каждое слово не более 23 символов. В случае использования шаблона символы # не учитываются в длине.

Да
VCardIdlongИдентификатор виртуальной визитки. Визитка должна принадлежать той же кампании, что и объявление.Нет
AdImageHashstring

Хэш изображения.

Для динамических объявлений подходят только изображения с типом REGULAR и WIDE, см. Тип изображения.

Нет
SitelinkSetIdlongИдентификатор набора быстрых ссылок.Нет
AdExtensionIdsarray of longИдентификаторы расширений. Не более 50 элементов в массиве.Нет
Структура TextImageAdAdd
Hrefstring

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Да
AdImageHashstring

Хэш изображения.

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

Да
Структура MobileAppImageAdAdd
TrackingUrlstringТрекинговая ссылка для отслеживания установок приложения. Не более 1024 символов. Должна содержать протокол и доменное имя.Нет
AdImageHashstring

Хэш изображения.

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

Да
Структура TextAdBuilderAdAdd
CreativeAdBuilderAdAddItem

Креатив, созданный в конструкторе креативов.

См. раздел Конструктор креативов для графических объявлений помощи Директа.

Да
Hrefstring

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Да
Структура MobileAppAdBuilderAdAdd
CreativeAdBuilderAdAddItem

Креатив, созданный в конструкторе креативов.

См. раздел Конструктор креативов для графических объявлений помощи Директа.

Да
TrackingUrlstringТрекинговая ссылка для отслеживания установок приложения. Не более 1024 символов. Должна содержать протокол и доменное имя.Нет
Структура CpmBannerAdBuilderAdAdd
CreativeAdBuilderAdAddItem

Креатив, загруженный в веб-интерфейсе или созданный в конструкторе креативов.

См. раздел Создание медийной кампании помощи Директа.

Да
Hrefstring

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Да
TrackingPixelsArrayOfStringМожет содержать не более двух строк:
  • Пиксель Яндекс.Аудиторий — см. раздел Пиксель помощи Яндекс.Аудиторий.
  • Счетчик показов ADFOX. В счетчике показов обязательно должен быть макрос %random% или %aw_random%.

Длина каждой строки не более 1024 символов.

Нет
Структура CpcVideoAdBuilderAdAdd
CreativeAdBuilderAdAddItem

Креатив, созданный в конструкторе креативов.

См. раздел Конструктор креативов для видеодополнений помощи Директа.

Да
Hrefstring

Ссылка на сайт рекламодателя. Не более 1024 символов. В случае использования шаблона символы # не учитываются в длине.

Должна содержать протокол и доменное имя. Может содержать подстановочные переменные.

Да
Структура AdBuilderAdAddItem
CreativeIdlong

Идентификатор креатива.

Получить идентификатор креатива можно с помощью метода Creatives.get.

Да
Примечание. «Узкими» считаются символы !,.;:"

Ответ

Структура ответа в формате JSON:

{
  "result": { /* result */
    "AddResults": [{  /* ActionResult */
      "Id": (long),
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ] 
    }, ... ]
  }
}
ПараметрТипОписание
Структура result (для JSON) / AddResponse (для SOAP)
AddResultsarray of ActionResultРезультаты добавления объявлений.
Структура ActionResult
IdlongИдентификатор созданного объявления. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.
Warningsarray of ExceptionNotification

Предупреждения, возникшие при выполнении операции.

Errorsarray of ExceptionNotification

Ошибки, возникшие при выполнении операции.