Wprowadzenie do ga.js (starsza wersja)

ga.js to biblioteka JavaScript do pomiaru interakcji użytkowników z witryną. To jest starsza biblioteka. Jeśli dopiero zaczynasz korzystać z Google Analytics, zalecamy skorzystanie z najnowszej biblioteki śledzenia analytics.js.

Krótkie wprowadzenie do kodu śledzenia

Fragment kodu Analytics to krótki fragment kodu JavaScript, który należy wkleić na stronach. Wstawienie tagu ga.js na stronie aktywuje śledzenie Google Analytics. Aby użyć go na swoich stronach, skopiuj poniższy fragment kodu, zastępując UA-XXXXX-X identyfikatorem usługi internetowej. Wklej ten fragment kodu na stronie szablonu witryny, aby wyświetlał się przed zamykającym tagiem </head>.

Jeśli chcesz zrobić coś więcej niż tylko podstawowe śledzenie stron, zapoznaj się z dokumentacją śledzenia zawierającą listę metod dostępnych w interfejsie API, a szczegółowe informacje na temat korzystania ze składni asynchronicznej znajdziesz w przewodniku korzystania. Szczegółowe instrukcje konfigurowania śledzenia znajdziesz w artykule w Centrum pomocy dotyczącym konfigurowania śledzenia.

<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>

Powyższy fragment kodu przedstawia minimalną konfigurację potrzebną do asynchronicznego śledzenia strony. Wykorzystuje on właściwość _setAccount do ustawiania identyfikatora usługi internetowej strony, a następnie wywołuje metodę _trackPageview, by przesłać dane śledzenia z powrotem do serwerów Google Analytics.

Ważne: jeśli aktualizujesz strony z tradycyjnego fragmentu kodu do najnowszej wersji asynchronicznej, musisz najpierw usunąć istniejący fragment kodu śledzenia. Nie zalecamy używania obu fragmentów jednocześnie na tej samej stronie. Instrukcje migracji znajdziesz w artykule Migracja do wersji asynchronicznej.

Jak działa składnia asynchroniczna

Umożliwia on składnię asynchroniczną dzięki obiektowi _gaq. Działa ona jak kolejka, która jest strukturą danych typu pierwsze wejście, pierwsze wyjście, która zbiera wywołania interfejsu API, dopóki interfejs ga.js nie będzie gotowy do ich wykonania. Aby dodać coś do kolejki, użyj metody _gaq.push.

Aby przekazać wywołanie interfejsu API do kolejki, musisz przekonwertować je z tradycyjnej składni JavaScript na tablicę poleceń. Tablice poleceń to po prostu tablice JavaScript, które dostosowują się do określonego formatu. Pierwszy element w tablicy poleceń to nazwa metody obiektu skryptu śledzenia, którą chcesz wywołać. Musi to być ciąg znaków. Pozostałe elementy to argumenty, które chcesz przekazać do metody obiektów skryptu śledzenia. Może to być dowolna wartość JavaScript.

Ten kod wywołuje funkcję _trackPageview() przy użyciu tradycyjnej składni:

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

Odpowiadający mu kod w składni asynchronicznej wymaga 2 wywołań funkcji _gaq.push.

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

W składni asynchronicznej utworzenie obiektu skryptu śledzenia jest domniemane, ale i tak potrzebujemy sposobu na ustawienie identyfikatora usługi internetowej na potrzeby modułu śledzenia. Aby to umożliwić, dodaliśmy metodę _setAccount. Wszystkie pozostałe metody obiektów skryptu śledzenia są takie same zarówno przy śledzeniu asynchronicznym, jak i tradycyjnym. Różni się tylko składnia.

Więcej informacji o składni asynchronicznej znajdziesz w dokumentacji śledzenia metody _gaq.push.

Powrót do góry

Śledzenie za pomocą modułów obsługi zdarzeń HTML

Składni śledzenia asynchronicznego należy też używać z modułów obsługi zdarzeń DOM. Na przykład poniższy przycisk generuje zdarzenie po kliknięciu.

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

