Введение в ga.js (устаревшая версия)

ga.js — это библиотека JavaScript для измерения того, как пользователи взаимодействуют с вашим сайтом. Это устаревшая библиотека. Если вы только начинаете работать с Google Analytics, вам следует использовать новейшую библиотеку отслеживания Analytics.js .

Краткое руководство по коду отслеживания

Фрагмент Analytics — это небольшой фрагмент кода JavaScript, который вы вставляете на свои страницы. Он активирует отслеживание Google Analytics, вставляя ga.js на страницу. Чтобы использовать это на своих страницах, скопируйте приведенный ниже фрагмент кода, заменив UA-XXXXX-X идентификатором вашего веб-ресурса. Вставьте этот фрагмент на страницу шаблона вашего веб-сайта, чтобы он отображался перед закрывающим тегом </head> .

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

<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

Приведенный выше фрагмент представляет минимальную конфигурацию, необходимую для асинхронного отслеживания страницы. Он использует _setAccount для установки идентификатора веб-ресурса страницы, а затем вызывает _trackPageview для отправки данных отслеживания обратно на серверы Google Analytics.

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

Как работает асинхронный синтаксис

Объект _gaq делает возможным асинхронный синтаксис. Он действует как очередь, представляющая собой структуру данных в порядке очереди , которая собирает вызовы API до тех пор, пока ga.js не будет готов их выполнить. Чтобы добавить что-то в очередь, используйте метод _gaq.push .

Чтобы поместить вызов API в очередь, необходимо преобразовать его из традиционного синтаксиса JavaScript в массив команд . Массивы команд — это просто массивы JavaScript, соответствующие определенному формату. Первый элемент массива команд — это имя метода объекта трекера, который вы хотите вызвать. Это должна быть строка. Остальные элементы — это аргументы, которые вы хотите передать методу объекта трекера. Это может быть любое значение JavaScript.

Следующий код вызывает _trackPageview() используя традиционный синтаксис:

var pageTracker = _gat._getTracker('UA-XXXXX-X');
pageTracker._trackPageview();

Эквивалентный код в асинхронном синтаксисе требует двух вызовов _gaq.push .

_gaq.push(['_setAccount', 'UA-XXXXX-X']);
_gaq.push(['_trackPageview']);

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

Дополнительную информацию об асинхронном синтаксисе см. в Справочнике по отслеживанию метода _gaq.push .

Вернуться к вершине

Отслеживание с помощью обработчиков событий HTML

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

<button onclick="_gaq.push(['_trackEvent', 'button3', 'clicked'])"></button>

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

Вернуться к вершине

Помещение функций в очередь

Помимо массивов команд, вы также можете помещать в очередь _gaq функциональные объекты. Функции могут содержать любой произвольный JavaScript и, как и массивы команд, они выполняются в том порядке, в котором они помещены в _gaq . Этот метод полезен для вызова API отслеживания, которые возвращают значения. Например, следующий код создает URL-адрес компоновщика и устанавливает свойство href для ссылки с результатом.

