---
title: "Введение в Пакет rmytarget"
author: "Alexey Seleznev"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Введение в Пакет rmytarget}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  eval = FALSE,
  comment = "#>"
)
```

## Краткое описание.

Пакет rmytarget помогает получить дата фрейм со списком клиентов агентств из аккаунта MyTarget, получить список и обшие параметры рекламных кампаний по каждому из проектов, а так же получить детальную статистику по кампаниям, объявлениям и клиентам за каждый день, и в целом за выбранный период.


## Установка пакета rmytarget.

Установка пакета осуществляется либо из CRAN, либо из репозитория GitHub, для этого сначала требуется установить и подключить пакет devtools.

Установка из CRAN: `install.packages("rmytarget")`

Для установка dev версии из GitHub предварительно вам необходимо установить пакет `devtools`, и уже с его помощью устанавлиать `rmytarget`:

```{r}
install.packages("devtools")
library(devtools)

# После чего можно устанавливать пакет rmytarget.
install_github('selesnow/rmytarget')
library(rmytarget)
```

## Пример кода для загрузки данных из API MyTarget

### Работа с обычным рекламным аккаунтом, даже если вы имете к нему доступ через агентский аккаунт
```{r}
library(rmytarget)

# ================
# пример работы с клиентским аккаунтом
# авторизация
# если вы работаете через агенский аккаунт то в браузере выберите пункт 
# предоставить доступ к аккаунту клиента или менеджера

myTarAuth(login = "seleznev", token_path = "tokens")

# загрузка списка рекламных кампаний и объявлений
campaing <- myTarGetCampaignList(login = "seleznev", token_path = "tokens")
ads      <- myTarGetAdList(login = "seleznev", token_path = "tokens")

# загрузка статистики по рекламным кампанийм
camp_data    <- myTarGetStats(date_from   = Sys.Date() - 7,
                              date_to     = Sys.Date(),
                              object_type = "campaigns",
                              object_id   = campaing$id,
                              stat_type   = "day",
                              login       = "seleznev", 
                              token_path  = "tokens")

# загрузка списка метрик входящих в группы "base", "tps", "viral" по объявлениям
custom_data <- myTarGetStats(date_from   = Sys.Date() - 7,
                             date_to     = Sys.Date(),
                             object_type = "banners",
                             metrics     = c("base", "tps", "viral"),
                             stat_type   = "day",
                             login       = "seleznev", 
                             token_path  = "tokens")

# загрузка всех возможных метрик с группировкой по рекламным кампаниям
all_data <- myTarGetStats(date_from   = Sys.Date() - 7,
                          date_to     = Sys.Date(),
                          object_type = "campaigns",
                          metrics     = "all",
                          login       = "seleznev", 
                          token_path  = "tokens")
```

### Работа с агентским аккаунтом
```{r}
library(rmytarget)

# авторизация
# в браузере необходимо выбрать пункт предоставить доступ к аккаунту "логин агенсткого аккаунта"
myTarAuth(login = "agency", token_path = "tokens")

# загрузка списка клиентов
clients <- myTarGetClientList(login = "agency",
                              token_path = "tokens")

# загрузка статистики с группировкой по клиентам агентского аккаунта
client_stat <-  myTarGetStats(date_from   = Sys.Date() - 7,
                              date_to     = Sys.Date(),
                              object_id   = clients$id,
                              object_type = "users",
                              metrics     = "all",
                              login       = "agency",
			      token_path = "tokens")