Nawet jeśli ten przycisk zostanie kliknięty przed zakończeniem wczytywania funkcji ga.js przez przeglądarkę, zdarzenie zostanie przechwycone i wykonane. W takiej sytuacji przeglądarka może zgłosić wyjątek, korzystając z tradycyjnego śledzenia.

Powrót do góry

Przekazywanie funkcji do kolejki

Oprócz tablic poleceń możesz też przenosić obiekty funkcji do kolejki _gaq. Funkcje mogą zawierać dowolny kod JavaScript, podobnie jak tablice poleceń, są wykonywane w kolejności, w jakiej zostały przekazane na argument _gaq. Ta metoda jest przydatna do wywoływania interfejsów API śledzenia, które zwracają wartości. Na przykład ten kod tworzy adres URL łączący i ustawia właściwość href dla linku z wynikiem.

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

W przykładzie powyżej użyto elementu _gat do utworzenia obiektu śledzenia, ale ponieważ jest on przypisany do zmiennej lokalnej, kod spoza funkcji nie może go użyć. Mimo że jest to dozwolone, możesz użyć metody _gat._createTracker, aby utworzyć trwały, dostępny globalnie obiekt. Poniższy kod pokazuje, jak to działa.

_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']);

Powyższy przykład tworzy w funkcji funkcji asynchroniczny kod śledzenia, a następnie odwołuje się do niego później za pomocą nazwy w tablicy poleceń.

Możliwy jest również odwrotny przypadek użycia. Jeśli na przykład musisz użyć obiektu asynchronicznego śledzenia utworzonego za pomocą wcześniej przekazanej tablicy poleceń, użyj metody _gat._getTrackerByName. Poniższy kod pokazuje, jak to działa.

_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/');
});

Powrót do góry

1 pchnięcie, wiele poleceń

Zamiast wpisywać _gaq.push(...) przy każdym wywołaniu, możesz przekazać wszystkie polecenia naraz. Poniższy kod pokazuje tę metodę.

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

Działa to, ponieważ metoda _gaq.push imituje metodę Array.push, która umożliwia przekazywanie wielu elementów za pomocą jednego wywołania.

Powrót do góry

Podział fragmentu kodu

Jeśli wolisz umieścić fragment kodu Analytics u dołu strony, pamiętaj, że nie musisz umieszczać całego kodu u dołu strony. Aby zachować większość korzyści płynących z wczytywania asynchronicznego, podziel fragment na pół – pierwszą połowę umieść u góry strony, a resztę na dole. Pierwsza część fragmentu kodu śledzenia ma niewielki wpływ lub nie ma żadnego wpływu na renderowanie strony, więc możesz zostawić tę część u góry, a część, która wstawia ga.js na dole.

Strona z asynchronicznym fragmentem kodu podzielonym na pół może wyglądać tak:

<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>

Oba fragmenty kodu muszą być umieszczone w osobnym tagu skryptu, ale tylko 6 ostatnich wierszy oryginalnego asynchronicznego fragmentu kodu należy przenieść na dół. Wszystkie wiersze, które przekazują metody do obiektu _gaq, mogą pozostać na górze.

Powrót do góry

Unikanie najczęstszych błędów

Korzystając ze składni asynchronicznej lub tradycyjnej, pamiętaj o tych kwestiach:

  • W nazwach metod rozróżniana jest wielkość liter.
    Jeśli używasz nazwy metody bez odpowiedniej wielkości liter, wywołania metody nie będą działać. Przykłady:
    _gaq.push(['_trackpageview']);   // bad
    _gaq.push(['_trackPageview']);   // good
  • Używaj prawidłowych nazw metod.
    Jeśli śledzenie nie działa prawidłowo, sprawdź, czy używasz prawidłowej nazwy metody. Przykłady:
    _gaq.push(['_setDomain', 'example.com']);       // bad
    _gaq.push(['_setDomainName', 'example.com']);   // good
    
  • Podawaj tylko ciągi tekstowe w cudzysłowach. Pozostałe typy nie należy umieszczać w cudzysłowie.
    Każda wartość, która nie jest ciągiem znaków, taka jak wartości logiczne, literały obiektów, funkcje czy tablice, powinna zostać przekazana bez cudzysłowu. Jeśli przekazujesz coś, co ma być interpretowane jako ciąg, używaj tylko cudzysłowów. Jeśli przeprowadzasz migrację ze składni tradycyjnej, każdy parametr funkcji przekazany bez cudzysłowu powinien pozostać w składni asynchronicznej nieuwzględniony w cudzysłowie. Przykłady:
    _gaq.push(['_setAllowLinker', 'false']);    // bad
    _gaq.push(['_setAllowLinker', false]);      // good
    
  • Upewnij się, że na początku ani na końcu ciągu znaków nie ma spacji.
    Przykłady:
    _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
    _gaq.push(['_setAccount', 'UA-65432-1']);     // good
    