_gaq.push(function() {
  var pageTracker = _gat._getTracker('UA-XXXXX-X');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

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

_gaq.push(function() {
  var pageTracker = _gat._createTracker('UA-XXXXX-X', 'myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

_gaq.push(['myTracker._trackPageview']);

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

Возможен и противоположный вариант использования. Например, если вам нужно использовать асинхронный объект отслеживания, созданный с помощью ранее отправленного массива команд, используйте метод _gat._getTrackerByName . Следующий код демонстрирует, как это работает.

_gaq.push(['myTracker._setAccount', 'UA-XXXXX-X']);

_gaq.push(function() {
  var pageTracker = _gat._getTrackerByName('myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

Вернуться к вершине

Одно нажатие, несколько команд

Вместо того, чтобы вводить _gaq.push(...) для каждого вызова, вы можете отправить все свои команды одновременно. Следующий код демонстрирует этот метод.

_gaq.push(
  ['_setAccount', 'UA-XXXXX-X'],
  ['_setDomainName', 'example.com'],
  ['_setCustomVar', 1, 'Section', 'Life & Style', 3],
  ['_trackPageview']
);

Это работает, поскольку метод _gaq.push имитирует метод Array.push , который позволяет отправлять несколько элементов за один вызов.

Вернуться к вершине

Разделение фрагмента

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

Страница с разделенным пополам асинхронным фрагментом может выглядеть так:

<html>

<head>
  <script type="text/javascript">
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-XXXXX-X']);
    _gaq.push(['_trackPageview']);
  </script>
</head>

<body>
  <p>Page Content</p>

  <script src="some_random_script.js"></script>

  <p>Page Content</p>

  <script type="text/javascript">  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script> </body> </html>

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

Вернуться к вершине

Как избежать распространенных ошибок

При использовании асинхронного или традиционного синтаксиса имейте в виду следующее:

  • Имена методов чувствительны к регистру.
    Если вы используете имя метода без надлежащего регистра, вызовы метода не будут работать. Примеры:
    _gaq.push(['_trackpageview']);   // bad
    _gaq.push(['_trackPageview']);   // good
  • Используйте правильные имена методов.
    Если ваше отслеживание работает неправильно, убедитесь, что вы используете правильное имя для метода. Примеры:
    _gaq.push(['_setDomain', 'example.com']);       // bad
    _gaq.push(['_setDomainName', 'example.com']);   // good
    
  • С кавычками следует передавать только строки . Все остальные типы следует оставить без кавычек.
    Любое значение, не являющееся строкой, например логические значения, литералы объектов, функции или массивы, следует передавать без кавычек. Используйте только кавычки, когда передаете что-то, что должно интерпретироваться как строка. Если вы переходите от традиционного синтаксиса, любой параметр функции, переданный без кавычек, должен оставаться в асинхронном синтаксисе без кавычек. Примеры:
    _gaq.push(['_setAllowLinker', 'false']);    // bad
    _gaq.push(['_setAllowLinker', false]);      // good
    
  • Убедитесь, что строки не содержат пробелов в начале или в конце.
    Примеры:
    _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
    _gaq.push(['_setAccount', 'UA-65432-1']);     // good
    

Вернуться к вершине

Отключение отслеживания

В некоторых случаях может потребоваться отключить код отслеживания Google Analytics на странице без удаления фрагмента кода. Например, вы можете сделать это, если политика конфиденциальности вашего сайта предусматривает возможность посетителя отказаться от отслеживания Google Analytics.

Фрагмент отслеживания ga.js теперь включает свойство window, которое, если для него установлено значение true , отключает отправку данных в Google Analytics. Когда Google Analytics пытается установить файл cookie или отправить данные обратно на серверы Google Analytics, он проверяет, установлено ли для этого свойства значение true . Если это так, это будет иметь тот же эффект, как если бы у посетителя был установлен плагин браузера для отключения Google Analytics .

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

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

Где значение UA-XXXXXX-Y соответствует идентификатору веб-ресурса, для которого вы хотите отключить отслеживание.

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

Так, например, если ваш код отслеживания Google Analytics на странице включает:

_gaq.push['_setAccount', 'UA-123456-1']

И вы хотите запретить этому коду отслеживания устанавливать файлы cookie или отправлять данные обратно в Google Analytics, тогда вы используете следующий код перед вызовом кода отслеживания:

window['ga-disable-UA-123456-1'] = true;

Если вы используете несколько трекеров на странице с несколькими идентификаторами веб-ресурса, вы должны установить для эквивалентной переменной window['ga-disable-UA-XXXXXX-Y'] значение true для каждого веб-ресурса, чтобы полностью отключить отслеживание Google Analytics на этой странице.

Пример

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

Сначала добавьте на свой сайт новую HTML-ссылку, чтобы выполнить логику отказа:

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

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

<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 также будет отключен.

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

Чтобы заставить Google Analytics всегда отправлять данные с использованием SSL, даже с незащищенных страниц (HTTP), используйте метод _gat._forceSSL , как в этом примере:

_gaq.push(['_setAccount', 'UA-12345-1']);
_gaq.push(['_gat._forceSSL']);       // Send all hits using SSL, even from insecure (HTTP) pages.
_gaq.push(['_trackPageview']);

Вернуться к вершине