rym

Загрузка данных из API Яндекс.Метрики в R

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

Menu:


rym - пакет для работы с API Яндекс Метрик

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

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

Ссылки

CRAN

Rdoc rpackages.io rank

Содержание ReadMe пакета rym

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

rym является R интерфейсом для работы с API Яндекс Метрики, его функции позволяют вам взаимодействовать со следующими API:

  1. API Управления - позволяет получить таблицы с такими объектами как достуные счётчики Яндекс.Метрики, список настроенных целей, фильтров и сегментов, а так же список пользователей у которых есть доступ к счётчику.
  2. API Отчётов - позволяет получать информацию о статистике посещений сайта и другие данные, не используя интерфейс Яндекс.Метрики.
  3. API совместимый с Core API Google Analytics (v3) - позволяет запрашивать статистические данные используя при этом название полей такие же как и при работе с Core Reporting API v3.
  4. Logs API - позволяет получить сырые, несгруппированные данные о посещении вашего сайта из Яндекс.Метрики.

Пример кода

install.packages('rym')
library(rym)

# переходим в рабочую директорию
setwd("C:\\webinars\\cybermarketing-2018")

# авторизаци под двумя разными аккаунтами
rym_auth(login = "vipman.netpeak", token.path = "metrica_token")
rym_auth(login = "selesnow", token.path = "metrica_token")


# API Управления
# получить список счЄтчиков
selesnow.counters <- rym_get_counters(login      = "selesnow",
                                      token.path = "metrica_token")

vipman.counters   <- rym_get_counters(login      = "vipman.netpeak",
                                      token.path = "metrica_token")

# получить список целей
my_goals <- rym_get_goals(counter = 10595804,
                          login      = "vipman.netpeak",
                          token.path = "metrica_token")

# получить список фильров
my_filter <- rym_get_filters(counter = 10595804,
                             login      = "vipman.netpeak",
                             token.path = "metrica_token")

# получить список сегментов
my_segments <- rym_get_segments(counter = 10595804,
                                login      = "vipman.netpeak",
                                token.path = "metrica_token")

# получить список пользователей счЄтчика
users <- rym_users_grants(counter = 10595804,
                          login      = "vipman.netpeak",
                          token.path = "metrica_token")

# API отчЄтов
reporting.api.stat <- rym_get_data(counters   = "23660530,10595804",
                                   date.from  = "2018-08-01",
                                   date.to    = "yesterday",
                                   dimensions = "ym:s:date,ym:s:lastTrafficSource",
                                   metrics    = "ym:s:visits,ym:s:pageviews,ym:s:users",
                                   sort       = "-ym:s:date",
                                   login      = "vipman.netpeak",
                                   token.path = "metrica_token",
                                   lang = "en")

# Logs API
logs.api.stat      <- rym_get_logs(counter    = 23660530,
                                   date.from  = "2018-08-01",
                                   date.to    = "2018-08-05",
                                   fields     = "ym:s:date,
                                                 ym:s:lastTrafficSource,
                                                 ym:s:referer",
                                   source     = "visits",
                                   login      = "vipman.netpeak",
                                   token.path = "metrica_token")

# API —овместимый с Core API Google Analytics v3
ga.api.stat        <- rym_get_ga(counter    = "ga:22584910",
                                 dimensions = "ga:date,ga:source",
                                 metrics    = "ga:sessions,ga:users",
                                 start.date = "2018-08-01",
                                 end.date   = "2018-08-05",
                                 sort       = "-ga:date",
                                 login      = "selesnow",
                                 token.path = "metrica_token")

Безопасность использования пакета rym

Вопрос безопасности использования разработанных мной пакетов я подробно описал в стать “Насколько безопасно использовать R пакеты для работы с API рекламных систем”, которую опубликовал на Хабре.

Авторизация в API Яндекс.Метрики осуществляется по протоколу OAuth2, если коротко этот протокол позволяет вам использовать сторонние приложения для управления своими рекламными материалами не передавая свои учётные данные, логин и пароль орт входа в аккаунт.

В пакете rym для авторизации предназначена функция rym_auth. При использовании данной функции процесс авторизации идёт по описанной тут схеме, единственным уязвимым местом в данном случае является период от момента генерация кода подтверждения до ввода его в консоль R.

