Объявление (Ad)

Объявление представляет собой рекламно-информационный материал. Набор параметров объявления зависит от его типа.

Узнайте больше

• Ведение кампании.

Сервис

Для управления объявлениями предназначен сервис Ads.

Методы

add | update | delete | suspend | resume | archive | unarchive | moderate | get

Для работы с товарными объявлениями используется адрес https://api.direct.yandex.com/v501/.

Ограничения

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

Никакие операции с объявлениями в архивной кампании невозможны.

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

Ограничения на параметры объявления см. в разделе Количественные ограничения Справки Директа.

Тип объявления

Тип объявления задается при создании и недоступен для изменения.

Существуют следующие типы объявлений:

• TEXT_AD — текстово-графическое (обычное) объявление.

  Объявление содержит заголовок и текст объявления, а также ссылку на продвигаемый сайт. В объявление также можно добавить отображаемую ссылку, изображение, видео, цену, набор быстрых ссылок, уточнения, идентификатор профиля организации на Яндексе. Объявлению может быть автоматически присвоена возрастная метка — в этом случае значение метки можно изменить.

  Чтобы создать или отредактировать текстово-графическое объявление, его параметры необходимо передать в структуре TextAd методов add, update.

  Чтобы получить параметры объявления (кроме параметров цены), необходимо перечислить имена параметров во входном параметре TextAdFieldNames метода get. Чтобы получить параметры цены, необходимо перечислить их имена во входном параметре TextAdPriceExtensionFieldNames.

• IMAGE_AD — графическое объявление.

  Подтипы графических объявлений:

  • TEXT_IMAGE_AD

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

    Чтобы создать или отредактировать объявление, его параметры необходимо передать в структуре TextImageAd методов add, update.

    Чтобы получить параметры объявления, необходимо перечислить имена параметров во входном параметре TextImageAdFieldNames метода get.

  • TEXT_AD_BUILDER_AD

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

    Чтобы создать или отредактировать объявление, его параметры необходимо передать в структуре TextAdBuilderAd методов add, update.

    Чтобы получить параметры объявления, необходимо перечислить имена параметров во входном параметре TextAdBuilderAdFieldNames метода get.

  Внимание

  Графические объявления показываются только в сетях (Рекламной сети Яндекса и внешних сетях), но не показываются на поиске.

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

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

• CPM_BANNER_AD — медийный баннер.

  Объявление содержит креатив, загруженный в веб-интерфейсе или созданный в конструкторе креативов, а также ссылку на продвигаемый сайт или страницу в соцсети с дополнительной информацией о предложении. В объявление также можно добавить пиксель Яндекс Аудиторий и счетчик показов ADFOX.

  Чтобы создать или отредактировать объявление, его параметры необходимо передать в структуре CpmBannerAdBuilderAd методов add, update.

  Чтобы получить параметры объявления, необходимо перечислить имена параметров во входном параметре CpmBannerAdBuilderAdFieldNames метода get.

• CPM_VIDEO_AD — медийное видеообъявление (в кампании с типом «Медийная кампания»).

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

  Чтобы создать или отредактировать объявление, его параметры необходимо передать в структуре CpmVideoAdBuilderAd методов add, update.

  Чтобы получить параметры объявления, необходимо перечислить имена параметров во входном параметре CpmVideoAdBuilderAdFieldNames метода get.

• SHOPPING_AD – товарное объявление (в кампании с типом «Единая перфоманс-кампания»).

  Объявление формируется на основе товарных предложений и/или страниц каталога из фида — в зависимости от значения параметра GenerationScopes. В одну группу можно добавить до двух неархивных товарных объявлений.

  Чтобы создать или отредактировать объявление, его параметры необходимо передать в структуре ShoppingAd методов add, update.

  Чтобы получить параметры объявления, необходимо перечислить имена параметров во входном параметре ShoppingAdFieldNames метода get.

• LISTING_AD — объявление для страниц каталога (в кампании с типом «Единая перфоманс-кампания»).

  Внимание

  Тип объявления LISTING_AD и структура ListingAd устарели. Для работы со страницами каталога используйте ShoppingAd со значением параметра GenerationScopes = ["LISTING"].

  Подробнее см. в разделе Совместимость с объявлениями страниц каталога.

• RESPONSIVE_AD – объявление, в котором можно указать несколько заголовков, текстов, изображений и видео.

  В одну группу можно добавить до 3 неархивных комбинаторных объявлений и до 10 объявлений этого типа с учетом архивных.

  Чтобы создать или отредактировать объявление, его параметры необходимо передать в структуре ResponsiveAd методов add, update.

  Чтобы получить параметры объявления, необходимо перечислить имена параметров во входном параметре ResponsiveAdFieldNames метода get.

