Управление ставками ключевых слов с помощью API Яндекс Директ

Alexey Seleznev

2023-03-17

Значительная часть представленной в этой виньетке информации взаимствована из официальной документации к API ЯндексюДирект версии 5.

Для управления ставками в пакете ryandexdirect существуют 3 функции:

Загрузка ставок и данных торгов, функция yadirGetKeyWordBids

Аргументы

Описание данных возвращаемых функцией yadirGetKeyWordBids

Дополнительные поля при запросе данных торгов на поиске AuctionBids = "network"

  • Probability - Частота показа (доля аудитории) в сетях. Указывается в процентах от 0 до 100;
  • AuctionBid - Ставка в сетях, соответствующая указанной частоте показа.

Пример кода для запроса ставок

# подключаем пакет
library(ryandexdirect)

# запрашиваем список ключевых слов
kw <- yadirGetKeyWords()
                       
# запрашиваем ставки
bids  <- yadirGetKeyWordsBids(kw$Id)

# запрашиваем ставки и данные торго на поиске
bids_search <- yadirGetKeyWordsBids(kw$Id,
                                    AuctionBids = "search")
                                    
# запрашиваем ставки и данные торго в сетях
network_bids <- yadirGetKeyWordsBids(kw$Id,
                                     AuctionBids = "network")

Назначение фиксированных ставок и приоритетов для ключевых фраз и автотаргетингов, функция yadirSetKeyWordsBids

Аргументы

Обязательно указать хотя бы один из аргументов SearchBid, NetworkBid, StrategyPriority.

Ставку или приоритет можно назначить:

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

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

Если выбрана стратегия показа в сетях MAXIMUM_COVERAGE или MANUAL_CPM, то можно указать аргумент NetworkBid.

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

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

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

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

Возвращаемый результат

В результате работы функции будет возвращён объект класса list. Данный объект будет состоять из ответов полученных на каждый запрос, название узла списка соттветвует ID вашего запроса.

Внутри лист с ответом на каждый запрос может содержать следующие данные:

Соответвенно, если в ответе вы получили список в котором содержится перечень KeywordId, AdGroupId и CampaignId, это говорит о том, что вы успешно назначили ставки.

Пример ответа в случае успешной устновки ставки:

## $`2874076041280427473`
## $`2874076041280427473`[[1]]
## $`2874076041280427473`[[1]]$KeywordId
## [1] 6402098519
##
##
## $`2874076041280427473`[[2]]
## $`2874076041280427473`[[2]]$KeywordId
## [1] 6402098520

Пример ответа в случае ошибок и предупреждений при устновке ставки:

## $`2874442110113212447`
## $`2874442110113212447`[[1]]
## $`2874442110113212447`[[1]]$Warnings
## $`2874442110113212447`[[1]]$Warnings[[1]]
## $`2874442110113212447`[[1]]$Warnings[[1]]$Code
## [1] 10160
## 
## $`2874442110113212447`[[1]]$Warnings[[1]]$Message
## [1] "Ставка не будет применена"
## 
## $`2874442110113212447`[[1]]$Warnings[[1]]$Details
## [1] "Ставки на сети не будут изменены, так как отключены показы на сети"
## 
## 
## 
## $`2874442110113212447`[[1]]$Errors
## $`2874442110113212447`[[1]]$Errors[[1]]
## $`2874442110113212447`[[1]]$Errors[[1]]$Code
## [1] 9600
## 
## $`2874442110113212447`[[1]]$Errors[[1]]$Message
## [1] "Поле не соответствует установленной стратегии"
## 
## $`2874442110113212447`[[1]]$Errors[[1]]$Details
## [1] "Для стратегии с ручным управлением ставками на поиске поле SearchBid должно быть указано"
## 
## 
## 
## 
## $`2874442110113212447`[[2]]
## $`2874442110113212447`[[2]]$Warnings
## $`2874442110113212447`[[2]]$Warnings[[1]]
## $`2874442110113212447`[[2]]$Warnings[[1]]$Code
## [1] 10160
## 
## $`2874442110113212447`[[2]]$Warnings[[1]]$Message
## [1] "Ставка не будет применена"
## 
## $`2874442110113212447`[[2]]$Warnings[[1]]$Details
## [1] "Ставки на сети не будут изменены, так как отключены показы на сети"
## 
## 
## 
## $`2874442110113212447`[[2]]$Errors
## $`2874442110113212447`[[2]]$Errors[[1]]
## $`2874442110113212447`[[2]]$Errors[[1]]$Code
## [1] 9600
## 
## $`2874442110113212447`[[2]]$Errors[[1]]$Message
## [1] "Поле не соответствует установленной стратегии"
## 
## $`2874442110113212447`[[2]]$Errors[[1]]$Details
## [1] "Для стратегии с ручным управлением ставками на поиске поле SearchBid должно быть указано"

