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

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

# Введение в работу с пакетом `rym`

[![Rdoc](http://www.rdocumentation.org/badges/version/rym)](https://www.rdocumentation.org/packages/rym)

## Содержание

* Краткое описание
* Синтаксис пакета
* Установка пакета
* Авторизация в API Яндекс.Метрики

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

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

1. [API Управления](https://yandex.ru/dev/metrika/doc/api2/management/intro-docpage) - позволяет получить таблицы с такими объектами как достуные счётчики Яндекс.Метрики, список настроенных целей, фильтров и сегментов, а так же список пользователей у которых есть доступ к счётчику.
2. [API Отчётов](https://yandex.ru/dev/metrika/doc/api2/api_v1/intro-docpage) - позволяет получать информацию о статистике посещений сайта и другие данные, не используя интерфейс Яндекс.Метрики.
3. [API совместимый с Core API Google Analytics (v3)](https://yandex.ru/dev/metrika/doc/api2/ga/intro-docpage) - позволяет запрашивать статистические данные используя при этом название полей такие же как и при работе с Core Reporting API v3.
4. [Logs API](https://yandex.ru/dev/metrika/doc/api2/logs/intro-docpage) - позволяет получить сырые, несгруппированные данные о посещении вашего сайта из Яндекс.Метрики.

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

Для удобства работы, и быстрого поиска функций, все функция пакета `rym` начинаются с префикса `rym`. 
Имена функций заданы в змеином_регистре (snake_case), т.е. название пишутся в нижнем регистре, и разделяются нижним подчёркиванием, *(прим. rym_get_data)*.
Имана аргументов, так же пишутся в нижнем регистре, но разделяются точкой *(прим. token.path)*.
## Установка rym
Пакет `rym` можно установить как из основного репозитория для хранения R пакетов CRAN, так и dev версию из GitHub.
Установка с CRAN осуществляется стандартноой командой: `install.packages("rym")`.
Для установки `rym` из GitHub вам потребуется пакет `devtools`.
```r
install.packages("devtools")
devtools::install_github("selesnow/rym")
```
## Авторизация в API Яндекс.Метрики
Для работы с API Яндекс.Метрики изначально вам необходимо пройти [авторизацию](https://yandex.ru/dev/metrika/doc/api2/intro/authorization-docpage), в `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 сессии с различными аккаунтами Яндекс.Метрики, во всех функциях пакета вам доступны следующие аргументы:
* **login** — логин пользователя, под которым вам доступен счётчик Яндекс.Метрики, из которого вы будете запрашивать данные;
* **new.user** — признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса;
* **token.path** — путь к папке, в которой будет создан файл для хранения ваших учётных данных для работы с API Яндекс.Метрики.
Используя данные аргументы вы можете организовать работу сразу с несколькими пользовательскими аккаунтами в рамках одного R скрипта.
### Пример кода для прохождения процесса авторизации
```r
library(rym)
rym_auth(login      = "ваш логин",
         token.path = "C:/my_tokens/")
```
Перед использованием данного кода замените "ваш логин", на логин пользователя Яндекс.Метрики под которым достпен нужный вам счёчик.