```

## Получение списка клиентов для агентского аккаунта.
Эта функция доступна только для агентских аккаунтов, и соответсвенно для токенов выданных агентским аккаунтам.

`myTarGetClients <- myTarGetClientList(login = "agency_login")`

Аргументы функции:

* auth - Необязательный аргумент, объект R с авторизационными данными, полученный с помощью функции myTarAuth
* login - Логин, в принципе используется только для работы с файлом в котором храняться учётные данные
* token_path - Путь к папке, в котором изначально будет сохранеён файл для хранения учётных данных, а в дальнейшем для загрузки учётных * данных, по умолчанию рабочая директория


## Получение списка рекламных кампаний.

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

`Campaign <- myTarGetCampaignList(login = "your_login")`

Аргументы функции:

* auth - Необязательный аргумент, объект R с авторизационными данными, полученный с помощью функции myTarAuth
* login - Логин, в принципе используется только для работы с файлом в котором храняться учётные данные
token_path - Путь к папке, в котором изначально будет сохранеён файл для хранения учётных данных, а в дальнейшем для загрузки учётных данных, по умолчанию рабочая директория
* request_speed - Необязательный аргумент, служит для регулировки паузы между запросами к API, что бы избежать ошибки `Too Many Requests (RFC 6585) (HTTP 429)`, т.е. при работе с большим аккаунтом может потребоваться увеличить паузы между запросами, если столкнулись с такой ошибкой установите значение "slow", при работе с аккаунтами в которых небольшое количетсво рекламных кампаний можно устанавливать значение "fast".


## Получение списка объявлений.

Для загрузки списка объявлений используйте функцию `myTarGetAdList`.

`Ads <- myTarGetAdList(login = "your_login")`

Аргументы функции:

* auth - Необязательный аргумент, объект R с авторизационными данными, полученный с помощью функции myTarAuth
* login - Логин, в принципе используется только для работы с файлом в котором храняться учётные данные
token_path - Путь к папке, в котором изначально будет сохранеён файл для хранения учётных данных, а в дальнейшем для загрузки учётных данных, по умолчанию рабочая директория
* request_speed - Необязательный аргумент, служит для регулировки паузы между запросами к API, что бы избежать ошибки `Too Many Requests (RFC 6585) (HTTP 429)`, т.е. при работе с большим аккаунтом может потребоваться увеличить паузы между запросами, если столкнулись с такой ошибкой установите значение "slow", при работе с аккаунтами в которых небольшое количетсво рекламных кампаний можно устанавливать значение "fast".

## Получение статистики по рекламным аккаунтам и объявлениям.
Для загрузки статистики необходимо использовать функцию `myTarGetStats`. Примеры её использования приведены в начале документации.

Аргументы функции:

- date_from - Дата начала отчётного периода
- date_to - Дата звершения отчётоного периода
- object_type - Тип объекта по которому будут группироваться полученные данные, возможные значения banners, campaings и users. Группировка users доступна только при работе с агентскими аккаунтами, и предназначена для загрузки статистики в разрезе клиентов агентского аккаунта. 
- object_id - Необязательный аргумент, ID объектов по которым вы хотите получить статистику, зависит от значения установленного в аргумент object_type. По умолчанию запрашивается статистика по всем объектам указанного в аргументе object_type типа.
- stat_type - Временная группировка данных, по умолчанию "day", так же можно загружать статистику за весь период указав значение "summary".
- metrics - Вектор, содержащий названия групп метрик которые вы хотите получить, по умолчанию принимает значение base, но так же вам доступны такие группы: base, events, video, viral, uniques, tps. Для загрузки всех метрик укажите значение "all". Подробное описание метрик входящих в каждую группу доступно по [ссылке](https://target.my.com/adv/api-marketing/doc/stat-v2), или чуть ниже в этой документации.
- auth - Необяхательный аргумент, объект который можно получить с помощью функции myTarAuth.
- token_path - Путь к папке в которой хранится файл с учётными данными, файл создаётся при первом обращении к API MyTarget в случае запуска любой из функций пакета, далее учётые данные подтягиваются по значению аргумента login. **Будьтк внимательны, т.к. API MyTagrteg позволяет запрашивать не более 5 токен для одного аккаунта**.

### Группы метрик которые можно задавать в аргументе metrics:



<details><summary><b>base</b> - базовые метрики:</summary>

<ul>
<li>shows - количество показов;</li>
<li>clicks - количество кликов;</li>
<li>goals - количество достижений целей (цели Top@Mail.ru для сайтов и установок для мобильных приложений);</li>
<li>spent - списания;</li>
<li>cpm - среднее списание за 1000 просмотров;</li>
<li>cpc - среднее списание за 1 клик;</li>
<li>cpa - среднее списание за достижение 1 цели;</li>
<li>ctr - процентное отношение количества кликов к количеству просмотров;</li>
<li>cr - процентное отношение количества достижений целей к количеству кликов.</li>
</ul>
	
</details>

<details><summary><b>events</b> - метрики для рекламируемых сообщений в ленте социальных сетей:</summary>

<ul>
<li>opening_app - количество открытий рекламируемого приложения соцсетей;</li>
<li>opening_post - количество открытий рекламируемого сообщения в ленте соцсетей;</li>
<li>moving_into_group - количество переходов на страницу группы из рекламируемого сообщения;</li>
<li>clicks_on_external_url - количество кликов по внешней ссылке в рекламируемом сообщении;</li>
<li>launching_video - количество запусков видео в рекламируемом сообщении;</li>
<li>comments - количество оставленных комментариев в рекламируемом сообщении;</li>
<li>joinings - количество присоединений к группе через рекламируемое сообщение;</li>
<li>likes - количество лайков рекламируемого сообщения;</li>
<li>shares - количество действий "Поделиться" для рекламируемого сообщения;</li>
<li>votings - количество действий голосования в рекламируемом сообщении.</li>
</ul>

</details>

<details><summary><b>uniques</b> - метрики по количеству уникальных пользователей:</summary>

<ul>
<li>opening_app - количество открытий рекламируемого приложения соцсетей;</li>
<li>opening_post - количество открытий рекламируемого сообщения в ленте соцсетей;</li>
<li>moving_into_group - количество переходов на страницу группы из рекламируемого сообщения;</li>
<li>clicks_on_external_url - количество кликов по внешней ссылке в рекламируемом сообщении;</li>
<li>launching_video - количество запусков видео в рекламируемом сообщении;</li>
<li>comments - количество оставленных комментариев в рекламируемом сообщении;</li>
<li>joinings - количество присоединений к группе через рекламируемое сообщение;</li>
<li>likes - количество лайков рекламируемого сообщения;</li>
<li>shares - количество действий "Поделиться" для рекламируемого сообщения;</li>
<li>votings - количество действий голосования в рекламируемом сообщении.</li>
</ul>

</details>

<details><summary><b>video</b> - метрики для видеорекламы:</summary>

<ul>
<li>started - количество стартов воспроизведения видео;</li>
<li>paused - количество пауз воспроизведения видео;</li>
<li>resumed_after_pause - количество воспроизведения видео после паузы;</li>
<li>fullscreen_on - количество включений полноэкранного режима воспроизведения видео;</li>
<li>fullscreen_off - количество выключений полноэкранного режима воспроизведения видео;</li>
<li>sound_turned_off - количество выключений звука видео;</li>
<li>sound_turned_on - количество включений звука видео;</li>
<li>viewed_10_seconds - количество просмотров первых 10 секунд видео;</li>
<li>viewed_25_percent - количество просмотров первых 25% длительности видео;</li>
<li>viewed_50_percent - количество просмотров первых 50% длительности видео;</li>
<li>viewed_75_percent - количество просмотров первых 75% длительности видео;</li>
<li>viewed_100_percent - количество просмотров 100% длительности видео;</li>
<li>viewed_10_seconds_rate - процент просмотров с достижением первых 10 секунд видео;</li>
<li>viewed_25_percent_rate - процент просмотров с достижением первых 25% длительности видео;</li>
<li>viewed_50_percent_rate - процент просмотров с достижением первых 50% длительности видео;</li>
<li>viewed_75_percent_rate - процент просмотров с достижением первых 75% длительности видео;</li>
<li>viewed_100_percent_rate - процент просмотров с достижением 100% длительности видео;</li>
<li>depth_of_view - средняя глубина просмотра видео (в процентах);</li>
<li>view_10_seconds_cost - средняя стоимость просмотра первых 10 секунд видео;</li>
<li>viewed_25_percent_cost - средняя стоимость просмотра первых 25% длительности видео;</li>
<li>viewed_50_percent_cost - средняя стоимость просмотра первых 50% длительности видео;</li>
<li>viewed_75_percent_cost - средняя стоимость просмотра первых 75% длительности видео;</li>
<li>viewed_100_percent_cost - средняя стоимость просмотра 100% длительности видео.</li>
</ul>

</details>

<details><summary><b>viral</b> - метрики виральных событий:</summary>

<ul>
<li>impressions - количество показов расшаренного рекламного сообщения в социальных сетях;</li>
<li>reach - количество уникальных пользователей, увидивших расшаренное рекламное сообщение за указанный период;</li>
<li>total - общее количество уникальных пользователей, увидевших расшаренное рекламное сообщение за всё время;</li>
<li>increment - количество новых уникальных пользователей, увидевших расшаренное рекламное сообщение за указанный период;</li>
<li>frequency - средняя частота показа расшаренного рекламного сообщения одному уникальному пользователю;</li>
<li>opening_app - количество открытий рекламируемого приложения из расшаренного рекламного сообщения;</li>
<li>opening_post - количество открытий расшаренного рекламируемого сообщения в ленте соцсетей;</li>
<li>moving_into_group - количество переходов на страницу группы из расшаренного рекламируемого сообщения;</li>
<li>clicks_on_external_url - количество кликов по внешней ссылке в расшаренном рекламируемом сообщении;</li>
<li>launching_video - количество запусков видео в расшаренном рекламируемом сообщении;</li>
<li>comments - количество оставленных комментариев в расшаренном рекламируемом сообщении;</li>
<li>joinings - количество присоединений к группе через расшаренное рекламируемое сообщение;</li>
<li>likes - количество лайков расшаренного рекламируемого сообщения;</li>
<li>shares - количество действий "Поделиться" для расшаренного рекламируемого сообщения;</li>
<li>votings - количество действий голосования в расшаренном рекламируемом сообщении.</li>
</ul>

</details>

<details><summary><b>carousel</b> - статистика по отдельным слайдам рекламной карусели (N - от 1 до количества слайдов):</summary>

<ul>
<li>slide_N_shows - количество показов слайда N;</li>
<li>slide_N_clicks - количество кликов по слайду N;</li>
<li>slide_N_ctr - процентное отношение количества кликов к количеству просмотров по слайду N;</li>
</ul>

</details>

<details><summary><b>tps</b> - статистика по дополнительным списаниям:</summary>

<ul>
<li>tps - дополнительные списания за использование сервиса moat;</li>
<li>tpd - дополнительные списания за использование сторонних данных (от dmp). </li>
</ul>

</details>

<details><summary><b>moat</b> - статистика по данным сервиса moat:</summary>

<ul>
<li>impressions - количество показов;</li>
<li>in_view - количество видимых показов;</li>
<li>never_focused - количество показов в неактивной вкладке;</li>
<li>never_visible - количество показов вне зоны видимости;</li>
<li>never_50_perc_visible - количество показов с зоной видимости объявления менее 50%;</li>
<li>never_1_sec_visible - количество показов с длительностью видимости менее 1 секунды;</li>
<li>human_impressions - количество верифицированных показов;</li>
<li>impressions_analyzed - количество анализируемых показов;</li>
<li>in_view_percent - процент видимых показов;</li>
<li>human_and_viewable_perc - процент верифицированных показов;</li>
<li>never_focused_percent - процент показов в неактивной вкладке;</li>
<li>never_visible_percent - процент показов вне зоны видимости;</li>
<li>never_50_perc_visible_percent - процент оказов с зоной видимости объявления менее 50%;</li>
<li>never_1_sec_visible_percent - процент показов с длительностью видимости менее 1 секунды;</li>
<li>in_view_diff_percent - разница в количестве видимых показов;</li>
<li>active_in_view_time - среднее время нахождения объявления в зоне видимости;</li>
<li>attention_quality - уровень вовленчения;</li>
</ul>

</details>