Объясню почему, вот как отображаются в Google Analytics данные о посещении страницы генерации кода подтверждения.

Т.е. код идёт после знака ‘?’, и считается GET параметром, который фиксирует счётчик Google Analytics, но срок жизни такого кода подтверждения заканчивается сразу после его использования, т.е. сразу после того, как вы ввели его в консоль R. Максимальный срок жизни такого кода - 10 минут.

При этом сам токен генерируется не на сайте, а запрашивается непосредственно из R у сервера oauth.yandex.ru в обмен на авторизационный код, и через данный сайт он вообще не проходит.

ВАЖНО никому не передавайте полученные с помощью пакета rym авторизационные токены, т.к. передав токен вы предоставите доступ к управлению вашими счётчиками Яндекс.Метрики, при этом доступ к ним вы не потеряете в любом случае.

Сами токены храняться на стороне сервера oauth.yandex.ru и они недоступны человеку зарегистрировшему приложение, подробно о том как проходит авторизация на стороне Яндекса можно узнать из официальной документации в разделе “Авторизация”.

Пакет rym был опубликован в основной, официальный репозиторий хранения пакетов для языка R - CRAN. Перед публикацией на этом репозитории пакеты проходят модерацию командой специалистов, что так же гарантирует вам безопасность его использования.

Весь код пакета rym открыт, и перед его использованием вы можете ознакомиться с ним на GitHub.

Запись вебинара по работе с пакетом rym

Синтаксис пакета

Для удобства работы, и быстрого поиска функций, все функция пакета rym начинаются с префикса rym. Имена функций заданы в змеином_регистре (snake_case), т.е. название пишутся в нижнем регистре, и разделяются нижним подчёркиванием, (прим. rym_get_data). Имана аргументов, так же пишутся в нижнем регистре, но разделяются точкой (прим. token.path).

Установка rym

Пакет rym можно установить как из основного репозитория для хранения R пакетов CRAN, так и dev версию из GitHub. Установка с CRAN осуществляется стандартноой командой: install.packages("rym").

Для установки rym из GitHub вам потребуется пакет devtools.

install.packages("devtools")
devtools::install_github("selesnow/rym")

Виньетки

Виньетки это набор статей, которые состовляют документацию к пакету написанную в произвольной форме. На данный момент к пакету rym написанны следующие виньетки:

Авторизация в API Яндекс.Метрики

Для работы с API Яндекс.Метрики изначально вам необходимо пройти авторизацию, в rym для этого существует отдельная функция rym_auth. Но в целом нет необходимоси проходить авторизацию с помощью данной функции т.к. при любом обращении к API, с помощью любой из достпных в пакете функций будет запущен процесс авторизации, который в rym происходит по следующей схеме.

  1. При запуске любой функции пакета, изначально осуществляется поиск файла с учётными данными в папке, указанной в аргументе token.path. Имя файла состоит из login.rymAuth.RData, где login — значение, указанное в одноимённом аргументе. Таким образом, в ходе одной R-сессии вы можете работать со счётчиками, доступными под любым количеством пользовательских аккаунтов.
  2. Если ранее вы уже прошли процесс авторизации и дали разрешение на запись полученных учётных данных в локальный файл, то учётные данные подгрузятся оттуда.
  3. Если вы впервые проходите авторизацию или в аргументе token.path указали папку, в которой ранее не был сохранён файл с учётными данными, вас перенаправит в браузер, в котором необходимо разрешить доступ к данным вашего аккаунта. После этого вы перейдете на страницу, где будет сгенерирован семизначный код для подтверждения авторизации. Скопируйте и вставьте его в R-консоль в ответ на запрос «Enter authorize code:».
  4. Далее у вас запросят разрешение на создание полученных учётных данных в локальный файл «Do you want save API credential in local file token.path/login.rymAuth.RData for use it between R sessions?». На запрос необходимо ответить одним из таких значений: yes, ok или save.
  5. После чего в папке, указанной в аргументе token.path, сохранится файл login.rymAuth.RData и при следующих обращениях к API, в случае если вы укажите ту же папку в аргументе token.path, учётные данные для обращения к API будут загружены из файла login.rymAuth.RData.

При этом, для возможности работать в одной R сессии с различными аккаунтами Яндекс.Метрики, во всех функциях пакета вам доступны следующие аргументы:

