rmytarget

Пакет для загрузки данных из API MyTarget в R.

Project maintained by selesnow Hosted on GitHub Pages — Theme by mattgraham

Menu:


Search:


rmytarget - пакет для работы с API MyTarget на языке R.

Поддержать проект

Вы можете поддержать проект любой произвольной суммой воспользовавшись кнопкой или перейдя по этой ссылке.

Ссылки

CRAN

Rdoc rpackages.io rank

Содержание README:

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

Пакет 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")

Авторизация в API MyTarget.

Авторизация в API через rmytarget осуществляется по схеме авторизации Authorization Code Grant, подробнее о способах авторизации можно узнать в официальной справке API MyTarget.

Пройти авторизации можно с помощью функции myTarAuth:

myTarAuth(login = "my_test_client",
          token_path = "mt_tokens")

Аргументы:

Помните что в API MyTarget вы можете запрашивать всего 5 токенов для одного аккаунта.

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

Для работы с агентским аккаунтом выберите верхний пункт.

генерация токена для агентского аккаунта

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

Если же вам необходимо получить какие либо данные из подчинённого клиентского аккаунта то при авторизации через браузер выберите пункт “Предоставить доступ к аккаунту клиента или менеджера”.

Генерация токена для работы с клеинтским аккаунтом

Далее необходимо нажать кнопку подтверждения доступа, после чего вы будете перенаправлены на страницу где вам необходимо скопировать код подтверждения доступа к API.

Скопированный код необходимо ввести в консоль RStudio, в качестве ответа на запрос Enter code from browser:.

Если до этого момента вы сделали всё правильно в консоле будет выведено количество оставшихся токенов для данного аккаунта.

You tokens left for this account: 2, что говорит о том, что для данного аккаунта можно запросить ещё 2 токена.

И будет выведен запрос, разрешаете ли вы сохранить полученный токен в локальный файл на ваш жесткий диск, для того, что использовать его между разными сессиями работы в R, и не проходить постоянно процесс авторизации в браузере. Do you want save API credential in local file (C:/webinars/automationday-2018/my_login.rymAuth.RData), for use it between R sessions?. Напоминаю что вы можете получить всего 5 токенов на 1 аккаунт, поэтому я крайне рекомендую сохранять полученные токены в файл, и в качестве ответа на этот запрос ввести y или yes, в противном случае вы загрузите данные, но токен сохранён не будет, и вам при следующем обращении к API понадобиться повторно его запрашивать.

Если вы согласились, и всё сделали правильно то в консоль будет выведено сообщение Token saved at C:/webinars/automationday-2018/my_login.mytar.Auth.RData.

Далее в рабочей директории будет создан файл хранящий учётные данные, название файла будет начинаться с указаннолого логина и далее .mytar.Auth.RData.

При каждом обращении к API будет проверяться скрок действия токен, если срок заканчивается менее чем через 30 минут то токен авточески будет обновлён.

На самом деле проходить авторизацию отдельно через функцию myTargetAuth необзательно, т.к. при запуске любой из доступных в пакете функций процесс авторизации будет запущен автоматически.

Другие схемы авторизации

Так же rmytarget поддерживает и другие схемы авторизации. Но для прохождения аутентификации с их помощью вам для начала надо самостоятельно получить доступ к API, о том как это сделать вы можете узнать по этой ссылке. На данный момент он предоставляется только юр.лицам в ручном режиме.

В зависимости от типа вашего аккаунта вам необходимо получить токен доступа согласно типу вашего аккаунта в MyTarget. Пройти авторизацию для обычного клиентского аккаунта так ж можно по сехеме Client Credentials Grant для обычного рекламодателя и для агентства.

Получение токена для обычного рекламного аккаунта.

myTargetAuth <- myTarAuth(grant_type = "client_credentials",
                          client_id = "XXXXXXXXXX",
                          client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
			  code_grant = FALSE)

Аргументы: grant_type - Тип вашего аккаунта, в данном случае обычный клиентский аккаунт. client_id - ID выдаётся вам при подтверждение доступа к API MyTarget. client_secret - Выдаётся вам при подтверждение доступа к API MyTarget вместе с Client ID.

Получение токена для агентского аккаунта.

myTarGetAuth <- myTarAuth(grant_type = "agency_client_credentials",
                          client_id = "XXXXXXXXXX",
                          client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                          agency_client_name = "xxxxxxxxx@agency_client",
			  code_grant = FALSE)

Вариант grant_type=agency_client_credentials не является стандартным для OAuth2. Он реализован для того, чтобы агентства могли создавать access-токены для своих клиентов напрямую. Помимо параметров client_id, client_secret нужно передавать agency_client_name. Для получения информации по агентскому аккаунту, например поучить список клиентов агентсва необходимо следовать первой описанной схеме с grant_type = “client_credentials” и получить токен агентского аккаунта.

##Обновление токена доступа При авторизации по схеме Authorization Code Grant, которая установлена в rmytarget по умолчанию, обновлять токены вам не потребуются, во первых потому, что вы получаете бессрочный токен, а во вторых при работе по этой схеме пакет при необходимости сам будет обновлять токеню

При работе со схемамы авторизации Client Credentials Grant и Agency Credentials Grant. Каждый полученный access-токен является действительным в течение суток. На это указывает свойство expires_in в ответе на запрос access-токена. Для обновления токета в пакете rmytarget есть функция myTarRefreshToken

myTarGetAuth <- myTarRefreshToken(old_auth = myTargetAuth,
                                  client_id = "xxxxxxxxx",
                                  client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxx...")

Аргументы функции: old_auth - R объект с учётными данными полученный с помощью функции myTarAuth. client_id - ID выдаётся вам при подтверждение доступа к API MyTarget. client_secret - Выдаётся вам при подтверждение доступа к API MyTarget вместе с Client ID.

Подробную информацию о схеме аутинтификации в API вы можете получить по ссылке.

Получение списка клиентов для агентского аккаунта.

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

myTarGetClients <- myTarGetClientList(login = "agency_login")

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

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

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

Campaign <- myTarGetCampaignList(login = "your_login")

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

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

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

Ads <- myTarGetAdList(login = "your_login")

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

Получение статистики по рекламным аккаунтам и объявлениям.

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

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

Группы метрик которые можно задавать в аргументе 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 - уровень вовленчения;

Автор пакета: Алексей Селезнёв, Head of Analytics Dept. at Netpeak

Контакты
email: selesnow@gmail.com
skype: selesnow
telegram: @AlexeySeleznev
Facebook Vkontakte Linkedin Blog GitHub Stepic