setAuto
Конструктор ставок — рассчитывает ставки для фраз по заданному алгоритму.
Метод выполняет назначение ставок в асинхронном режиме и не возвращает ставки. Получить ставки можно методом get.
Ставку можно назначить, только если в кампании выбрана ручная стратегия.
Метод не сбрасывает значение автоматической ставки (AutotargetingSearchBidIsAuto).
В случае если элемент входного массива содержит ставки, не соответствующие стратегии, то эти ставки применены не будут.
- Если в кампании автоматическая стратегия, возвращается ошибка.
- Если в кампании отключены показы на поиске, а в параметре 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 |
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 |
Ставку в сетях можно назначить только для стратегии, предусматривающей раздельное управление ставками на поиске и в сетях.
Чтобы назначить ставки в сетях, передайте в параметре Scope значение NETWORK.
Для расчета ставки используются значения, переданные в параметрах ContextCoverage, IncreasePercent, MaxBid.
Формула расчета ставки:
Ставка, при которой прогнозируется указанная частота показа + ставка, при которой прогнозируется указанная частота показа × IncreasePercent / 100,
но не более 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 | Указывает, какие ставки назначить. Массив может содержать следующие элементы (один или оба):
| Да |
MaxBid | long | Ограничение на ставку, умноженное на 1 000 000. Целое число. Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies. | Нет |
Position | PositionEnum | Позиция показа, ставка за которую используется как основа для расчета ставок на поиске. К цене указанной позиции прибавляется надбавка (см. параметры IncreasePercent и CalculateBy). | Если в массиве Scope присутствует значение Search |
IncreasePercent | int | Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается. | Нет |
CalculateBy | CalculateByEnum | База, на основе которой рассчитывается надбавка:
| Если в массиве Scope присутствует значение Search и задан параметр IncreasePercent |
ContextCoverage | int | Частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100. К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр IncreasePercent). | Если в массиве Scope присутствует значение Network |
Параметр | Тип | Описание | Обязательный |
Структура params (для JSON) / SetAutoRequest (для SOAP) | |||
---|---|---|---|
Bids | array of BidSetAutoItem | Параметры расчета ставок. | Да |
Структура BidSetAutoItem | |||
CampaignId | long | Идентификатор кампании. Указывается, если требуется обновить ставки для всех фраз кампании. | Либо CampaignId, либо AdGroupId, либо KeywordId |
AdGroupId | long | Идентификатор группы объявлений. Указывается, если требуется обновить ставки для всех фраз группы. | |
KeywordId | long | Идентификатор фразы. Указывается, если требуется обновить ставку для отдельной фразы. Ограничение. Идентификатор автотаргетинга не допускается. | |
Scope | array of ScopeEnum | Указывает, какие ставки назначить. Массив может содержать следующие элементы (один или оба):
| Да |
MaxBid | long | Ограничение на ставку, умноженное на 1 000 000. Целое число. Указывается в валюте рекламодателя. Ограничения представлены в справочнике валют, который можно получить с помощью метода Dictionaries.get, указав в запросе имя справочника Currencies. | Нет |
Position | PositionEnum | Позиция показа, ставка за которую используется как основа для расчета ставок на поиске. К цене указанной позиции прибавляется надбавка (см. параметры IncreasePercent и CalculateBy). | Если в массиве Scope присутствует значение Search |
IncreasePercent | int | Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается. | Нет |
CalculateBy | CalculateByEnum | База, на основе которой рассчитывается надбавка:
| Если в массиве Scope присутствует значение Search и задан параметр IncreasePercent |
ContextCoverage | int | Частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100. К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр IncreasePercent). | Если в массиве Scope присутствует значение Network |
Ответ
Структура ответа в формате 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 | Ошибки, возникшие при выполнении операции. |
Параметр | Тип | Описание |
Структура 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 } ] } }