Введение в ga.js (предыдущая версия)

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

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

Фрагмент кода Google 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.

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

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

Объект _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 , который позволяет отправлять несколько элементов одним вызовом.

Наверх

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

Если вы предпочитаете размещать фрагмент Google 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>

Оба фрагмента кода должны быть заключены в собственные теги script, но только последние шесть строк исходного асинхронного фрагмента должны быть перемещены вниз. Все строки, которые помещают методы в _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 теперь включает свойство окна, которое, если задано значение true , отключает отправку данных фрагментом отслеживания в Google Analytics. Когда Google Analytics пытается установить файл cookie или отправить данные обратно на серверы Google Analytics, он проверяет, установлено ли для этого свойства значение true . Если это так, это будет иметь такой же эффект, как если бы у посетителя был установлен подключаемый модуль браузера Google Analytics Opt-out .

Чтобы отключить отслеживание, установите для следующего свойства окна значение 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 . Он установит куки на долгое время в будущем и отключит сбор данных 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']);

Наверх