add

Создает фильтры — условия нацеливания для смарт-баннеров, назначает CPC, CPA или приоритет для создаваемых фильтров.

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

CPC, CPA или приоритет используются в зависимости от того, какая стратегия показа выбрана в кампании:

  • Если в кампании настроена стратегия AVERAGE_ROI, то используется параметр StrategyPriority: фильтры с более высоким приоритетом по возможности получают больший объем трафика на поиске или долю аудитории в сетях, а при недостатке бюджета отключаются в последнюю очередь.
  • Если в кампании настроена стратегия AVERAGE_CPA_PER_CAMPAIGN или AVERAGE_CPA_PER_FILTER, то используется параметр AverageCpa.
  • Если в кампании настроена стратегия AVERAGE_CPC_PER_CAMPAIGN или AVERAGE_CPC_PER_FILTER, то используется параметр AverageCpc.

Если указана ставка или приоритет, не соответствующие стратегии, они игнорируется.

Если стратегия предполагает назначение ставки, а ставка не указана, используется ставка из настроек стратегии. Если стратегия предполагает назначение приоритета, а приоритет не указан, возвращается ошибка.

Внимание.
  • Ставки и цены передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой ставку или цену, умноженную на 1 000 000.

  • Все ставки и цены указываются в валюте рекламодателя.

Ограничения

Фильтры для смарт-баннеров можно добавить только в группу объявлений с типом SMART_AD_GROUP.

Не более 50 фильтров в группе объявлений.

Не более 1000 фильтров в одном вызове метода.

Запрос

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

{
  "method": "add",
  "params": { /* params */
    "SmartAdTargets": [{ /* SmartAdTargetAddItem */
      "Name": (string), /* required */
      "AdGroupId": (long), /* required */
      "AverageCpc": (long),
      "AverageCpa": (long),
      "StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ),
      "Audience": ( "INTERESTED_IN_SIMILAR_PRODUCTS" | "VISITED_PRODUCT_PAGE" | "ALL_SEGMENTS" ), /* required */
      "Conditions": { /* ConditionsArray */ 
        "Items": [{ /* ConditionsItem */ 
          "Operand": (string), /* required */
          "Operator": ( "GREATER_THAN" | "LESS_THAN" | "IN_RANGE" | "EXISTS" | "EQUALS_ANY" | "CONTAINS_ANY" | "NOT_CONTAINS_ALL" ), /* required */
          "Arguments": [(string), ... ] /* required */
        }, ... ] /* required */
      },
      "AvailableItemsOnly": ( "YES" | "NO" )
    }, ... ]
  }
}
Параметр Тип Описание Обяза-тельный
Структура params (для JSON) / AddRequest (для SOAP)
SmartAdTargets array of SmartAdTargetAddItem Фильтры. Да
Структура SmartAdTargetAddItem
Name string Название фильтра (не более 100 символов). Да
AdGroupId long Идентификатор группы, в которую добавляется фильтр. Да
AverageCpc long Средняя цена клика, умноженная на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies.

Нет
AverageCpa long Средняя цена конверсии, умноженная на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies.

Нет
StrategyPriority PriorityEnum

Приоритет: LOW, NORMAL или HIGH. Используется только для стратегии AVERAGE_ROI.

Для стратегии AVERAGE_ROI
Audience AudienceEnum Целевая аудитория:
  • INTERESTED_IN_SIMILAR_PRODUCTS — пользователи, которые интересовались похожими товарами в сети.
  • VISITED_PRODUCT_PAGE — пользователи, которые смотрели товары на сайте рекламодателя.
  • ALL_SEGMENTS — обе группы.
Да
Conditions ConditionsArray

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

Если параметр не задан, фильтр отбирает все товарные предложения из фида (тип отбора ITEMS_ALL).
Ограничение. Если тип фида в группе объявлений — FLIGHTS или RETAIL, правила отбора не предусмотрены.
Нет
AvailableItemsOnly YesNoEnum Отбирать только товары в наличии. Значение по умолчанию NO.

Может быть использован только в фидах с типом Яндекс Маркет, в остальных фидах будет проигнорирован.

Нет
Структура ConditionsArray
Items array of ConditionsItem Правила отбора. Не более 30 фильтров в массиве. Суммарная длина правил отбора — не более 65 кБайт (в формате JSON). Да
Структура ConditionsItem
Operand string

Параметр фида.

Описание полей для каждого типа фида см. в разделе Настройка фильтров помощи Директа.

Да
Operator StringConditionOperatorEnum

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

Да
Arguments array of string

Массив строк, с которыми сравнивается операнд.

Да
Параметр Тип Описание Обяза-тельный
Структура params (для JSON) / AddRequest (для SOAP)
SmartAdTargets array of SmartAdTargetAddItem Фильтры. Да
Структура SmartAdTargetAddItem
Name string Название фильтра (не более 100 символов). Да
AdGroupId long Идентификатор группы, в которую добавляется фильтр. Да
AverageCpc long Средняя цена клика, умноженная на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies.

Нет
AverageCpa long Средняя цена конверсии, умноженная на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies.

Нет
StrategyPriority PriorityEnum

Приоритет: LOW, NORMAL или HIGH. Используется только для стратегии AVERAGE_ROI.

Для стратегии AVERAGE_ROI
Audience AudienceEnum Целевая аудитория:
  • INTERESTED_IN_SIMILAR_PRODUCTS — пользователи, которые интересовались похожими товарами в сети.
  • VISITED_PRODUCT_PAGE — пользователи, которые смотрели товары на сайте рекламодателя.
  • ALL_SEGMENTS — обе группы.
Да
Conditions ConditionsArray

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

Если параметр не задан, фильтр отбирает все товарные предложения из фида (тип отбора ITEMS_ALL).
Ограничение. Если тип фида в группе объявлений — FLIGHTS или RETAIL, правила отбора не предусмотрены.
Нет
AvailableItemsOnly YesNoEnum Отбирать только товары в наличии. Значение по умолчанию NO.

Может быть использован только в фидах с типом Яндекс Маркет, в остальных фидах будет проигнорирован.

Нет
Структура ConditionsArray
Items array of ConditionsItem Правила отбора. Не более 30 фильтров в массиве. Суммарная длина правил отбора — не более 65 кБайт (в формате JSON). Да
Структура ConditionsItem
Operand string

Параметр фида.

Описание полей для каждого типа фида см. в разделе Настройка фильтров помощи Директа.

Да
Operator StringConditionOperatorEnum

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

Да
Arguments array of string

Массив строк, с которыми сравнивается операнд.

Да

Ответ

Структура ответа в формате 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)
AddResults array of ActionResult Результаты добавления фильтров.
Структура ActionResult
Id long Идентификатор созданного фильтра. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.
Warnings array of ExceptionNotification

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

Errors array of ExceptionNotification

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

Параметр Тип Описание
Структура result (для JSON) / AddResponse (для SOAP)
AddResults array of ActionResult Результаты добавления фильтров.
Структура ActionResult
Id long Идентификатор созданного фильтра. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.
Warnings array of ExceptionNotification

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

Errors array of ExceptionNotification

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