Используя данные аргументы вы можете организовать работу сразу с несколькими пользовательскими аккаунтами в рамках одного R скрипта.

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

library(rym)
rym_auth(login      = "ваш логин",
         token.path = "C:/my_tokens/")

Перед использованием данного кода замените “ваш логин”, на логин пользователя Яндекс.Метрики под которым достпен нужный вам счёчик.

Работа с API управления

Для работы с API управления в rym вам доступны следующие функции:

Набор аргументов для всех перечисленных выше функций одинаков:

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

Списоок полей возвращаемых функцией rym_get_counters

Списоок полей возвращаемых функцией rym_get_filters

Списоок полей возвращаемых функцией rym_get_segments

Списоок полей возвращаемых функцией rym_get_goals

Списоок полей возвращаемых функцией rym_users_grants

Пример работы с API управления

При использовании приведённого нже примера замените *“ваш логин” на логин пользователя Яндекса, под которым есть доступ к нужному вам счётчику Яндекс.Метрики, вместо 000000000 введите номер нужного вам счётчика.*

library(rym)

# список доступных счётчиков
my_counters <- rym_get_counters(login      = "ваш логин",
                                token.path = "metrica_token")

# список целей
my_goals <- rym_get_goals(counter    = 000000000,
                          login      = "ваш логин",
                          token.path = "metrica_token")

# список фильтров
my_filter <- rym_get_filters(counter    = 000000000,
                             login      = "ваш логин",
                             token.path = "metrica_token")

# список сегментов
my_segments <- rym_get_segments(counter    = 000000000,
                                login      = "ваш логин",
                                token.path = "metrica_token")

# список пользователей
users <- rym_users_grants(counter    = 000000000,
                          login      = "ваш логин",
                          token.path = "metrica_token")

Работа с API отчётов

Для работы с API отчётов в rym предназначена функция rym_get_data. На данный момент rym_get_data принимает следующие аргументы:

Пример работы с API отчётов

reporting.api.stat <- rym_get_data(counters   = "00000000,111111111",
                                   date.from  = "2018-08-01",
                                   date.to    = "yesterday",
                                   dimensions = "ym:s:date,ym:s:lastTrafficSource",
                                   metrics    = "ym:s:visits,ym:s:pageviews,ym:s:users",
                                   filters    = "ym:s:trafficSourceName=='Переходы из поисковых систем' AND ym:s:isNewUser=='Yes'",
                                   sort       = "-ym:s:date",
                                   accuracy   = "full",
                                   login      = "ваш логин",
                                   token.path = "metrica_token",
                                   lang       = "ru")

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

Работа с API совместимым с Core Reporting API Google Analytics

Если вы ранее работали с Core Reporting API Google Analytics, то именно данный API будет для вас наиболее удобен, т.к. он позволяет запрашивать данные используя такие же имена полей. Для работы с этим API в rym существует функция rym_get_ga.

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

Пример работы с API совместимым с Core API Google Analytics

ga.api.stat        <- rym_get_ga(counter    = "ga:00000000",
                                 dimensions = "ga:date,ga:source",
                                 metrics    = "ga:sessions,ga:users",
                                 start.date = "2018-08-01",
                                 end.date   = "20daysAgo",
                                 filters    = "ga:source==google.ru",
                                 sort       = "-ga:date",
                                 login      = "ваш логин",
                                 token.path = "metrica_token")

Перед использованием данного примера замените значения аргументов *counter и login на ваши.*

Работа с Logs API Яндекс.Метрики

Logs API предназначен для получения несгруппированных данных из Яндекс.Метрики, на самом деле вы можете получить данные в двух группировках:

Для загрузки данных из Logs API можно использовать функцию rym_get_logs, которая принимает следующий набор аргументов.

Пример работы с Logs API Яндекс.Метрики.

logs.api.stat      <- rym_get_logs(counter    = 00000000,
                                   date.from  = "2018-08-01",
                                   date.to    = "2018-08-05",
                                   fields     = "ym:s:date,
                                                 ym:s:lastTrafficSource,
                                                 ym:s:referer",
                                   source     = "visits",
                                   login      = "ваш логин",
                                   token.path = "metrica_token")

Перед использованием данного примера замените значения аргументов counter и login на ваши.