Powrót do góry

Wyłączanie śledzenia

W niektórych przypadkach może być konieczne wyłączenie kodu śledzenia Google Analytics na stronie bez konieczności usuwania fragmentu kodu. np. jeśli polityka prywatności witryny umożliwia użytkownikom zrezygnowanie ze śledzenia Google Analytics.

Fragment kodu śledzenia ga.js zawiera teraz usługę window, która po ustawieniu wartości true wyłącza wysyłanie danych do Google Analytics przez fragment kodu śledzenia. Gdy Google Analytics spróbuje umieścić plik cookie lub wysłać dane z powrotem do serwerów Google Analytics, sprawdzi, czy ta usługa ma wartość true. Jeśli tak, będzie to miało taki sam skutek jak w przypadku, gdy użytkownik zainstalował wtyczkę do przeglądarki blokującą Google Analytics.

Aby wyłączyć śledzenie, ustaw dla tej właściwości window wartość „true” (prawda):

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

Gdzie wartość UA-XXXXXX-Y odpowiada identyfikatorowi usługi internetowej, w której chcesz wyłączyć śledzenie.

Tę właściwość okna należy ustawić przed wywołaniem kodu śledzenia. Musisz ją skonfigurować na każdej stronie, na której chcesz wyłączyć śledzenie Google Analytics. Jeśli właściwość nie jest ustawiona lub ma wartość Fałsz, śledzenie będzie działać w zwykły sposób.

Jeśli więc na przykład Twój kod śledzenia Google Analytics na stronie zawiera:

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

Aby wyłączyć tworzenie przez kod śledzenia plików cookie lub wysyłanie danych z powrotem do Google Analytics, użyj następującego kodu przed wywołaniem kodu śledzenia:

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

Jeśli na stronie z kilkoma identyfikatorami usług internetowych używasz wielu skryptów śledzenia, musisz dla każdej usługi internetowej ustawić równoważną zmienną window['ga-disable-UA-XXXXXX-Y'] na true, aby całkowicie wyłączyć śledzenie Google Analytics na tej stronie.

Przykład

Oto prosty przykład kodu, za pomocą którego możesz udostępnić użytkownikom funkcję rezygnacji.

Najpierw dodaj do witryny nowy link HTML, aby wykonać logikę rezygnacji:

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

Następnie dodaj poniższy fragment kodu przed fragmentem kodu ga.js. Pamiętaj, aby zastąpić wartość gaProperty z UA-XXXX-Y właściwością używaną w Twojej witrynie. To ta sama wartość, którą przekazujesz do polecenia _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>

Gdy użytkownik kliknie link HTML rezygnacji, zostanie uruchomiona niestandardowa funkcja gaOptout. Utworzy on plik cookie na dłuższy czas i wyłączy zbieranie danych za pomocą tagu analytics.js. Gdy użytkownik wróci do tej witryny, powyższy skrypt sprawdzi, czy został ustawiony plik cookie rezygnacji. Jeśli tak, zbieranie danych za pomocą tagu analytics.js również zostanie wyłączone.

Wymuszanie protokołu SSL (HTTPS)

Aby wymusić na Google Analytics wysyłanie danych zawsze przez SSL, nawet z niezabezpieczonych stron (HTTP), użyj metody _gat._forceSSL jak w tym przykładzie:

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

Powrót do góry