---
title: "Управление ставками ключевых слов с помощью API Яндекс Директ."
author: "Alexey Seleznev"
output: rmarkdown::html_vignette
date: "`r Sys.Date()`"
vignette: >
  %\VignetteIndexEntry{Keyword Bids Managment by 'Yandex Direct' API RUS}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  eval = FALSE,
  collapse = TRUE,
  comment = "#>"
)
```
Значительная часть представленной в этой виньетке информации взаимствована из [официальной документации](https://tech.yandex.ru/direct/doc/ref-v5/bids/bids-docpage/) к API ЯндексюДирект версии 5.

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

* `yadirGetKeyWordsBids` - Возвращает ставки и приоритеты для ключевых фраз и автотаргетингов, отвечающих заданным критериям, а также данные торгов: ставки и списываемые цены для различных объемов трафика на поиске и ставки для охвата различных долей аудитории в сетях.
* `yadirSetKeyWordsBids` - Назначает фиксированные ставки и приоритеты для ключевых фраз и автотаргетингов.
* `yadirSetAutoKeyWordsBids` - Назначает для фраз ставки на поиске в зависимости от желаемого объема трафика или ставки в сетях в зависимости от желаемой частоты показа (доли аудитории).

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

### Аргументы

* KeywordIds - Идентификатор ключевой фразы или автотаргетинга;
* AdGroupIds - Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг;
* CampaignIds - Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг;
* AuctionBids - Тип аукционов данные о торгах на которым вы хотите получить, возможные значения:
    * `NA` - Не загружать данные торгов;
    * `search` - Получить данные ставок и списываемых цен на поиске, соответствующих различным объемам трафика;
    * `network` - Получить массив ставок, соответствующих охвату различных долей аудитории.

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

* CampaignId - Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг;
* AdGroupId - Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг;
* KeywordId - Идентификатор ключевой фразы или автотаргетинга;
* ServingStatus - Статус возможности показов группы объявлений:
    * ELIGIBLE - Показы возможны;
    * RARELY_SERVED - "Мало показов" — при текущих настройках показы происходят крайне редко. Например, ключевые фразы не встречаются в поисковых запросах пользователей.
* StrategyPriority - Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH.
* SearchBib - Ставка на поиске, назначенная рекламодателем;
* NetworkBid - Ставка в сетях, назначенная рекламодателем.

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

* AuctionTrafficVolume - Объем трафика;
* AuctionBid - Ставка на поиске, соответствующая указанному объему трафика;
* AuctionPrice - Списываемая цена, соответствующая указанному объему трафика.

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

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

### Пример кода для запроса ставок
```{r}
# подключаем пакет
library(ryandexdirect)

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

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


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

### Аргументы

* KeywordIds - Идентификатор ключевой фразы или автотаргетинга;
* AdGroupIds - Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг;
* CampaignIds - Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг;
* StrategyPriority - Приоритет фразы: LOW, NORMAL или HIGH. Только для автоматической стратегии.
* SearchBid - Ставка на поиске. Только для ручной стратегии. Указывается в валюте рекламодателя.
* NteworkBid - Ставка в сетях. Только для ручной стратегии с независимым управлением ставками в сетях. Указывается в валюте рекламодателя. 

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

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

* для отдельной ключевой фразы или автотаргетинга с помощью аргумента *KeywordIds*;

* для всех ключевых фраз и автотаргетинга в группе объявлений с помощью аргумента *AdGroupIds*;

* для всех ключевых фраз и автотаргетингов в кампании с помощью аргумента *CampaignIds*.

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

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

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

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

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

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

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

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

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

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

* SetResults - Результаты назначения ставок и/или приоритетов
    * Warnings - Предупреждения, возникшие при выполнении операции
    * Errors - Ошибки, возникшие при выполнении операции.
    * CampaignId - Идентификатор кампании. Возвращается в случае отсутствия ошибок.
    * AdGroupId - Идентификатор группы объявлений. Возвращается в случае отсутствия ошибок.
    * KeywordId - Идентификатор ключевой фразы или автотаргетинга. Возвращается в случае отсутствия ошибок.

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

Пример ответа в случае успешной устновки ставки:
```{r}
## $`2874076041280427473`
## $`2874076041280427473`[[1]]
## $`2874076041280427473`[[1]]$KeywordId
## [1] 6402098519
##
##
## $`2874076041280427473`[[2]]
## $`2874076041280427473`[[2]]$KeywordId
## [1] 6402098520
```

Пример ответа в случае ошибок и предупреждений при устновке ставки:
```{r}
## $`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 должно быть указано"
```

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

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

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

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

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

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

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

### Аргументы

* KeywordIds - Идентификатор ключевой фразы или автотаргетинга;
* AdGroupIds - Идентификатор группы объявлений, к которой относится ключевая фраза или автотаргетинг;
* CampaignIds - Идентификатор кампании, к которой относится ключевая фраза или автотаргетинг;
* TargetTrafficVolume - Желаемый объем трафика на поиске. Указывается в процентах от 5 до 100. К ставке, соответствующей выбранному объему трафика, прибавляется надбавка (см. аргумент *SearchIncreasePercent*).
* SearchIncreasePercent - Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.
* SearchBidCeiling - Ограничение на ставку. Целое число. Указывается в валюте рекламодателя.
* TargetCoverage - Желаемая частота показа (доля аудитории) в сетях. Указывается в процентах от 1 до 100. К ставке, соответствующей выбранной частоте показа, прибавляется надбавка (см. параметр *NetworkIncreasePercent*).
* NetworkIncreasePercent - Процент надбавки от 0 до 1000. Если не задан, надбавка не рассчитывается.
* NetworkBidCeiling - Ограничение на ставку, умноженное на 1 000 000. Целое число. Указывается в валюте рекламодателя. 

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

Все аргументы функции `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% соответвующих поисковых запросах воспользуйтесь кодом.

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

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

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

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


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

### Пример кода загрузки ставок с использованием пайплана.
```{r}
# подключаем пакет
library(ryandexdirect)
library(magrittr)

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

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

## Ссылки

* [Справка Яндекс.Директ по сервису KeywordBids.](https://tech.yandex.ru/direct/doc/ref-v5/keywordbids/keywordbids-docpage/)
* [Справка Яндекс.Директ по методу get сервиса KeywordBids.](https://tech.yandex.ru/direct/doc/ref-v5/keywordbids/get-docpage/)
* [Справка Яндекс.Директ по методу set сервиса KeywordBids.](https://tech.yandex.ru/direct/doc/ref-v5/keywordbids/set-docpage/)
* [Справка Яндекс.Директ по методу setAuto сервиса KeywordBids.](https://tech.yandex.ru/direct/doc/ref-v5/keywordbids/setAuto-docpage/)
* [Руководство разработчика Яндекс.Директ по ставкам и приоритетам.](https://tech.yandex.ru/direct/doc/dg/objects/bid-priority-docpage/)