Загрузка данных в Яндекс.Метрику

Загрузка данных о расходах на рекламу в Яндекс.Метрику

Более подробно о загрузке данных по расходам из рекламных систем в Яндекс.Метрику вы можете узнать из виньетки “rym: Загрузка данных о расходах в Яндекс.Метрику”.

Для загрузки данных о расходах вам понадобятся следующие функции:

Аргументы функций для загрузки данных о расходах

Пример кода для загрузки расходов в Яндекс.Метрику

# данные для загрузки
expense <- data.frame(Date        = c("2020-06-01",
                                      "2020-06-02"),
                      UTMSource   = c("test_s_1",
                                      "test_s_2"),
                      Expenses    = c(88.12,
                                      92.11),
                      UTMMedium   = c("cpc",
                                      "cpm"),
                      UTMCampaign = c("camp1",
                                      "camp2"),
                      UTMTerm     = c("term1",
                                      "term2"),
                      UTMContent  = c("cont1",
                                      "cont2"),
                      Currency    = c("RUB", 
                                      "RUB"),
                      Clicks      = c(11, 15))

# отправка данных в Яндекс.Метрику
rym_upload_expense(counter = 11111, 
                   data    = expense,
                   login   = 'yandex_login', 
                   token.path = "D:/packlab/rym")

# Удаление данных из Яндекс.Метрики
rym_delete_uploaded_expense(counter = 11111, 
                            data    = expense,
                            login   = 'yandex_login', 
                            token.path = "D:/packlab/rym")

# получение списка загрузок
loaded <- rym_get_uploadings_expense(counter = 11111, 
                                     login   = 'yandex_login', 
                                     token.path = "D:/packlab/rym")

Загрузка оффлайн конверсий в Яндекс.Метрику

Более подробно о загрузке оффлайн конверсий в Яндекс.Метрику вы можете узнать из виньетки “rym: Загрузка данных о расходах в Яндекс.Метрику”.

Функции для загрузки оффлайн конверсий в метрику:

Структура данных для загрузки оффлайн конверсий

Перед загрузкой, данные по оффлайн конверсии необходимо привести к нужной структуре.

Датафрейм должен содержать следующие столбцы:

Обязательные поля
Необязательные поля

Пример кода для загрузки оффлайн конверсийх в Яндекс.Метрику

library(rym)

# создаём цель для оффлайн конверсий
rym_add_goal(123456789, 
             name = 'Заказ оплачен',
             type = 'action',
             conditions = list(type = 'exact', 
                               url  = 'order_confirmed'),
             login = 'yandex_login')

# включаем учёт оффлайн конверсий
rym_enable_offline_conversion(123456789, 
                              login = 'yandex_login') 
			      
# проверка можно ли загружать данные и за какой период
rym_allow_offline_conversion(123456789, 
                             login = 'yandex_login')

# загружаем в метрику данные по оффланй конверсиям
rym_upload_offline_conversion(12345, 
                              data = conv_data,
                              client.id.type = "CLIENT_ID",
                              login = 'yandex_login')
			
# получаем список загрузок оффлайн конверсий
uploads <- rym_get_uploadings_offline_conversions(
              counter = 123456789,
              login   = 'yandex_login')

Загрузка данных о звонках в Яндекс.Метрику

Более подробно о загрузке оффлайн конверсий в Яндекс.Метрику вы можете узнать из виньетки “rym: Загрузка данных о расходах в Яндекс.Метрику”.

Функции для загрузки данных о звонках в метрику:

ПОдготовка данных о звонках для загрукзи

Перед загрузкой, данные о звонках необзодимо привести к нужной структуре:

Обязательные поля
Необязательные поля

Пример кода для загрузки данных о звонках в Яндекс.Метрику

library(rym)

# включаем учёт данных о звонках
rym_enable_calls(123456789, 
                 login = 'yandex_login') 
		 
# проверка можно ли загружать данные и за какой период
rym_allow_calls(123456789, 
                login = 'yandex_login')

# загружаем данные о звонках в метрику
rym_upload_calls(12345, 
                 data = conv_data,
                 client.id.type = "CLIENT_ID",
                 login = 'yandex_login')

# просмотр списка загрузок
uploads <- rym_get_uploadings_calls(
              counter = 123456789,
              login   = 'yandex_login')