---
title: "rym: API управления Яндекс.Метрики"
author: "Alexey Seleznev"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{rym: API управления Яндекс.Метрики}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

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

* `rym_get_counters()` — список доступных счётчиков Яндекс.Метрики;
* `rym_get_filters()` — список настроенных фильтров в счётчике;
* `rym_get_segments()` — список настроенных сегмнтов в счётчике Яндекс.Метрики;
* `rym_get_goals()` — список настроенных целей в Яндекс.Метрике;
* `rym_get_direct_clients()` - данные о клиентах Яндекс.Директа, к кампаниям которых есть доступ у владельца счетчика Метрики;
* `rym_users_grants()` — список пользователей, у которых есть доступ к счётчику Яндекс.Метрики, с указанием уровня доступа.
* `rym_add_goal()` - создать цель в Яндекс Метрике.
* `rym_add_segment()` - создать сегмент в API Яндекс Метрики.

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

* **counter** — Id счётчика Яндекс.Метрики;
* **login** — имя пользователя, под которым доступен нужный счётчик Яндекс.Метрики. Используется при авторизации и при поиске файла, в котором хранятся учётные данные пользователя;
* **token.path** — путь к папке, в которой хранится файл с учётными данными.

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

* *id* - Номер счётчика Яндекс.Метрики.
* *status* - Статус счетчика. Active — Счетчик активен, Deleted — Счетчик удален.
* *owner_login* - Логин владельца счетчика.
* *name* - Наименование счетчика.
* *code_status* - Статус установки кода счетчика. Возможные значения:
  * CS_ERR_INFECTED — не удалось проверить (сайт, на котором установлен счетчик или одно из его зеркал находится в списке зараженных сайтов).
  * CS_NOT_FOUND — Не установлен.
  * CS_ERR_OTHER_HTML_CODE — установлен другой счетчик.
  * CS_ERR_CONNECT — не удалось проверить (ошибка соединения).
  * CS_ERR_TIMEOUT — не удалось проверить (превышено время ожидания).
  * CS_OK — Корректно установлен.
* *site* - Полный домен сайта.
* *permission* - Уровень доступа к счетчику. Возможные значения:
  * view — гостевой счетчик с уровнем доступа «только просмотр»;
  * edit — гостевой счетчик с уровнем доступа «полный доступ»;
  * own — счетчик, принадлежащий пользователю.
* *type* - Тип информера. Возможные значения:
  * ext — расширенный (по умолчанию).
  * simple — простой;
* *gdpr_agreement_accepted* - Принято соглашение gdpr.

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

* *id* - Идентификатор фильтра. 
* *attr* - Тип данных, к которым применяется фильтр. Возможные значения:
	* referer — реферер;
	* uniq_id — специальный атрибут для фильтра «не учитывать мои визиты»;
	* client_ip — IP-адрес;
	* title — заголовок страницы;
	* url — URL страницы.
* *type* - Отношение или действие для фильтра. Возможные значения:
	* equal — равно;
	* contain — содержит;
	* me — мои посещения, используется только с типом данных attr = uniq_id;
	* start — начинается с;
	* interval — в интервале, используется только с типом данных «IP-адрес» (attr = client_ip);
	* only_mirrors — только сайт и зеркала, используется только для типа данных «URL страницы» (attr = url) и типа фильтра «оставить только трафик» (action = include), а также при условии, что для счетчика заданы зеркала.
* *value* - Значение фильтра.
* *action* - Тип фильтра. include — оставить только трафик, exclude — исключить трафик.
* *status* - Статус фильтра. Возможные значения:
	* active — фильтр используется;
	* disabled — фильтр отключен (без удаления).
* *with_subdomains* - Фильтровать по поддоменам.
* *start_ip* - Первый IP-адрес диапазона.
* *end_ip* - Последний IP-адрес диапазона.

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

