Просмотр исходного текста страницы R:Google Analytics

{{CC-BY-4.0|author=авторами Филипп Управителев и Артём Клевцов}}

{{Pkg-req-notice}}

== Общее описание ==

На данный момент, несмотря на все многообразие, в официальном репозитории CRAN нет пакетов для работы с API Google Analytics. Однако на сторонних ресурсах, тем не менее, можно обнаружить три рабочих решения: [https://code.google.com/p/r-google-analytics/ <code>RGoogleAnalytics</code>], [http://skardhamar.github.io/rga/ <code>rga</code>], [https://github.com/jdeboer/ganalytics <code>ganalytics</code>] и [https://bitbucket.org/unikum/rga RGA]. <ref>Пакеты <code>rga</code>, <code>ganalytics</code> и <code>RGA</code> в ближайшее время могут появиться и в CRAN, работы в этом направлении уже ведутся.</ref>

Сравнительная таблица пактов для работы с API Google Analytics:

{| class="wikitable sortable" width="800px"
! width="40%" | Параметры сравнения
! width="20%" | [https://code.google.com/p/r-google-analytics/ RGoogleAnalytics]
! width="20%" | [https://github.com/skardhamar/rga rga]
! width="20%" | [https://github.com/jdeboer/ganalytics ganalytics]
! width="20%" | [https://bitbucket.org/unikum/rga RGA]
|-
! colspan=5 | Общая информация
|-
| Размещение
| style="text-align:center" | [https://code.google.com/p/r-google-analytics/ Google Code]
| style="text-align:center" | [https://github.com/skardhamar/rga GitHub]
| style="text-align:center" | [https://github.com/jdeboer/ganalytics GitHub]
| style="text-align:center" | [https://bitbucket.org/unikum/rga Bitbucket]
|-
| Дата публикации
| style="text-align:center" | 29.09.2010
| style="text-align:center" | 27.11.2012
| style="text-align:center" | 25.05.2013
| style="text-align:center" | 3.06.2014
|-
| Дата последней стабильной версии
| style="text-align:center" | 9.09.2013<ref>В апреле 2014 были внесены значительные изменения в код проекта, но после их внесения стабильного выпуска пока нет.</ref>
| style="text-align:center" | 1.06.2014<ref>Дата последней правки на данный момент, т.к. релизы данного пакета отсутствуют.</ref>
| style="text-align:center" | 4.08.2014<ref>Дата последней правки на данный момент, т.к. релизы данного пакета отсутствуют.</ref>
| style="text-align:center" | 5.08.2014<ref>Дата последней правки на данный момент, т.к. релизы данного пакета отсутствуют.</ref>
|-
| Лицензия
| style="text-align:center" | Apache 2.0
| style="text-align:center" | GPL2
| style="text-align:center" | MIT
| style="text-align:center" | GPL2
|-
| Зависимости
| style="text-align:center" | <code>RCurl</code>, <code>rjson</code>, <code>lubridate</code>
| style="text-align:center" | <code>RCurl</code>, <code>httr</code>, <code>jsonlite</code>, <code>lubridate</code>
| style="text-align:center" | <code>httr</code>, <code>plyr</code>, <code>stringr</code>, <code>jsonlite</code>, <code>httpuv</code>
| style="text-align:center" | <code>RCurl</code>, <code>httr</code>, <code>jsonlite</code>
|-
! colspan=5 | Авторизация
|-
| Авторизация по логину и паролю
| style="text-align:center" | +
| style="text-align:center" | -
| style="text-align:center" | -
| style="text-align:center" | -
|-
| Авторизация [https://developers.google.com/accounts/docs/OAuth2 OAuth2]<ref>Авторизация по Client ID и Client secret, полученным в [https://console.developers.google.com API Console].</ref>
| style="text-align:center" | +
| style="text-align:center" | +
| style="text-align:center" | +
| style="text-align:center" | +
|-
! colspan=5 | Доступ к API
|-
| Доступ к [https://developers.google.com/analytics/devguides/reporting/core/v3/ API базовых отчётов]
| style="text-align:center" | +
| style="text-align:center" | +
| style="text-align:center" | +
| style="text-align:center" | +
|-
| Доступ к [https://developers.google.com/analytics/devguides/reporting/mcf/v3/ API отчётов<br />многоканальных последовательностей]
| style="text-align:center" | -
| style="text-align:center" | +
| style="text-align:center" | -
| style="text-align:center" | +
|-
| Доступ к [https://developers.google.com/analytics/devguides/config/mgmt/v3/ API конфигурации]<ref>Информация по аккаунтам, профилям, представлениям, сегментам и целям.</ref>
| style="text-align:center" | +
| style="text-align:center" | +
| style="text-align:center" | -
| style="text-align:center" | +
|-
| Пакетная обработка запросов<ref>Pagination - получение данных, превышающих ограничения Google (1000 на один запрос) путем организации нескольких запросов.</ref>
| style="text-align:center" | +
| style="text-align:center" | +
| style="text-align:center" | +
| style="text-align:center" | +
|}

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

Так, пакет <code>RGoogleAnalytics</code> основан на использовании простых функции и S3-методов, но по внутренней организации похож на RC (Reference classes). Пакет <code>rga</code> целиком основан на использовании RC. Пакет <code>ganalytics</code> основан на использовании S4 классов и методов, что обеспечивает более точный контроль над вводимыми аргументами <ref>Получить обобщённое представление об принципах и реализации ООП в R можно [http://adv-r.had.co.nz/OO-essentials.html#rc здесь]</ref>. При определенных различиях в реализации доступа к GA API, все пакеты, тем не менее, основываются на функционале пакета <code>httr</code>.

В плане подробности документации, бесспорно, выигрывает пакет <code>ganalytics</code>. Он обладает довольно подробным <code>README</code> файлом, расположенном на странице проекта [https://github.com/jdeboer/ganalytics ganalytics], и описывающим практически весь функционал пакета. Помимо этого, пакет также содержит полную документацию всех функций, которая поставляется вместе с пакетом. Пакет <code>rga</code> обладает <code>README</code> файлом, описывающем лишь основы работы с пакетом и не включает в себя описание ряда возможностей пакета. Справка по функциям, доступная при установке пакета, содержит только краткое описание процедуры получения доступа к GA API и описание структуры запроса к API. Другие полезные функции, в частности, получение списка доступных профилей GA-аккаунта, приходится искать вслепую. Документация пакета <code>RGoogleAnalytics</code> также имеет файл <code>README</code>, в котором пошагово описан процесс работы с пакетом, включающим весь функционал.

В плане простоты использования, в свою очередь. лидирует пакет <code>rga</code>. В отличие от <code>ganalytics</code>, пакет <code>rga</code> позволяет указывать метрики, измерения, узкие сегменты и фильтры в виде аргументов сразу, в одной функции, что упрощает понимание структуры запроса и сегмента, и позволяет обрабатывать множество однотипных сегментов (например, страниц сайта) в цикле или <code>[a-z]pply</code>-функциях. Также <code>ganalytics</code> не имеет внутренних инструментов получения ID профилей, а их получение из web-интерфейса Google Analytics с последующей вставкой в запросы <code>ganalytics</code> трудоемко и, самое главное, неинтуитивно. <code>RGoogleAnalytics</code>, несмотря на достаточно подробную документацию и достаточный для полноценной работы функционал, обладает несколько непрозрачной и неочевидной структурой запросов к GA API.

== Получение ключей для доступа к API Google Analytics ==

Прежде чем приступить к работе с пакетами, предназначенными для работы с Google Analytics API, необходимо создать новое приложение в [https://console.developers.google.com Google Developers Console] и получить '''Client ID''' (идентификатор клиента) и '''Client secret''' (секретный ключ клиента) для доступа к API Google Analytics. Не смотря на то, что некоторые пакеты, например <code>rga</code>, предоставляют ключи доступа, сгенерированные автором пакета, мы всё же рекомендуем получить собственные ключи, т.к. сторонние ключи могут быть в любой момент отозваны автором.

Пошаговая инструкция приведена ниже:

# Создание нового проекта (можно пропустить, если проект уже создан):
#* Откройте страницу https://console.developers.google.com/project;
#* В левой верхней части страницы нажмите на красную кнопку с надписью '''Create Project''';
#* Во всплывающем окне в поле '''PROJECT NAME''' введите название проекта;
#* Подтвердите создание проекта, нажав на кнопку '''Create'''.
# Активация доступа к API Google Analytics:
#* Выберите проект в списке проектов на странице https://console.developers.google.com/project;
#* На боковой панели слева выберите пункт '''APIs & auth''';
#* на вкладке '''APIs''' активируйте '''Analytics API''', нажав на кнопку с надписью `OFF` (убедитесь, что вместо надписи `OFF` появилось `ON`).
# Создание нового приложения:
#* В боковой панели слева выберите пункт '''APIs & auth''', подпункт '''Credentials''';
#* В левой части страницы нажмите на кнопку с надписью '''Create new Client ID''';
#* Во всплывающем окне выберите пункт '''Installed application''' в списке '''APPLICATION TYPE''' и пункт '''Other''' в списке '''INSTALLED APPLICATION TYPE'''.
#* Подтвердите создание приложения, нажав на кнопку с надписью '''Create Client ID'''.
# Получение Client ID и Client secret:
#* Выберите проект в списке проектов на странице https://console.developers.google.com/project;
#* В боковой панели слева выберите пункт '''APIs & auth''', подпункт '''Credentials''';
#* В таблице с названием '''Client ID for native application''' скопируйте значения полей '''Client ID''' и '''Client secret'''.

Теперь вы в любой момент можете вернуться на страницу '''Credentials''' и узнать '''Client ID''' и '''Client secret'''.

== Пакет <code>rga</code> ==

=== Установка пакета ===

Исходный код пакета <code>rga</code> располагается на [https://github.com github], поэтому установить его можно с помощью функции <code>install_github</code> из пакета {{r-package|devtools}}:

{{r-code|code=<nowiki>> devtools::install_github("rga", "skardhamar")</nowiki>}}

=== Авторизация ===

Перед началом работы необходимо загрузить пакет <code>rga</code> (требуется только в начале работы при запуске новой R-сессии):

{{r-code|code=<nowiki>> library(rga)</nowiki>}}

Для предоставления доступа к данным Google Analytics API из пакета <code>rga</code> неободимо пройти процедуру авторизации. Для этого используется функция <code>rga.open</code>, которая принимает следующие аргументы:

* <code>instance</code> - имя переменной, которая будет содержать информацию о доступе к APi Google Analytics;
* <code>where</code> - путь и/или имя файла, который будет использоваться для кэширования информации;
* <code>client.id</code> - ID клиента;
* <code>client.secret</code> - секретный ключ.

Для получения токена доступа потребуется переход в браузер, подтверждение доступа и копирование код доступа в консоль. Опционально команда создает отдельный файл, который потом можно использовать для аутентификации без перехода в браузер<ref>Аргумент <code>where</code> с указанием пути и имени файла.</ref>.

{{r-code|code=<nowiki>> rga.open(instance = "ga", where = "ga.rga")</nowiki>}}

Видим, что в директории проекта появился файл <code>ga.rga</code><ref>Можно указать любой удобный путь и имя файла.</ref>. Теперь при повторном использовании этой команды будет осуществляться проверка наличия файла <code>ga.rga</code> в рабочей директории и, если такой файл будет найден, то данные для аутентификации будут взяты из данного файла.

Второй вариант аутентификации с использованием собственных ключей доступа:

{{r-code|code=<nowiki>> rga.open(instance = "ga", client.id = "XXXXXX", client.secret = "XXXXXXX", where = "ga.rga")</nowiki>}}

После выполнения данной команды будет открыт интернет браузер со страницей запроса подтверждения разрешения на доступ к данным Google Analytics. Необходимо авторизоваться под своей учётной записью Google и подтвердить разрешение на доступ к данным Google Analytics. Отметим, что пакет `RGA` запрашивает доступ '''только для чтения''' данных.

После успешной аутентификации информацию о установленном подключении можно получить с помощью команды <code>ga$status()</code> или более подробную информацию <code>ga$show()</code>.

=== Получение данных ===

Пакет <code>rga</code> позволяет получить доступ к различным API Google Analytics. Поскольку объекты, формируемые пакетом <code>rga</code>, относятся к классу <code>refClass</code>, что не является широко распространённой системой в данный момент, то ниже мы проведём небольшой обзор доступных функций и методов.

Получить общую информацию о классе <code>rga</code> можно с помощью функции <code>getRefClass()</code>:

{{r-code|code=<nowiki>> getRefClass(Class = "rga")
Generator for class "rga":

Class fields:
                                                              
Name:      client.id client.secret         where         token
Class:     character     character     character          list

 Class Methods:  
    "callSuper", "copy", "explore", "export", "field", "getAccounts", "getClass", "getData", 
"getDataInBatches", "getDataInWalks", "getFirstDate", "getGoals", "getMCFData", 
"getMCFDataInBatches", "getMCFDataInWalks", "getProfiles", "getRefClass", "getSegments", 
"getToken", "getWebProperties", "import", "initFields", "initialize", "isToken", "isTokenExpired", 
"isWhere", "prepare", "processManagementData", "refreshToken", "setToken", "show", "status", 
"tokenExpiresIn", "trace", "untrace", "usingMethods"


 Reference Superclasses:  
    "envRefClass"
</nowiki>}}

Получить информацию о всех методах, доступных для класса <code>rga</code> можно с помощью команды <code>rga$methods()</code>:

{{r-code|code=<nowiki>> rga$methods()
 [1] "callSuper"           "copy"                "explore"             "export"              "field"               "getAccounts"        
 [7] "getClass"            "getData"             "getDataInBatches"    "getDataInWalks"      "getFirstDate"        "getGoals"           
[13] "getMCFData"          "getMCFDataInBatches" "getMCFDataInWalks"   "getMGMTData"         "getProfiles"         "getRefClass"        
[19] "getSegments"         "getToken"            "getWebProperties"    "import"              "initFields"          "initialize"         
[25] "isToken"             "isTokenExpired"      "isWhere"             "prepare"             "refreshToken"        "setToken"           
[31] "show"                "status"              "tokenExpiresIn"      "trace"               "untrace"             "usingMethods"  
</nowiki>}}

Наиболее полезными являются:

* <code>getAccounts</code> - получение списка аккаунтов в, к которым пользователь имеет доступ;
* <code>getData</code> - получение данных из GA API базового отчёта;
* <code>getFirstDate</code> - получения даты начала сбора статистики для данного id;
* <code>getGoals</code> - получение списка целей;
* <code>getMCFData</code> - получение данных из GA API многоканальных последовательностей;
* <code>getProfiles</code> - получение списка ресурсов и представлений сайтов, к которым пользователь имеет доступ<ref>Можно указать <code>accountId</code> (по умолчанию будет выведена информацию по всем аккаунтам).</ref>;
* <code>getSegments</code> - получение списка сегментов;
* <code>getToken</code> - получение токена дотупа;
* <code>getWebProperties</code> - получение списка ресурсов, к которым пользователь имеет доступ<ref>Можно указать <code>accountId</code> (по умолчанию будет выведена информацию по всем аккаунтам).</ref>;
* <code>refreshToken</code> - обновление токена доступа;
* <code>show</code> - получение подробной информации о данных подключения к GA;
* <code>status</code> - получение краткой информации о статусе подключения к GA;

Получить справку по тому или иному методу можно с помощью команды <code>rga$help(topic)</code>, где вместо <code>topic</code> нужно подставить название интересующего метода:

{{r-code|code=<nowiki>> rga$help("getWebProperties")
Call:
$getWebProperties(accountId = , start = , max = )
</nowiki>}}
Вызов метода осуществляется аналогично доступу к элементам списка посредством оператора <code>$</code>. После создания объекта с помощью функции <code>rga.open()</code> к методам можно обратиться с помощью конструкции <code>object$methodName()</code>, где <code>object</code> - имя, которое было указано в качестве аргумента <code>instance</code> при вызове функции <code>rga.open()</code>, а <code>methodName()</code> - один из вышеперечисленных методов.

Узнать какие аргументы, а также их значения по умолчанию, можно передать тому или иному методу можно узнать с помощью функции <code>args</code>. Например:

{{r-code|code=<nowiki>> args(ga$getData)
function (ids, start.date = format(Sys.time(), "%Y-%m-%d"), end.date = format(Sys.time(), 
    "%Y-%m-%d"), date.format = "%Y-%m-%d", metrics = "ga:users,ga:sessions,ga:pageviews", 
    dimensions = "ga:date", sort = "", filters = "", segment = "", 
    fields = "", start = 1, max, messages = TRUE, batch, walk = FALSE, 
    output.raw, output.formats, return.url = FALSE, rbr = FALSE, 
    envir = .GlobalEnv) 
NULL
</nowiki>}}

Пакет <code>rga</code> поддерживает работу как с [https://developers.google.com/analytics/devguides/reporting/core/v3/ API отчётов], так и с [https://developers.google.com/analytics/devguides/reporting/mcf/v3/ API многоканальных последовательностей].

Получения данных базовых отчётов:

{{r-code|code=<nowiki>> ga$getData(id, start.date, end.date, metrics, dimensions)</nowiki>}}

Получение данных по многоканальным последовательностям можно получить через функцию <code>ga$getMCFData()</code>. Аргументы методов <code>getData</code> и <code>getMCFData</code> совпадают<ref>Отличием является содержание показателей и измерений.</ref>.

Пояснения по значениям аргументов для метода <code>getData</code>:

* <code>ids</code> - ID профиля, из которого нужно выгрузить данные;
* <code>start.date</code> - символьная строка, которая задаёт стартовое время в формате <code>YYYY-MM-DD</code><ref>Получить начальную дату сбора статистики в GA можно с помощью команды <code> ga$getFirstDate(id)</code>.</ref>. Допускаются также значения "today", "yesterday", "ndaysAgo", где <code>n</code> - это количество дней;
* <code>end.date</code> - символьная строка, которая задаёт конечное время в формате <code>YYYY-MM-DD</code><ref>В данном случае используется функция <code>Sys.Date()</code>, которая выводит текущую дату.</ref>. Допускаются также значения "today", "yesterday", "ndaysAgo", где <code>n</code> - это количество дней;
* <code>date.format</code> - символьная строка, которая задаёт формат даты, который используется для преобразования дат, полученных в результате запроса (по умолчанию <code>%Y-%m-%d</code>);
* <code>metrics</code> - символьная строка, которая определяет показатели (столбцы), которые будут входить в таблицу с данными (по умолчанию <code>"ga:visits"</code>)<ref>Можно использовать не больше 10 метрик одновременно.</ref>;
* <code>dimensions</code> - символьная строка, которая определяет параметры (строки) таблицы, которые будут входить в таблицу с данными (по умолчанию <code>"ga:date"</code>)<ref>Можно использовать не больше 7 измерений одновременно.</ref>;
* <code>segment</code> - символьная строка, которая определяет сегмент данных (как правило, страницы/разделы сайта);
* <code>sort</code> - символьная строка, которая определяет, по какому из столбцов будет производиться сортировка данных в таблице<ref>Поддерживается как прямая, так и обратная сортировка</ref>;
* <code>filters</code> - символьная строка, которая определяет фильтры, применяемые при отборе данных на стороне сервера (в определенной мере аналог сегментов);
* <code>batch = TRUE</code> - позволяет преодолеть ограничение на количество возвращаемых строк при ответе сервера (необходимо, если предполагается, что строк может быть больше, чем 10000).
* <code>walk = TRUE</code> - позволяет получить исходные, а не агрегированные данные.

Аргументы <code>ids</code>, <code>start.date</code>, <code>end.date</code> и <code>metrics</code> являются обязательными для запроса к Google Analytics API. Все аргументы метода <code>getData</code>, а также значения по умолчанию, можно посмотреть с помощью команды <code>args(ga$getData)</code>.

Детальную информацию  можно найти на соответствующих страницах справочного руководства по GA API:

* по параметрам запроса к API отчётов: https://developers.google.com/analytics/devguides/reporting/core/v3/reference
* по параметрам запроса к API многоканальных последовательностей: https://developers.google.com/analytics/devguides/reporting/mcf/v3/reference
* по метрикам и измерениям базовых отчётов: https://developers.google.com/analytics/devguides/reporting/core/dimsmets
* по метрикам и измерениям многоканальных последовательностей: https://developers.google.com/analytics/devguides/reporting/mcf/dimsmets/
* по сегментам: https://developers.google.com/analytics/devguides/reporting/core/v3/segments

Получить доступ к API Google Analytics можно также с помощью веб-сервисов Google по следующей ссылке: https://developers.google.com/apis-explorer/?hl=ru#p/analytics/v3/. Для получения данных необходимо авторизоваться и задать требуемые параметры для запроса к API.

Пример сбора данных по выбранным метрикам и измерениям приведён ниже.

{{r-code|code=<nowiki>> ga.data <- ga$getData(ids = id,
+                       start.date = ga$getFirstDate(id), end.date = Sys.Date(),
+                       metrics = "ga:users,ga:sessions,ga:pageviews",
+                       dimensions = "ga:date", batch = TRUE)</nowiki>}}

После получения данных мы можем работать с переменной <code>ga.data</code> как с обычной таблицей данных (<code>data.frame</code>). Таблица данных, полученныя на предыдущем этапе, выглядит следующим образом (значения для psylab.info):

{{r-code|code=<nowiki>> head(ga.data)
        date pageviews sessions users
1 2014-03-19      9032     3651  3038
2 2014-03-20     11914     5028  4037
3 2014-03-21     10494     4388  3505
4 2014-03-22      7173     3133  2445
5 2014-03-23      8561     3676  2853
6 2014-03-24     11919     5043  3989</nowiki>}}

Структура таблицы имеют следующий вид:

{{r-code|code=<nowiki>> str(ga.data)
'data.frame':   34 obs. of  4 variables:
 $ date     : Date, format: "2014-03-19" "2014-03-20" "2014-03-21" "2014-03-22" ...
 $ pageviews: num  9032 11914 10494 7173 8561 ...
 $ sessions : num  3651 5028 4388 3133 3676 ...
 $ users    : num  3038 4037 3505 2445 2853 ...</nowiki>}}

== Примечания ==

<references />

== Ссылки ==

* R Google Analytics: An easy API connector to Google Analytics in R - http://skardhamar.github.io/rga/
* r-google-analytics: Google Analytics For The R Statistical Programming Language - https://code.google.com/p/r-google-analytics/
* Google Analytics: Dimensions & Metrics Reference - https://developers.google.com/analytics/devguides/reporting/core/dimsmets
* Google Analytics Query Explorer 2 - https://ga-dev-tools.appspot.com/explorer/?csw=1
* Google Analytics: Core Reporting API - Segments - https://developers.google.com/analytics/devguides/reporting/core/v3/segments
* Google Analytics Core Reporting API Changelog: https://developers.google.com/analytics/devguides/reporting/core/v3/changelog

== См. также ==

* [[R:Google Analytics/Параметры и измерения|Google Analytics - Параметры и измерения]]
* [[R:Google Analytics/Примеры|Примеры анализа данных Google Analytics в R]]

[[Категория:R]]
[[Категория:Веб-аналитика]]