add

Создает ключевые фразы и автотаргетинги.

Внимание

Метод не сохраняет дубликаты фраз, см. Дубликаты фраз.

Ставку можно назначить в зависимости от того, какая стратегия выбрана в кампании:

  • Если в кампании настроена ручная стратегия, то можно указать параметр Bid, а если стратегия предусматривает независимое управление ставками в сетях — параметры Bid и ContextBid.

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

  • Если в кампании настроена автоматическая стратегия, а при создании фразы заданы параметры Bid и/или ContextBid, то эти значения ставок не будут применены: в момент смены стратегии с автоматической на ручную будут заданы ставки, подобранные автоматическим алгоритмом.

  • Если в кампании настроена ручная стратегия без независимого управления ставками в сетях, а при создании фразы задан параметр ContextBid, то в дальнейшем в момент смены стратегии на ручную с независимым управлением ставками заданное значение ставки будет применено.

Если стратегия предполагает назначение ставки, а ставка не указана, по умолчанию назначается:

  • для ключевой фразы — минимальная ставка;

  • для автотаргетинга для ставки ContextBid – ставка, рассчитанная на основе ставок по ключевым фразам в группе объявлений (в случае отсутствия фраз в группе — минимальная ставка).

  • для автотаргетинга для ставки Bid – автоматическая ставка. Если автоматическая ставка выключена – ставка, рассчитанная на основе ставок по ключевым фразам в группе объявлений (ручная ставка рассчитывается всегда, но используется только при выключенной автоставке). В случае отсутствия фраз в группе используется минимальная ставка.

По умолчанию все категории таргетинга включены.

Категории, для которых явно не указано значение "YES" или "NO", считаются включенными.

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

Ограничения

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

Не более 1 автотаргетинга в группе объявлений.

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

Не допускается добавление автотаргетингов в группы объявлений с типом DYNAMIC_TEXT_AD_GROUP и CPM_BANNER_AD_GROUP.

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

Ограничения на количество слов и символов в ключевой фразе см. в разделе Количественные ограничения помощи Директа.

Запрос

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

{
  "method": "add",
  "params": {  /* params */
    "Keywords": [{  /* KeywordAddItem */
      "Keyword": (string), /* required */
      "AdGroupId": (long), /* required */
      "Bid": (long),
      "AutotargetingSearchBidIsAuto" : ("YES" | "NO"),
      "ContextBid": (long),
      "StrategyPriority":  ( "LOW" | "NORMAL" | "HIGH" ),
      "UserParam1": (string),
      "UserParam2": (string),
      "AutotargetingCategories" : [{  /* AutotargetingCategoriesAddItem */
          "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */,
          "Value" : ("YES"|"NO") /* required */
      }, ...],
      "AutotargetingSettings" : {
        "Categories" : {
            "Exact" : ("YES"|"NO"),
            "Narrow" : ("YES"|"NO"),
            "Alternative" : ("YES"|"NO"),
            "Accessory" : ("YES"|"NO"),
            "Broader" : ("YES"|"NO")
        },
        "BrandOptions" : {
            "WithoutBrands" : ("YES"|"NO"),
            "WithAdvertiserBrand" : ("YES"|"NO"),
            "WithCompetitorsBrand" : ("YES"|"NO")
        }
      }
    }, ... ] /* required */
  }
}

Параметр

Тип

Описание

Обязательный

Структура params (для JSON) / AddRequest (для SOAP)

Keywords

array of KeywordAddItem

Ключевые фразы и автотаргетинги, которые требуется добавить.

Да

Структура KeywordAddItem

AdGroupId

long

Идентификатор группы, в которую добавляется ключевая фраза или автотаргетинг.

Да

Keyword

string

Ключевая фраза.

Может содержать минус-слова, которые указывают со знаком минус перед словом, например молния -гром -дождь.

Длина ключевой фразы — не более 4096 символов. Оператор “!” перед минус-словом не учитывается в длине фразы (последовательность “-!” считается как один символ).

Не более 7 слов в ключевой фразе, без учета стоп-слов и минус-слов. Каждое слово — не более 35 символов, без учета минуса перед минус-словом.

Примечание

Минус-слова, общие для всех ключевых фраз в группе объявлений, предпочтительно задавать в параметре группы [NegativeKeywords](*NegativeKeywords).

