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

Mode

Значение “SinglePrice”.

Да

CampaignID

Идентификатор кампании, в которой требуется обновить ставки.

Да

BannerIDS

Массив идентификаторов объявлений (не более 1000). Ставки обновляются только для фраз, принадлежащих указанным объявлениям в указанной кампании. Объявления, не относящиеся к указанной кампании, игнорируются.

Нет

PhraseIDS

Массив идентификаторов фраз (не более 2000). Ставки обновляются только для указанных фраз в указанной кампании. Фразы, не принадлежащие указанной кампании, игнорируются.

Нет

BannersType

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

Нет

SinglePrice

Ставка на поиске и в Рекламной сети Яндекса.

Внимание

Параметр оставлен для совместимости со стабильной версией API. В версии Live 4 используются параметры Price и ContextPrice. При этом не допускается совместное использование параметра SinglePrice и любого из параметров Price и ContextPrice.

Либо SinglePrice, либо Price и ContextPrice

Price

Ставка на поиске Яндекса (в валюте, указанной в параметре Currency). Используется, только если для кампании выбрана [

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

  • 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” (обязательный параметр WeeklySumLimit, дополнительный MaxPrice);
  • CPAOptimizer — стратегия “Недельный бюджет: максимальная конверсия”“Weekly budget: maximum conversion rate” (обязательные параметры WeeklySumLimit и GoalID, дополнительный MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа;
  • AverageClickPrice — стратегия “Средняя цена клика”“Average CPC” (обязательный параметр AveragePrice, дополнительный WeeklySumLimit);
  • WeeklyPacketOfClicks — стратегия “Недельный пакет кликов”“Weekly click package” (обязательный параметр ClicksPerWeek, дополнительные MaxPrice или AveragePrice);
  • AverageCPAOptimization — стратегия “Средняя цена конверсии”“Average CPA” (обязательные параметры AverageCPA и GoalID, дополнительные WeeklySumLimit и MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа;
  • ROIOptimization — стратегия “Средняя рентабельность инвестиций”“Average ROI” (обязательные параметры ReserveReturn, ROICoef, GoalID, дополнительные Profitability, WeeklySumLimit и MaxPrice); см. условия подключения стратегииусловия подключения стратегии в помощи Директа.

](*

-Стратегия-на-поиске.-Ниже-перечислены-возможные-значения.----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”-(обязательный-параметр-WeeklySumLimit,-дополнительный-MaxPrice);---CPAOptimizer-—-стратегия-“Недельный-бюджет:-максимальная-конверсия”“Weekly-budget:-maximum-conversion-rate”-(обязательные-параметры-WeeklySumLimit-и-GoalID,-дополнительный-MaxPrice);-см.-условия-подключения-стратегииусловия-подключения-стратегии-в-помощи-Директа;---AverageClickPrice-—-стратегия-“Средняя-цена-клика”“Average-CPC”-(обязательный-параметр-AveragePrice,-дополнительный-WeeklySumLimit);---WeeklyPacketOfClicks-—-стратегия-“Недельный-пакет-кликов”“Weekly-click-package”-(обязательный-параметр-ClicksPerWeek,-дополнительные-MaxPrice-или-AveragePrice);---AverageCPAOptimization-—-стратегия-“Средняя-цена-конверсии”“Average-CPA”-(обязательные-параметры-AverageCPA-и-GoalID,-дополнительные-WeeklySumLimit-и-MaxPrice);-см.-условия-подключения-стратегииусловия-подключения-стратегии-в-помощи-Директа;---ROIOptimization-—-стратегия-“Средняя-рентабельность-инвестиций”“Average-ROI”-(обязательные-параметры-ReserveReturn,-ROICoef,-GoalID,-дополнительные-Profitability,-WeeklySumLimit-и-MaxPrice);-см.-условия-подключения-стратегииусловия-подключения-стратегии-в-помощи-Директа.-

) с ручным управлением ставками.

Максимальное и минимальное значения представлены в таблице {#T}.

Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел {#T}). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке.

Price или ContextPrice (могут присутствовать оба)

ContextPrice

Ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Currency).

Параметр доступен для изменения в следующих случаях:

  1. Для Рекламной сети выбрана стратегия MaximumCoverage.

  2. Для Рекламной сети выбрана стратегия Default и фраза отключена на поиске за низкий CTR.

    Для новых фраз данное условие не актуально, поскольку фразы больше не отключаются за низкий CTR.

Максимальное и минимальное значения представлены в таблице {#T}.

Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел {#T}). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке.

DontWaitForPriceUpdate

Вызов метода в асинхронном режиме — Yes/No. Если не задано, подразумевается No. При значении Yes результирующие данные будут содержать только идентификаторы фраз, объявлений и кампаний, а цены будут назначены несколько позднее.

Нет

Currency

Валюта, в которой указаны ставки.

Возможные значения: 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 / 100

diff

Min + (Max – Min) × Proc / 100

max

value

Max + Max × Proc / 100

diff

Max + (PremiumMin – Max) × Proc / 100

pmin или P13

value

PremiumMin + PremiumMin × Proc / 100

diff

PremiumMin + ([Ставка за P12](*Ставка-за-P12) – PremiumMin) × Proc / 100

P12

value

[Ставка за P12](*Ставка-за-P12) + [Ставка за P12](*Ставка-за-P12) × Proc / 100

diff

[Ставка за P12](*Ставка-за-P12) + (PremiumMax – [Ставка за P12](*Ставка-за-P12)) × Proc / 100

pmax или P11

value

PremiumMax + PremiumMax × Proc / 100

diff

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

Mode

Значение “Wizard”.

Да

CampaignID

Идентификатор кампании, в которой требуется обновить ставки.

Да

BannerIDS

Массив идентификаторов объявлений (не более 1000). Ставки обновляются только для фраз, принадлежащих указанным объявлениям в указанной кампании. Объявления, не относящиеся к указанной кампании, игнорируются.

Нет

PhraseIDS

Массив идентификаторов фраз (не более 2000). Ставки обновляются только для указанных фраз в указанной кампании. Фразы, не принадлежащие указанной кампании, игнорируются.

Нет

BannersType

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

Нет

PhrasesType

Указывает, какие ставки обновлять. Возможные значения:

  • Search — ставки на поиске (см. параметры PriceBase, Proc, ProcBase).

  • Network — ставки в Рекламной сети Яндекса (см. параметры Scope и Proc). Может задаваться, если для Рекламной сети выбрана стратегия с ручным управлением ставками — MaximumCoverage или Default.

    Внимание

    При стратегии Default ставки в Рекламной сети будут обновлены только для фраз, отключенных на поиске за низкий CTR (поскольку для активных на поиске фраз ставки в Рекламной сети рассчитываются автоматически).

  • Both — и те и другие ставки.

Если не задано, подразумевается Search. Во всех случаях максимальная ставка ограничена параметром MaxPrice.

Нет

UpdatePhrases

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

Нет

UpdateCategories

Рассчитывать ставки для рубрик Яндекс Каталога. Параметр не используется, переданное значение игнорируется.

Нет

MaxPrice

Максимальная ставка (в валюте, указанной в параметре Currency).

Максимальное и минимальное значения представлены в таблице {#T}.

Если значение перед сохранением конвертируется из у. е. в валюту кампании, то оно округляется вверх с точностью до шага торгов в этой валюте (см. раздел {#T}). Если после конвертации в валюту кампании значение оказалось меньше минимальной или больше максимальной ставки в этой валюте, оно устанавливается равным минимальной или, соответственно, максимальной ставке.

Нет

PriceBase

Позиция на поиске, стоимость которой берется за основу для расчета ставок. Возможные значения:

  • min — 4-я позиция в блоке гарантированных показов;
  • max — 1-я позиция в блоке гарантированных показов;
  • pmin или P13 — 3-я позиция в спецразмещении;
  • P12 — 2-я позиция в спецразмещении;
  • pmax или P11 — 1-я позиция в спецразмещении.

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

При PhrasesType со значением Search или Both

Proc

Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.
Надбавка влияет на расчет ставок для поиска и для Рекламной сети Яндекса:

  • для поиска надбавка считается от базы, указанной в ProcBase, а результат прибавляется к цене позиции, указанной в PriceBase.
  • для Рекламной сети на указанный процент увеличивается ставка, рассчитанная в соответствии с параметром Scope.

Нет

ProcBase

База для расчета надбавки. От нее берется процент, заданный в параметре Proc. Влияет только на расчет ставок для поиска.

Возможные значения:

  • value — цена позиции, выбранной в PriceBase.

  • diff — разница в цене двух позиций: выбранной в PriceBase и следующей (например, при выборе позиции min для расчета надбавки берется разница max-min).

    При выборе позиции pmax следующая позиция отсутствует и надбавка равна нулю. Это же верно при выборе позиции max, если стоимость следующей позиции pmin меньше (редкая, но возможная ситуация).

При PhrasesType со значением Search или Both и если задан Proc

Scope

Требуемая доля аудитории Рекламной сети Яндекса в процентах от 1 до 100. Влияет только на расчет ставок в Рекламной сети Яндекса.

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

При PhrasesType со значением Network или Both

DontWaitForPriceUpdate

Вызов метода в асинхронном режиме — Yes/No. Если не задано, подразумевается No. При значении Yes результирующие данные будут содержать только идентификаторы фраз, объявлений и кампаний, а цены будут назначены несколько позднее.

Нет

Currency

Валюта, в которой указаны ставки.

Возможные значения: 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

PhraseID

Идентификатор фразы.

BannerID

Идентификатор объявления.

CampaignID

Идентификатор кампании.

Price

Новая ставка на поиске Яндекса (в валюте, указанной в параметре Currency).

Если кампания ведется в реальной валюте, а ставка выражена в у. е., возвращаемое значение конвертируется из валюты кампании в у. е. и округляется вверх с точностью до шага торгов (0,01 у. е., см. также раздел {#T}).

ContextPrice

Новая ставка в Рекламной сети Яндекса (в валюте, указанной в параметре Currency).

Если кампания ведется в реальной валюте, а ставка выражена в у. е., возвращаемое значение конвертируется из валюты кампании в у. е. и округляется вверх с точностью до шага торгов (0,01 у. е., см. также раздел {#T}).

AutoBroker

Признак включенного автоброкера. Всегда содержит значение Yes.

Currency

Валюта, в которой выражены ставки.

Возможные значения: 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
}
Предыдущая
Следующая