setAuto

Конструктор ставок — рассчитывает ставки для фраз по заданному алгоритму.

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

Метод выполняет назначение ставок в асинхронном режиме и не возвращает ставки. Получить ставки можно методом get.

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

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

  • Если в кампании автоматическая стратегия, возвращается ошибка.
  • Если в кампании отключены показы на поиске, а в параметре Scope передано только значение SEARCH, то возвращается ошибка. Если переданы оба значения — SEARCH и NETWORK, то будут обновлены ставки только в сетях и выдано предупреждение.
  • Если в кампании ручная стратегия на поиске, при этом не предусмотрено независимое управление ставками в сетях или показы в сетях отключены, а в параметре Scope передано только значение NETWORK, то возвращается ошибка. Если переданы оба значения — SEARCH и NETWORK, то будут обновлены ставки только на поиске и выдано предупреждение.
Внимание.
  • Ставки и цены передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой ставку или цену, умноженную на 1 000 000.

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

Чтобы назначить ставки на поиске, передайте в параметре Scope значение SEARCH.

Для расчета ставки используются значения, переданные в параметрах Position, IncreasePercent, CalculateBy, MaxBid.

Position CalculateBy Формула расчета ставки
FOOTERBLOCK VALUE

Минимальная ставка за 4-ю позицию в гарантии + минимальная ставка за 4-ю позицию в гарантии × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 4-ю позицию в гарантии + (минимальная ставка за 1-ю позицию – минимальная ставка за 4-ю позицию в гарантии) × IncreasePercent / 100,

но не более MaxBid

FOOTERFIRST VALUE

Минимальная ставка за 1-ю позицию в гарантии + минимальная ставка за 1-ю позицию в гарантии × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 1-ю позицию в гарантии + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 1-ю позицию в гарантии) × IncreasePercent / 100,

но не более MaxBid

PREMIUMBLOCK или P14 VALUE

Минимальная ставка за 4-ю позицию в спецразмещении + минимальная ставка за 4-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 4-ю позицию в спецразмещении + (минимальная ставка за 3-ю позицию в спецразмещении – минимальная ставка за 4-ю позицию в спецразмещении) × IncreasePercent / 100,

но не более MaxBid

P13 VALUE

Минимальная ставка за 3-ю позицию в спецразмещении + минимальная ставка за 3-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 3-ю позицию в спецразмещении + (минимальная ставка за 2-ю позицию в спецразмещении – минимальная ставка за 3-ю позицию в спецразмещении) × IncreasePercent / 100,

но не более MaxBid

P12 VALUE

Минимальная ставка за 2-ю позицию в спецразмещении + минимальная ставка за 2-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 2-ю позицию в спецразмещении + (минимальная ставка за 1-ю позицию в спецразмещении – минимальная ставка за 2-ю позицию в спецразмещении) × IncreasePercent / 100,

но не более MaxBid

PREMIUMFIRST или P11 VALUE

Минимальная ставка за 1-ю позицию в спецразмещении + минимальная ставка за 1-ю позицию в спецразмещении × IncreasePercent / 100,

но не более MaxBid

DIFF

Минимальная ставка за 1-ю позицию в спецразмещении, но не более MaxBid

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

Ограничения

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

Количество объектов в одном вызове метода:
  • кампаний — не более 10;
  • групп — не более 1000;
  • фраз — не более 10 000.

Запрос

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

{
  "method": "setAuto",
  "params": { /* params */
    "Bids": [{  /* BidSetAutoItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "MaxBid": (long),
      "Position": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" | "P11" | "P12" | "P13" | "P14" | "P21" | "P22" | "P23" | "P24" ),
      "IncreasePercent": (int),
      "CalculateBy": ( "VALUE" | "DIFF" ),
      "ContextCoverage": (int),
      "Scope": [( "SEARCH" | "NETWORK" ), ... ] /* required */
    }, ... ] /* required */
  } 
}
Параметр Тип Описание Обязательный
Структура params (для JSON) / SetAutoRequest (для SOAP)
Bids array of BidSetAutoItem Параметры расчета ставок. Да
Структура BidSetAutoItem
CampaignId long Идентификатор кампании. Указывается, если требуется обновить ставки для всех фраз кампании. Либо CampaignId, либо AdGroupId, либо KeywordId
AdGroupId long Идентификатор группы объявлений. Указывается, если требуется обновить ставки для всех фраз группы.
KeywordId long

Идентификатор фразы. Указывается, если требуется обновить ставку для отдельной фразы.

Ограничение. Идентификатор автотаргетинга не допускается.
Scope array of ScopeEnum Указывает, какие ставки назначить. Массив может содержать следующие элементы (один или оба):
  • SEARCH — назначить ставки на поиске (Bid). Для расчета ставок используются значения, переданные в параметрах Position, IncreasePercent, CalculateBy, MaxBid.
  • NETWORK — назначить ставки в сетях (ContextBid). Для расчета ставок используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.
Да
MaxBid long

Ограничение на ставку, умноженное на 1 000 000. Целое число.

Указывается в валюте рекламодателя. Ограничения приведены на странице Минимальный и максимальный размер цены за клик.

Нет
Position PositionEnum

Позиция показа, ставка за которую используется как основа для расчета ставок на поиске.

К цене указанной позиции прибавляется надбавка (см. параметры IncreasePercent и CalculateBy).

Если в массиве Scope присутствует значение Search
IncreasePercent int Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается. Нет
CalculateBy CalculateByEnum

База, на основе которой рассчитывается надбавка:

  • VALUE — цена позиции, указанной в Position.

  • DIFF — разница между минимальной ставкой за позицию, указанную в параметре Position, и за следующую позицию.

    При выборе позиции PREMIUMFIRST (P11) следующая позиция отсутствует и надбавка равна нулю. Это же верно при выборе позиции FOOTERFIRST (P21), если стоимость следующей позиции PREMIUMBLOCK (P14) меньше (редкая, но возможная ситуация).

Если в массиве Scope присутствует значение Search и задан параметр IncreasePercent
ContextCoverage int

Частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100.

К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр IncreasePercent).

Если в массиве Scope присутствует значение Network
Внимание. Параметры CampaignId, AdGroupId и KeywordId являются взаимоисключающими. В одном запросе можно указывать только один из этих параметров.

Ответ

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

{
  "result": { /* result */
    "SetAutoResults": [{  /* BidActionResult */
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
     }, ... ],        
    "CampaignId": (long),
    "AdGroupId": (long),
    "KeywordId": (long) 
   }, ... ]
  }
}
Параметр Тип Описание
Структура result (для JSON) / SetAutoResponse (для SOAP)
SetAutoResults array of BidActionResult Результаты назначения ставок и/или приоритетов.
Структура BidActionResult
CampaignId long Идентификатор кампании. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).
AdGroupId long Идентификатор группы объявлений. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).
KeywordId long Идентификатор ключевой фразы. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов (если был указан в запросе).
Warnings array of ExceptionNotification

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

Errors array of ExceptionNotification

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

Примеры

Пример запроса

Назначить на поиске цену 1-го места в гарантии + 50% от разницы до спецразмещения, но не более 0,25.

{
  "method" : "setAuto",
  "params" : {
    "Bids" : [
      {
        "Scope" : [
          "SEARCH"
        ],
        "IncreasePercent" : 50,
        "CalculateBy" : "DIFF",
        "Position" : "FOOTERFIRST",
        "KeywordId" : 1574449505,
        "MaxBid" : 250000
      }
    ]
  }
}
Пример ответа
{
  "result" : {
    "SetAutoResults" : [
      {
        "KeywordId" : 1574449505
      }
    ]
  }
}