Если указано значение ---autotargeting, будет создан автотаргетинг и появится возможность указать автоматическую ставку (AutotargetingSearchBidIsAuto).

Да

Bid

long

Ставка на поиске, умноженная на 1 000 000. Целое число. Только для ручной стратегии.

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

Нет

AutotargetingSearchBidIsAuto

YesNoEnum

Признак включения опции автоматической ставки.

Можно одновременно указать ручную ставку (Bid) и включить автоставку (AutotargetingSearchBidIsAuto). В этом случае будет работать автоставка, а ручная будет использоваться в случае отключения автоматической.

Если указана ручная ставка Bid: значение автоматической ставки (AutotargetingSearchBidIsAuto) будет выставлено NO, если в явном виде не прислано иное значение автоставки.

Если не указана ручная ставка Bid: значение автоматической ставки (AutotargetingSearchBidIsAuto) будет выставлено YES, если в явном виде не прислано иное значение автоставки.

Нет

ContextBid

long

Ставка в сетях, умноженная на 1 000 000. Целое число. Только для ручной стратегии с независимым управлением ставками в Рекламной сети.

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

Внимание

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

Нет

StrategyPriority

PriorityEnum

Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH. Только для автоматической стратегии.

Внимание

Параметр не используется, переданное значение игнорируется.

Нет

UserParam1

string

Значение подстановочной переменной{param1}. Не более 255 символов.

Нет

UserParam2

string

Значение подстановочной переменной{param2}. Не более 255 символов.

Нет

AutotargetingCategories

array of AutotargetingCategoriesAddItem

Категории таргетинга, которые требуется добавить.

Внимание

Структура устарела и скоро перестанет поддерживаться. Нельзя одновременно передать AutotargetingCategories и AutotargetingSettings, вернется ошибка валидации.

Нет

AutotargetingSettings

AutotargetingSettingsAddItem

Настройки таргетинга, которые требуется добавить.

Нет

Структура AutotargetingCategoriesAddItem

Category

AutotargetingCategoriesEnum

Категория таргетинга:

  • EXACT — целевые запросы. Рекламное объявление точно отвечает на запросы пользователя;
  • ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос;
  • COMPETITOR — запросы с упоминанием конкурентов. Поиск рекламируемого продукта у конкурентов;
  • BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение;
  • ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.

Внимание

Поле устарело и скоро перестанет поддерживаться.

Настройки, заданные с помощью API, сконвертируются в веб-интерфейсе по следующим правилам:

API

Веб-интерфейс

Включенная категория EXACT.

Включенные категории “Целевые”, “Узкие”.

Включенная категория COMPETITOR (если это единственная включенная категория).

Включенная опция упоминания брендов “Конкуренты” + отключение остальных опций упоминания брендов + включение всех категорий.

Включенная категория COMPETITOR (если это не единственная включенная категория).

Включенная опция упоминания брендов “Конкуренты”.

Выключенная категория COMPETITOR.

Выключенная опция упоминания брендов “Конкуренты”.

Да

Value

YesNoEnum

Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга.

Да

Структура AutotargetingSettingsAddItem

Categories

AutotargetingSettingsCategoriesFieldNames

Категории таргетинга. Доступные опции:

  • Exact – целевые запросы. Рекламное объявление точно отвечает на запросы пользователя.
  • Narrow – узкие запросы. Рекламное объявление шире, чем запросы пользователя.
  • Alternative – альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос.
  • Accessory – сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.
  • Broader – широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение.

Нет

BrandOptions

AutotargetingSettingsBrandOptionsFieldNames

Настройки брендовости. Доступные опции:

  • WithoutBrands – без упоминания брендов.
  • WithAdvertiserBrand – с упоминанием бренда рекламодателя.
  • WithCompetitorsBrand – с упоминанием брендов конкурентов.

Нет

Ответ

Структура ответа в формате 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)
      }, ... ]
    }, ... ] /* required */
  }
}

Параметр

Тип

Описание

Структура result (для JSON) / AddResponse (для SOAP)

AddResults

array of ActionResult

Результаты добавления ключевых фраз и автотаргетингов.

Структура ActionResult

Id

long

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

Warnings

array of ExceptionNotification

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

Errors

array of ExceptionNotification

Ошибки, возникшие при выполнении операции.
Предыдущая
Keywords: управление ключевыми фразами и автотаргетингами
Следующая
delete