add
Создает фильтры — условия нацеливания для смарт-баннеров, назначает CPC, CPA или приоритет для создаваемых фильтров.
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 | Целевая аудитория:
| Да |
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 | Целевая аудитория:
| Да |
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 | Ошибки, возникшие при выполнении операции. |