* *id* - Идентификатор сегмента.
* *counter_id* - Идентификатор счетчика.
* *name* - Название сегмента.
* *expression* - Выражение, которое соответствует [значению параметра filters](https://yandex.ru/dev/metrika/doc/api2/api_v1/segmentation-docpage).
* *is_retargeting* - Является ли данный сегмент ретаргетинговым
* *segment_source* - Источник сегмента. Указывает на способ его создания. Принимает значение api — используются сегменты, созданные с помощью API.

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

* *id* - Идентификатор цели.
* *name* - Наименование цели.
* *type* - Тип цели. Возможные значения.
	* number — просмотр N страниц;
	* action — цель типа событие.
	* step — составная цель;
	* url — совпадение по URL страницы;
* *is_retargeting* - Является ли цель ретаргетинговой.
* *conditions* - Cписок структур с условиями цели. Состоит из параметров *type* и *url*:
	* *type* - Тип условия. Возможные значения:
		* regexp — удовлетворяет регулярному выражению;
		* contain — содержит;
		* start — начинается с;
		* exact — совпадает;
		* action — специальный тип условия для целей типа action.
	* *url* - Адрес страницы или части страницы для условия.

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

* *id* - Идентификатор клиента Директа.
* *name* - Имя клиента, указанное в настройках Директа.
* *chief_login* - Логин главного представителя клиента в Директе. Может использоваться для формирования отчета Директ-расходы.

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

* *user_login* - Логин пользователя, которому выдано разрешение на управление счетчиком. Параметр содержит пустую строку, если к статистике счетчика предоставлен публичный доступ (perm = public_stat)
* *perm* - Уровень доступа. Возможные значения:
	* view — только просмотр;
	* edit — полный доступ;
	* public_stat — публичный доступ к статистике.
* *created_at* - Дата предоставления доступа в формате YYYY-MM-DD'T'hh:mm:ssZ.
* *comment* - Произвольный комментарий. Количество символов не должно превышать 255.
* *partner_data_access* - Является и доступ партнёрским.

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

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

```{r eval=FALSE}
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")

# список клиентов Яндекс Директ
my_clients <- rym_get_direct_clients(counters="000000000,111111111",
                                     login = "my_login",
                                     token.path = "metrica_token")

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

## Создание целей в Яндекс Метрике
Для создания цели в Яндекс Метрике используйте функцию `rym_add_goal()`.

### Аргументы
* name - Наименование цели.
* type - Тип цели. 
    * Возможные значения
        * number — просмотр N страниц;
        * action — цель типа событие.
        * step — составная цель;
        * url — совпадение по URL страницы;
* is.retargeting - Является ли цель ретаргетинговой
* flag - Тип цели для клиентов Яндекс.Маркета.
    * Возможные значения
        * basket — «корзина», страница посещения корзины;
        * order — «заказ», страница подтверждения заказа.
* conditions - Cписок структур с условиями цели.
    * type - Тип условия.
        * regexp — удовлетворяет регулярному выражению;
        * contain — содержит;
        * start — начинается с;
        * exact — совпадает;
        * action — специальный тип условия для целей типа action.
    * url - Адрес страницы или части страницы для условия.

```{r eval=FALSE}
rym_add_goal(123456789, 
             name = 'first_goal',
             type = 'action',
             conditions = list(type = 'exact', 
                               url = 'rym-first-goal'),
             login = 'your_login')
```

## Создание сегментов в Яндекс Метрике
Сегмент можно создать с помощью функции `rym_add_segment()`. Созданный с помощью API сегмент не отображается в веб-интерфейсе Яндекс.Метрики.

### Аргументы
* name - Название сегмента
* expression - Выражение, которое соответствует значению параметра [filters](https://yandex.ru/dev/metrika/doc/api2/api_v1/segmentation-docpage/).

```{r eval=FALSE}
rym_add_segment(
     counter = 123456789, 
     name = "my_segment",
     expression = "ym:s:trafficSource=='organic' AND ym:s:isNewUser=='Yes'",
     login = "your_login")
```