Author: Alexey Seleznev
Date: 2021-10-20

# Введение в Пакет rmytarget

#### Alexey Seleznev

#### 2021-10-20

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

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

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

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

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

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

    install.packages("devtools")
    library(devtools)

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

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

### Работа с обычным рекламным аккаунтом, даже если вы имете к нему доступ через агентский аккаунт

    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")

### Работа с агентским аккаунтом

    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”. Подробное описание метрик входящих в каждую группу доступно по ссылке, или чуть ниже в этой документации.
- auth - Необяхательный аргумент, объект который можно получить с помощью функции myTarAuth.
- token_path - Путь к папке в которой хранится файл с учётными данными, файл создаётся при первом обращении к API MyTarget в случае запуска любой из функций пакета, далее учётые данные подтягиваются по значению аргумента login. Будьтк внимательны, т.к. API MyTagrteg позволяет запрашивать не более 5 токен для одного аккаунта.

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

base - базовые метрики:

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

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

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

uniques - метрики по количеству уникальных пользователей:

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

video - метрики для видеорекламы:

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

viral - метрики виральных событий:

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

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

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

tps - статистика по дополнительным списаниям:

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

moat - статистика по данным сервиса moat:

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