add

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

  1. Ограничения
  2. Запрос
  3. Ответ
Внимание. Метод не сохраняет дубликаты фраз, см. Дубликаты фраз.

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

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

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

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

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

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

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

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

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

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

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

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

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

Ограничения

Не более 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),
      "ContextBid": (long),
      "StrategyPriority":  ( "LOW" | "NORMAL" | "HIGH" ),
      "UserParam1": (string),
      "UserParam2": (string)
    }, ... ] /* required */
  } 
}
Параметр Тип Описание Обяза-тельный
Структура params (для JSON) / AddRequest (для SOAP)
Keywords array of KeywordAddItem Ключевые фразы и автотаргетинги, которые требуется добавить. Да
Структура KeywordAddItem
AdGroupId long Идентификатор группы, в которую добавляется ключевая фраза или автотаргетинг. Да
Keyword string

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

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

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

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

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

Если указано значение ---autotargeting, будет создан автотаргетинг.

Да
Bid long

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

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

Нет
ContextBid long

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

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

Внимание. Показ графического объявления возможен только при условии, что ставка не ниже минимальной ставки для объявления с включенным в него изображением.
Нет
StrategyPriority PriorityEnum Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH. Только для автоматической стратегии. Нет
UserParam1 string Значение подстановочной переменной {param1}. Не более 255 символов. Нет
UserParam2 string Значение подстановочной переменной {param2}. Не более 255 символов. Нет

Ответ

Структура ответа в формате 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

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