SetAutoPrice (Live)
Задает или рассчитывает по алгоритму ставки для фраз.
Если ни для одной фразы ставка не обновлена, метод возвращает сообщение об ошибке 244.
Изменения ставок вступают в силу спустя некоторое время, см. правила показаправила показа.
Ограничения
Не более 100 вызовов метода для одной кампании в сутки.
Внимание
Метод поддерживает только кампании с типом “Текстово-графические объявления”“Text & Image Ads”. Для назначения ставок в кампаниях всех типов используйте сервис {#T} API версии 5.
Новое в версии Live 4
Добавлены входные параметры BannerIDS и PhraseIDS.
Добавлен входной параметр BannersType.
Добавлены входные параметры Price и ContextPrice для способа SinglePrice.
Добавлен входной параметр DontWaitForPriceUpdate.
Добавлен входной параметр Currency и результирующий параметр Currency (см. также раздел {#T}).
Внимание
- Изменено поведение метода SetAutoPrice (Live): теперь метод не учитывает активность объявлений при обновлении ставок. Ставки обновляются для всех указанных объявлений или фраз, исключая те группы объявлений, в которых все объявления помещены в архив. В частности, ставки могут быть обновлены для объявлений-черновиков, находящихся на модерации, отклоненных на модерации, остановленных. Входной параметр
BannersType
игнорируется. - Параметр CampaignID стал обязательным.
Добавлена возможность рассчитывать ставки на поиске на основе минимальной ставки за второе место в спецразмещении.
Входные данные
В методе предусмотрено два способа обновления ставок, которые имеют название SinglePrice и Wizard. Первый способ задает одинаковые ставки для всех фраз, второй рассчитывает ставку для каждой фразы.
Способ SinglePrice
Для всех фраз задается указанная ставка на поиске и указанная ставка в Рекламной сети Яндекса. Способ подходит для кампаний с малым количеством объявлений, фразы которых оцениваются примерно одинаково. В противном случае ставка может оказаться завышенной для одних фраз или заниженной для других.
Ниже показана структура входных данных в формате JSON.
{
"method": "SetAutoPrice",
"param": {
/* AutoPriceInfo */
"Mode": "SinglePrice",
"CampaignID": (int),
"BannerIDS": [
(long)
...
],
"PhraseIDS": [
(long)
...
],
"BannersType": (string),
"SinglePrice": (float),
"Price": (float),
"ContextPrice": (float),
"DontWaitForPriceUpdate": (string),
"Currency": (string)
}
}
Ниже приведено описание параметров.
Внимание
- Параметры
BannerIDS
иPhraseIDS
являются взаимоисключающими — только один из них может присутствовать в запросе. - Если не указан ни один из параметров
BannerIDS
иPhraseIDS
, ставки обновляются для всех фраз во всех объявлениях кампании.
Параметр |
Описание |
Требуется |
Объект AutoPriceInfo |
||
|
Значение “SinglePrice”. |
Да |
|
Идентификатор кампании, в которой требуется обновить ставки. |
Да |
|
Массив идентификаторов объявлений (не более 1000). Ставки обновляются только для фраз, принадлежащих указанным объявлениям в указанной кампании. Объявления, не относящиеся к указанной кампании, игнорируются. |
Нет |
|
Массив идентификаторов фраз (не более 2000). Ставки обновляются только для указанных фраз в указанной кампании. Фразы, не принадлежащие указанной кампании, игнорируются. |
Нет |
|
Отбирать объявления для обновления ставок. Параметр не используется, переданное значение игнорируется. |
Нет |
|
Ставка на поиске и в Рекламной сети Яндекса. Внимание Параметр оставлен для совместимости со стабильной версией API. В версии Live 4 используются параметры |
Либо |
|
Ставка на поиске Яндекса (в валюте, указанной в параметре |
|
Стратегия на поиске. Ниже перечислены возможные значения.
Стратегии с ручным управлением ставками на поиске:
Автоматические стратегии на поиске:
|
](* |
|
-Стратегия-на-поиске.-Ниже-перечислены-возможные-значения.----ShowsDisabled-—-выключить-показ-объявлений-на-поиске.-Это-необходимо-для-использования-автоматической-стратегии-в-Рекламной-сети-Яндекса.-Показ-на-поиске-невозможно-выключить,-если-для-Рекламной-сети-применяется-стратегия-Default.--Стратегии-с-ручным-управлением-ставками-на-поиске:----HighestPosition-—-стратегия-“Наивысшая-доступная-позиция”“Highest-available-position”;---LowestCost-—-стратегия-“Показ-в-блоке-по-минимальной-цене”“Cheapest-position-in-ad-block”;---LowestCostPremium-—-стратегия-“Показ-в-блоке-по-минимальной-цене”“Cheapest-position-in-ad-block”,-но-объявления-показываются-только-в-спецразмещении;---LowestCostGuarantee-—-стратегия-“Показ-под-результатами-поиска”“Impressions-below-search-results”-(в-нижнем-блоке-по-наименьшей-цене);---RightBlockHighest-—-стратегия-“Показ-под-результатами-поиска”“Impressions-below-search-results”-(в-нижнем-блоке-на-наивысшей-позиции,-доступной-при-указанной-ставке).--Автоматические-стратегии-на-поиске:----WeeklyBudget-—-стратегия-“Недельный-бюджет:-максимум-кликов”“Weekly-budget:-maximum-clicks”-(обязательный-параметр- |
) с ручным управлением ставками. Максимальное и минимальное значения представлены в таблице {#T}. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел {#T}). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. |
|
|
Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Параметр доступен для изменения в следующих случаях:
Максимальное и минимальное значения представлены в таблице {#T}. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел {#T}). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. |
|
|
Вызов метода в асинхронном режиме — Yes/No. Если не задано, подразумевается No. При значении Yes результирующие данные будут содержать только идентификаторы фраз, объявлений и кампаний, а цены будут назначены несколько позднее. |
Нет |
|
Валюта, в которой указаны ставки. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, переданные приложением ставки перед сохранением конвертируются в реальную валюту (см. раздел {#T}). Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245. |
Нет |
Способ Wizard
Ставка рассчитывается отдельно для каждой фразы. Базой для расчета ставки на поиске служит цена требуемой позиции показа (например, цена входа в спецразмещение). Базой для расчета ставки в Рекламной сети Яндекса служит цена, необходимая для охвата требуемой доли аудитории. К базовой цене делается надбавка.
Параметры для расчета подбирают эмпирическим путем. Оптимальные параметры позволяют рассчитать ставки, которые гарантируют показ объявлений, обеспечивают запас конкурентоспособности и в то же время не приводят к перерасходу бюджета.
Расчет ставки на поиске (Price)
-
Для расчета ставки используются значения, переданные в параметрах PriceBase, Proc, ProcBase, MaxPrice.
PriceBase
ProcBase
Формула расчета ставки
min
value
Min + Min ×
Proc
/ 100diff
Min + (Max – Min) ×
Proc
/ 100max
value
Max + Max ×
Proc
/ 100diff
Max + (PremiumMin – Max) ×
Proc
/ 100pmin или P13
value
PremiumMin + PremiumMin ×
Proc
/ 100diff
PremiumMin + ([Ставка за P12](*Ставка-за-P12) – PremiumMin) ×
Proc
/ 100P12
value
[Ставка за P12](*Ставка-за-P12) + [Ставка за P12](*Ставка-за-P12) ×
Proc
/ 100diff
[Ставка за P12](*Ставка-за-P12) + (PremiumMax – [Ставка за P12](*Ставка-за-P12)) ×
Proc
/ 100pmax или P11
value
PremiumMax + PremiumMax ×
Proc
/ 100diff
PremiumMax
Итоговая ставка ограничена параметром MaxPrice. Если рассчитанное значение превысило MaxPrice, ставка устанавливается равной MaxPrice.
Примечание
Со временем активность конкурентов может поднять цену позиции, и она превысит ставку. Чем выше надбавка, тем больше вероятность, что объявление будет показываться на выбранной позиции, но и выше возможные расходы.
Расчет ставки в Рекламной сети (ContextPrice)
-
Для расчета ставки используются значения, переданные в параметрах Scope, Proc, MaxPrice.
Если
PriceScope
— ставка, необходимая для охвата требуемой доли аудитории, то ставка составитPriceScope
+PriceScope
×Proc
/ 100Итоговая ставка ограничена параметром MaxPrice. Если рассчитанное значение превысило MaxPrice, ставка устанавливается равной MaxPrice.
Примечание
Расчет ставок по параметру
Scope
носит вероятностный характер и не гарантирует охвата требуемой доли аудитории. Расчет делается на основе статистических данных о том, при каких ставках достигается та или иная доля.
{
"method": "SetAutoPrice",
"param": {
/* AutoPriceInfo */
"Mode": "Wizard",
"CampaignID": (int),
"BannerIDS": [
(long)
...
],
"PhraseIDS": [
(long)
...
],
"BannersType": (string),
"PhrasesType": (string),
"UpdatePhrases": (string),
"UpdateCategories": (string),
"MaxPrice": (float),
"PriceBase": (string),
"Proc": (int),
"ProcBase": (string),
"Scope": (int),
"DontWaitForPriceUpdate": (string),
"Currency": (string)
}
}
Ниже приведено описание параметров.
Внимание
- Параметры
BannerIDS
иPhraseIDS
являются взаимоисключающими — только один из них может присутствовать в запросе. - Если не указан ни один из параметров
BannerIDS
иPhraseIDS
, ставки обновляются для всех фраз во всех объявлениях кампании.
Параметр |
Описание |
Требуется |
Объект AutoPriceInfo |
||
|
Значение “Wizard”. |
Да |
|
Идентификатор кампании, в которой требуется обновить ставки. |
Да |
|
Массив идентификаторов объявлений (не более 1000). Ставки обновляются только для фраз, принадлежащих указанным объявлениям в указанной кампании. Объявления, не относящиеся к указанной кампании, игнорируются. |
Нет |
|
Массив идентификаторов фраз (не более 2000). Ставки обновляются только для указанных фраз в указанной кампании. Фразы, не принадлежащие указанной кампании, игнорируются. |
Нет |
|
Отбирать объявления для обновления ставок. Параметр не используется, переданное значение игнорируется. |
Нет |
|
Указывает, какие ставки обновлять. Возможные значения:
Если не задано, подразумевается Search. Во всех случаях максимальная ставка ограничена параметром MaxPrice. |
Нет |
|
Рассчитывать ставки для фраз. Параметр не используется, переданное значение игнорируется. |
Нет |
|
Рассчитывать ставки для рубрик Яндекс Каталога. Параметр не используется, переданное значение игнорируется. |
Нет |
|
Максимальная ставка (в валюте, указанной в параметре Максимальное и минимальное значения представлены в таблице {#T}. Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел {#T}). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке. |
Нет |
|
Позиция на поиске, стоимость которой берется за основу для расчета ставок. Возможные значения:
К минимальной ставке за выбранную позицию прибавляется надбавка (см. параметры |
При |
|
Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.
|
Нет |
|
База для расчета надбавки. От нее берется процент, заданный в параметре Возможные значения:
|
При |
|
Требуемая доля аудитории Рекламной сети Яндекса в процентах от 1 до 100. Влияет только на расчет ставок в Рекламной сети Яндекса. К ставке, необходимой для охвата выбранной доли аудитории, прибавляется надбавка (см. параметр |
При |
|
Вызов метода в асинхронном режиме — Yes/No. Если не задано, подразумевается No. При значении Yes результирующие данные будут содержать только идентификаторы фраз, объявлений и кампаний, а цены будут назначены несколько позднее. |
Нет |
|
Валюта, в которой указаны ставки. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Значение должно совпадать с валютой кампании. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). В этом случае, если кампания ведется в реальной валюте, переданные приложением ставки перед сохранением конвертируются в реальную валюту (см. раздел {#T}). Если значение отлично от NULL и не совпадает с валютой кампании (одной из кампаний), возвращается ошибка с кодом 245. |
Нет |
Результирующие данные
Метод возвращает массив объектов PhrasePriceInfo
. Каждый объект соответствует фразе, для которой обновлена ставка. Ниже показана структура результирующих данных в формате JSON.
{
"data": [
{ /* PhrasePriceInfo */
"PhraseID": (long),
"BannerID": (long),
"CampaignID": (int),
"Price": (float),
"ContextPrice": (float),
"AutoBroker": (string),
"Currency": (string)
}
...
]
}
Ниже приведено описание параметров.
Параметр |
Описание |
Объект PhrasePriceInfo |
|
|
Идентификатор фразы. |
|
Идентификатор объявления. |
|
Идентификатор кампании. |
|
Новая ставка на поиске Яндекса (в валюте, указанной в параметре Если кампания ведется в реальной валюте, а ставка выражена в у. е., возвращаемое значение конвертируется из валюты кампании в у. е. и округляется вверх с точностью до шага торгов (0,01 у. е., см. также раздел {#T}). |
|
Новая ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Если кампания ведется в реальной валюте, а ставка выражена в у. е., возвращаемое значение конвертируется из валюты кампании в у. е. и округляется вверх с точностью до шага торгов (0,01 у. е., см. также раздел {#T}). |
|
Признак включенного автоброкера. Всегда содержит значение Yes. |
|
Валюта, в которой выражены ставки. Возможные значения: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. Если параметр отсутствует или равен NULL, подразумеваются условные единицы (у. е.). |
Примеры входных данных
Установить для указанных объявлений ставку, равную цене 1-го места + 30% от разницы до цены входа в спецразмещение, но не более 19,5 у. е.
Python
{
'Mode': 'Wizard',
'CampaignID': 1327944,
'BannerIDS': [1974642, 20920155, 20155899, 64654],
'PriceBase': 'max',
'ProcBase': 'diff',
'Proc': 30,
'MaxPrice': 19.5
}
PHP
array(
'Mode' => 'Wizard',
'CampaignID' => 1327944,
'BannerIDS' => array(1974642, 20920155, 20155899, 64654),
'PriceBase' => 'max',
'ProcBase' => 'diff',
'Proc' => 30,
'MaxPrice' =19.5
)
Perl
{
'Mode' => 'Wizard',
'CampaignID' => 1327944,
'BannerIDS' => [1974642, 20920155, 20155899, 64654],
'PriceBase' => 'max',
'ProcBase' => 'diff',
'Proc' => 30,
'MaxPrice' =19.5
}