К тому же при возникновении ошибок и предупреждений вы получите следующие сообщения:

!..Error: Для стратегии с ручным управлением ставками на поиске поле SearchBid должно быть указано
!..Error: Для стратегии с ручным управлением ставками на поиске поле SearchBid должно быть указано
...Warning: Ставки на сети не будут изменены, так как отключены показы на сети
...Warning: Ставки на сети не будут изменены, так как отключены показы на сети

Пример кода установки ставок

Если вы хотите установить ставку в поиске на уровне 9 рублей на все ключевые слова в одной рекламной кампании можете воспользоваться следующим кодом:

# подключаем пакет
library(ryandexdirect)

# запрашиваем список рекламных кампаний
camp <- yadirGetCampaign()

# меняем ставки
setbid     <- yadirSetKeyWordsBids(CampaignIds = camp$Id[1],
                                   SearchBid   = 9)

Назначить для фраз ставки на поиске в зависимости от желаемого объема трафика или ставки в сетях в зависимости от желаемой частоты показа (доли аудитории)., функция yadirSetKeyWordsBids

Аргументы

Наборы аргументов

Все аргументы функции yadirSetKeyWordsBids можно объединить в блоки.

  • Вы обязательно должны указать только один из аргументов: KeywordIds, AdGroupIds, CampaignIds.
  • Аргументы содержащие параметры для формулы расчета ставок деляться на два блока. В одном запросе вы должны использовать только один из блоков.
    • Блок аргументов установки параметров для формулы расчета ставок на поиске:
      • TargetTrafficVolume (обязательный)
      • SearchIncreasePercent
      • SearchBidCeiling
    • Блок аргументов установки параметров для формулы расчета ставок в сетях:
      • TargetCoverage (обязательный)
      • NetworkIncreasePercent
      • NetworkBidCeiling

Формула расчета ставки

Расчёт ставки на поиске:

Ставка, соответствующая объему трафика TargetTrafficVolume × (1 + SearchIncreasePercent / 100), но не более SearchBidCeiling.

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

Расчёт ставки в сетях:

Ставка, соответствующая частоте показа TargetCoverage × (1 + NetworkIncreasePercent / 100), но не более NetworkBidCeiling.

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

Ограничения

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

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

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

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

Пример кода автоматической установки ставок

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

# подключаем пакет
library(ryandexdirect)

# запрашиваем список ключевых слов
kw <- yadirGetKeyWords()

# меняем ставки
autosetbids <- yadirSetAutoKeyWordsBids(KeywordIds = kw$Id,
                                        TargetTrafficVolume = 50)

Работа с пайпланами %>%

Все функции, предназначенные для работы со ставками (yadirGetKeyWordsBids, yadirSetKeyWordsBids, yadirSetAutoKeyWordsBids) поддерживают работу с пайплайнами %>% из пакета magrittr. Данный функционал широко известен всем, кто привык использовать пакеты входящие в состав библиотеки tidyverse.

Пример кода загрузки ставок с использованием пайплана.

# подключаем пакет
library(ryandexdirect)
library(magrittr)

# загрузкса скписка ключевых слов и ставок по ним с помощью пайплайна
kw_bids <- yadirGetKeyWords() %>%
           yadirGetyadirGetKeyWordsBids()

# загрузкса скписка групп объявлений с типом "TEXT_AD_GROUP" и ставок по ключевым словам входящим в эти группы
autosetbids <-  yadirGetAdGroups(Types = "TEXT_AD_GROUP")  %>%
                yadirGetyadirGetKeyWordsBids(AdGroupIds = .)

Ссылки