Расширенная настройка – Веб-отслеживание (analytics.js)

Этот документ содержит общую информацию о библиотеке analytics.js.

Фрагмент кода analytics.js является частью сервиса Universal Analytics. Если вы используете классическую версию Google Analytics (ga.js), узнайте, как перевести свой ресурс на analytics.js, в Центре обновления.

Фрагмент кода JavaScript

Чтобы включить отслеживание с помощью Google Analytics на сайте, необходимо добавить фрагмент кода JavaScript перед закрывающим тегом </head>. Вот часть такого фрагмента:

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

При запуске этот код сначала создает глобальную функцию ga, а затем асинхронно загружает на страницу библиотеку analytics.js.

Глобальная функция ga – это основной способ взаимодействия с библиотекой analytics.js. Эта функция принимает ряд параметров, первый из которых представляет команду Google Analytics. Например, в стандартном фрагменте кода

ga('create', 'UA-XXXX-Y', 'auto');  // Creates a tracker.
ga('send', 'pageview');             // Sends a pageview.

первая строка вызывает команду create, а вторая – команду send.

Хотя код JavaScript загружает библиотеку analytics.js асинхронно, функция ga используется до того, как загрузится библиотека. Каждая команда, которую вы выполняете, ставится в очередь. Когда библиотека закончит загружаться, будут выполнены все команды из очереди. Новые команды выполняются сразу же. Это позволяет разработчикам использовать функцию ga, не обращая внимание на асинхронный характер Google Analytics.

Переименование глобального объекта

Иногда имя переменной ga может уже использоваться другим объектом на странице. Чтобы не переопределять его, можно переименовать функцию ga, например в __gaTracker. Для этого просто замените параметр ga в следующем фрагменте кода:

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','__gaTracker');

Теперь для вызова команд вы сможете использовать имя __gaTracker вместо ga:

__gaTracker('create', 'UA-XXXX-Y', 'auto');
__gaTracker('send', 'pageview');

Справка по фрагменту кода JavaScript

Далее показан основной фрагмент кода JavaScript с пояснительными комментариями.

<!-- Google Analytics -->
<script>
/**
 * Creates a temporary global ga object and loads analy  tics.js.
 * Paramenters o, a, and m are all used internally.  They could have been declared using 'var',
 * instead they are declared as parameters to save 4 bytes ('var ').
 *
 * @param {Window}      i The global context object.
 * @param {Document}    s The DOM document object.
 * @param {string}      o Must be 'script'.
 * @param {string}      g URL of the analytics.js script. Inherits protocol from page.
 * @param {string}      r Global name of analytics object.  Defaults to 'ga'.
 * @param {DOMElement?} a Async script tag.
 * @param {DOMElement?} m First script tag in document.
 */