Параметры Type, Subtype, Status, State, StatusClarification, AdCategories, AgeLabel являются общими для всех типов объявлений. Чтобы получить их, необходимо перечислить имена нужных параметров во входном параметре FieldNames метода get.

Соответствие типов объявлений и групп представлено в таблице ниже.

Совместимость с объявлениями страниц каталога

Тип объявления LISTING_AD и структура ListingAd устарели. Для работы со страницами каталога используйте ShoppingAd со значением параметра GenerationScopes = ["LISTING"]. Для товаров по-прежнему используются параметры FeedFilterConditions, TitleSources и TextSources структуры ShoppingAd. Фид для товаров и страниц каталога задается общим параметром FeedId.

Существующие запросы с ListingAd продолжают поддерживаться в режиме совместимости:

• Метод add. При передаче структуры ListingAd создается товарное объявление с GenerationScopes = ["LISTING"]. Параметры FeedFilterConditions, TitleSources и TextSources сохраняются соответственно в ListingFeedFilterConditions, ListingTitleSources и ListingTextSources.

• Метод update. Через структуру ListingAd можно изменять существующие объявления типа LISTING_AD и товарные объявления с GenerationScopes = ["LISTING"]. Соответствие параметров такое же, как в методе add. Для изменения объявлений, продвигающих товары или товары и страницы каталога, используйте ShoppingAd.

• Метод get. Режим получения объявлений зависит от параметра ListingAdFieldNames:

  • Передан непустой список ListingAdFieldNames — используется режим совместимости. Товарные объявления с GenerationScopes = ["LISTING"] возвращаются с типом LISTING_AD и структурой ListingAd, даже если также запрошены поля ShoppingAdFieldNames. При фильтрации по SelectionCriteria.Types такие объявления учитываются как LISTING_AD.

  • Параметр ListingAdFieldNames отсутствует — режим совместимости не используется. Такие объявления возвращаются с типом SHOPPING_AD; для получения их параметров используйте ShoppingAdFieldNames.

Статус и состояние объявления

Параметр State отражает текущее состояние объявления.

Параметр Status отражает результат модерации объявления.

Особая категория

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

Для некоторых категорий показ объявлений запрещен, для других — при показе объявлений выводятся предупреждения в соответствии с законодательством РФ.

Справочник особых категорий можно получить с помощью метода Dictionaries.get.

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

Возрастная метка

Параметр AgeLabel содержит возрастную категорию продвигаемой продукции, если указание категории требует Федеральный закон РФ «О рекламе». Порядок присвоения возрастной метки отличается в зависимости от типа объявления.

Для объявлений TEXT_AD и RESPONSIVE_AD значение возрастной метки зависит от принадлежности к особой категории BABY_FOOD:

• Для объявлений, относящихся к категории BABY_FOOD, — возраст ребенка в месяцах: "MONTHS_0", "MONTHS_1", "MONTHS_2", ..., "MONTHS_12".

• Для прочих объявлений — возраст, на который ориентирована информационная продукция. Возможные значения: "AGE_0", "AGE_6", "AGE_12", "AGE_16", "AGE_18".

Если у объявления отсутствует возрастная метка, задать ее нельзя (значение параметра игнорируется методом update).

Дополнения к объявлению

Методы add и update позволяют привязать к объявлению изображение, видеодополнение, набор быстрых ссылок, уточнения (в зависимости от типа объявления). Подробная инструкция приведена в разделе Дополнения к объявлению.

Видеодополнения показываются только в сетях (Рекламной сети Яндекса и внешних сетях), но не показываются на поиске.

Ставка для изображений и видеодополнений

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

Результат модерации дополнений

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

Метод get возвращает результат модерации изображения (структура AdImageModeration), набора быстрых ссылок (структура SitelinksModeration), видеодополнения (параметр Status в структуре VideoExtension).

Правила отбора для товарных объявлений

Правило отбора состоит из трех параметров:

• Operand — поле фида;
• Operator — оператор сравнения;
• Arguments — массив значений, с которыми сравнивается значение поля в фиде.

Совместимость полей фида и операторов зависит от фида:

Примеры

Значение содержит одну из заданных строк:

    {
      "Operand": "mark_id",
      "Operator": "CONTAINS_ANY",
      "Arguments": ["Audi","Opel"]
    }

Диапазон: цена от 111 до 222 или от 3000 до 10000:

    {
      "Operand": "price",
      "Operator": "IN_RANGE",
      "Arguments": ["111-222", "3000-10000"]
    }

Значение из списка:

    {
      "Operand": "wheel",
      "Operator": "EQUALS_ANY",
      "Arguments": ["левый"]
    }

Маркировка продвижения

Параметр ErirAdDescription содержит описание объекта продвижения.

Параметр AutogeneratedErirAdDescription содержит автоматически сгенерированное описание объекта продвижения.

Подробнее про маркировку продвижения см. здесь.