(function(i, s, o, g, r, a, m){
  i['GoogleAnalyticsObject'] = r; // Acts as a pointer to support renaming.

  // Creates an initial ga() function.  The queued commands will be executed once analytics.js loads.
  i[r] = i[r] || function() {
    (i[r].q = i[r].q || []).push(arguments)
  },

  // Sets the time (as an integer) this tag was executed.  Used for timing hits.
  i[r].l = 1 * new Date();

  // Insert the script tag asynchronously.  Inserts above current tag to prevent blocking in
  // addition to using the async attribute.
  a = s.createElement(o),
  m = s.getElementsByTagName(o)[0];
  a.async = 1;
  a.src = g;
  m.parentNode.insertBefore(a, m)
})(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');

ga('create', 'UA-XXXX-Y', 'auto'); // Creates the tracker with default parameters.
ga('send', 'pageview');            // Sends a pageview hit.
</script>
<!-- End Google Analytics -->

Альтернативный вариант асинхронного фрагмента кода

Выше показан стандартный фрагмент кода analytics.js, который загружается и выполняется асинхронно на всех браузерах. Тем не менее, современные браузеры не поддерживают предварительную загрузку такого скрипта.

Показанный ниже фрагмент избавлен от этого недостатка и позволяет немного повысить производительность в современных браузерах. Обратите внимание, что в Internet Explorer 9 и старых мобильных браузерах, которые не распознают атрибут async, этот скрипт может загружаться синхронно. Таким образом, этот вариант кода рекомендуется для сайтов, большинство посетителей которых используют современные браузеры.

<!-- Google Analytics -->
<script async src='//www.google-analytics.com/analytics.js'></script>
<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->

Создание объектов трекера

Для отправки данных в Google Analytics вам необходимо создать объект трекера. Каждый такой объект может передавать данные только в один веб-ресурс Google Analytics. Для создания объекта трекера используется следующий код:

ga('create', 'UA-XXXX-Y', 'auto');

Здесь первый параметр функции ga – команда create, а второй – идентификатор веб-ресурса, куда следует отправлять данные.

Примечание. Замените значение UA-XXXX-Y на идентификатор веб-ресурса, представленный в веб-интерфейсе Google Analytics.

Настройка объектов трекера

Вся настройка трекера должна выполняться при его первоначальном создании. Для этого функции ga в качестве последнего параметра передается объект конфигурации. Например, вот так можно переопределить некоторые стандартные настройки cookie:

ga('create', 'UA-12345-6', {
   'cookieDomain': 'foo.example.com',
   'cookieName': 'myNewName',
   'cookieExpires': 20000
});

В показанном выше примере с помощью объекта конфигурации были переопределены домен, имя и срок действия файла cookie.

В этом разделе Справки по полям вы найдете подробную информацию обо всех полях, которые могут настраиваться в методе create.

Тестирование на локальном хосте

Если вы хотите протестировать analytics.js с веб-сервера, который работает на локальном хосте, то для установки файлов cookie analytics.js вам нужно будет отключить домен cookie по умолчанию:

ga('create', 'UA-XXXX-Y', {
  'cookieDomain': 'none'
});

Отправка данных

Когда трекер будет создан и связан с веб-ресурсом, вы сможете использовать команду send для отправки данных на веб-ресурс. Информация, которую вы пересылаете в Google Analytics, называется обращением. Библиотека analytics.js позволяет отправлять разные типы данных. Для этого вам нужно задать тип обращения – hitType. При использовании команды send вы также должны указать hitType передаваемых данных.

Например, для просмотров страницы укажите тип обращения pageview:

ga('send', 'pageview');

В результате в Google Analytics будут переданы данные об URL просмотренной страницы.

Объект имени поля

Иногда может потребоваться переопределить несколько значений, отправляемых как просмотр страницы (pageview). Библиотека analytics.js позволяет передать объект имени поля в качестве последнего параметра в команде send. Это позволяет задать многие дополнительные свойства просмотра страницы, например ее заголовок:

ga('send', 'pageview', {
  'page': '/my-new-page',
  'title': 'My New Page Title'
});

Подробнее о настройке объекта трекера читайте в Справке по полям.

Настройка обратного вызова после обращения

Иногда (например, при отслеживании исходящих ссылок) необходимо знать, когда система отслеживания закончила отсылать данные, чтобы направить пользователя на целевую страницу только после того, как данные о клике были переданы в Google Analytics. Решить эту задачу позволяет команда send. С ее помощью можно задать в объекте имени поля функцию hitCallback, которая будет выполняться только после того, как библиотека analytics.js закончит отправлять данные. Задать функцию hitCallback можно следующим образом:

ga('send', 'pageview', {
  'page': '/my-new-page',
  'hitCallback': function() {
    alert('analytics.js done sending data');
  }
});

В приведенном примере объект имени поля задает как параметр page, так и функцию hitCallback. Как только закончится передача данных отслеживания, пользователю будет показано окно с предупреждением.

Настройка параметров для нескольких команд send

Могут возникнуть ситуации, когда вам потребуется задать параметр и назначить ему одно постоянное значение для нескольких команд send. Допустим, у вас есть веб-страница, на которой вы хотите отслеживать два типа обращений: один просмотр страницы и два события. Чтобы при каждом обращении использовался ваш собственный путь к странице, вы можете либо задавать новый путь при каждом выполнении команды send, либо использовать метод set:

ga('set', 'page', '/my-custom-page');

ga('send', 'pageview');
ga('send', 'event', 'image1', 'clicked');
ga('send', 'event', 'image2', 'clicked');

При выполнении этого кода для всех трех команд send будет отправлен ваш собственный путь к странице, /my-custom-page.

Отправка обращений с помощью метода useBeacon

Чтобы отправить обращение с помощью метода navigator.sendBeacon, присвойте параметру useBeacon значение true. Метод navigator.sendBeacon гарантирует передачу данных даже в том случае, если пользователь покидает страницу или закрывает браузер, не дождавшись завершения запроса. Как правило, с помощью этого метода отслеживают события непосредственно перед уходом пользователя с сайта, не мешая его действия.

Примечание. В браузерах, не поддерживающих метод sendBeacon, автоматически применяется стандартный механизм обработки обращений.

ga('send', 'event', 'click', 'download-me', {useBeacon: true});

Функции "проталкивания"

В некоторых случаях код требуется выполнять только после того, как завершится загрузка библиотеки analytics.js. Для этого функции ga в качестве параметра нужно передать функцию:

ga(function() {
  alert('library done loading');
});

Когда библиотека закончит загружаться, пользователь увидит окно, уведомляющее об этом.

Получение параметров

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

ga(function(tracker) {
  var defaultPage = tracker.get('page');
});

В приведенном выше примере функция использует параметр с именем tracker. По окончании загрузки библиотеки будет выполнена эта функция, и значением tracker будет трекер по умолчанию, созданный в результате выполнения первой команды create. Затем с помощью tracker будет получено значение страницы по умолчанию.

Принудительное использование SSL (HTTPS)

По умолчанию при отправке исходящих запросов Google Analytics будет использовать тот же протокол, что и у страницы. Чтобы данные отправлялись с использованием протокола SSL даже с незащищенных страниц (HTTP), задайте для поля forceSSL значение true:

ga('create', 'UA-XXXX-Y', 'auto');
ga('set', 'forceSSL', true);        // Send all data using SSL, even from insecure (HTTP) pages.
ga('send', 'pageview');

Работа с несколькими трекерами

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

Чтобы реализовать эту возможность, создайте трекер для каждого веб-ресурса, на который нужно отправлять данные:

ga('create', 'UA-XXXX-Y', 'auto');
ga('create', 'UA-12345-6', 'auto', {'name': 'newTracker'});  // New tracker.

Этот код создаст два трекера: один по умолчанию, без имени и второй – с именем newTracker.

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

ga('send', 'pageview');
ga('newTracker.send', 'pageview'); // Send page view for new tracker.

В результате просмотр страницы будет отправлен как в стандартный, так и в новый трекер.

Чтобы найти трекер по имени, используйте метод getByName:

ga(function() {
  var newTracker = ga.getByName('newTracker');
});

Получить массив со всеми настроенными трекерами можно с помощью метода getAll:

ga(function() {
  var allTrackers = ga.getAll();
});

Улучшенная атрибуция ссылок

Улучшенная атрибуция ссылок позволяет автоматически различать ссылки на один и тот же URL на странице с помощью идентификаторов элементов ссылок.

Чтобы использовать эту функцию:

1. Включите улучшенную атрибуцию ссылок в интерфейсе администратора в своем аккаунте Google Analytics.
2. Обновите код на каждой странице, добавив плагин улучшенной атрибуции ссылок, как показано в примере ниже.

ga('create', 'UA-XXXX-Y', 'auto');
ga('require', 'linkid');   // Load the plug-in. Note: this call will block until the plug-in is loaded.
ga('send', 'pageview');

Примечание. Чтобы функция давала наиболее точные результаты, у каждой ссылки на вашей странице должен быть уникальный идентификатор элемента.

Настройка улучшенной атрибуции ссылок

Плагин улучшенной атрибуции ссылок различает ссылки на один и тот же URL, используя идентификаторы элемента ссылки или родительского элемента, а также файл cookie. Вы можете указать, на каком уровне DOM следует искать идентификатор элемента и как устанавливать cookie, задав эти настройки при загрузке плагина:

ga('create', 'UA-XXXX-Y', 'auto');
ga('require', 'linkid', {
           'cookieName': '_ela',        // Cookie name. _gali by default.
           'duration': 45,              // Cookie duration. 30 seconds by default.
           'levels': 5});               // Max DOM levels from link to look for element ID. 3 by default.
ga('send', 'pageview');

Анонимизация IP

В некоторых случаях может потребоваться анонимизировать IP-адрес обращения (http-запрос), отправляемый в Google Analytics. Вы можете анонимизировать IP-адреса для всех обращений, отправляемых со страницы (на протяжении всего жизненного цикла трекера), используя команду set и задав для поля anonymizeIp значение true:

ga('set', 'anonymizeIp', true);

Чтобы анонимизировать IP-адрес для отдельного обращения, установите поле anonymizeIp в объекте конфигурации для данного обращения:

ga('send', 'pageview', {
  'anonymizeIp': true
});

Подробнее читайте в справочной статье Анонимизация IP в Google Analytics.

Отказ пользователя от отслеживания

Иногда возникает необходимость отключить код отслеживания Google Analytics на странице, не удаляя с нее фрагмент JavaScript (например, если ваша политика конфиденциальности дает пользователям возможность отказаться от отслеживания).

Теперь в библиотеку analytics.js входит специальное свойство window, которое при значении true блокирует отправку данных в Google Analytics. При попытке установить файл cookie или отправить данные на серверы Google Analytics проверяет, задано ли для этого свойства значение true. Если да, то эффект будет таким же, как если бы в браузере пользователя был установлен плагин Блокировщик Google Analytics.

Чтобы отключить отслеживание, задайте значение true для следующего свойства window:

window['ga-disable-UA-XXXX-Y'] = true;

UA-XXXX-Y – это идентификатор того веб-ресурса, на котором вы хотите отключить отслеживание.

Свойство window должно быть задано до вызова кода отслеживания, и его следует установить на каждой странице, где вы хотите отключить отслеживание Google Analytics. Если его значение на задано или равно false, отслеживание будет выполняться, как обычно.

Пример

Вот простой пример кода, позволяющего реализовать отказ от отслеживания.

Сначала добавьте на свой сайт HTML-ссылку для отказа от отслеживания:

<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>

Затем добавьте показанный ниже фрагмент кода перед фрагментом кода отслеживания analytics.js. Не забудьте заменить значение gaProperty с UA-XXXX-Y на идентификатор того ресурса, с помощью которого отслеживается ваш сайт. Это то же значение, которое вы передаете команде create.

<script>
// Set to the same value as the web property used on the site
var gaProperty = 'UA-XXXX-Y';

// Disable tracking if the opt-out cookie exists.
var disableStr = 'ga-disable-' + gaProperty;
if (document.cookie.indexOf(disableStr + '=true') > -1) {
  window[disableStr] = true;
}

// Opt-out function
function gaOptout() {
  document.cookie = disableStr + '=true; expires=Thu, 31 Dec 2099 23:59:59 UTC; path=/';
  window[disableStr] = true;
}
</script>

Когда пользователь нажмет на HTML-ссылку для отказа от отслеживания, будет выполнена функция gaOptout. Она установит файл cookie с длительным сроком действия и отключит сбор данных analytics.js. Когда пользователь вернется на этот сайт снова, показанный выше скрипт проверит, установлен ли файл cookie отказа от отслеживания. Если да, analytics.js не будет производить сбор данных.

Примечание. В примере выше предполагается, что у вас лишь один веб-ресурс для отслеживания сайта и один домен. Код реализует функцию отключения, используя cookie с длительным сроком действия. Если вам, наоборот, нужна функция включения, либо у вас несколько веб-ресурсов или доменов, то вам нужно будет внести изменения в этот код, написать свой собственный или использовать инструменты, специально предназначенные для этой цели.

Отладка

Для работы с отладочной версией analytics.js используйте библиотеку analytics_debug.js:

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics_debug.js','ga');
ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');

Библиотека analytics_debug.js имеет больший размер и обрабатывает обращения к сайту google-analytics.com с дополнительной задержкой. В связи с этим ее следует использовать только в качестве временного решения или на этапе разработки.

Трассировка отладки

Эта функция позволяет выводить на консоль более подробную информацию. Чтобы активировать ее, используйте библиотеку https://www.google-analytics.com/analytics_debug.js и добавьте следующую строку перед фрагментом кода.

window.ga_debug = {trace: true};