Spis treści¶

Kod śledzący¶

Podstawowy kod śledzący¶

Kod śledzący należy wstawić w kodzie źródłowym strony internetowej (pamiętając o podmianie identyfikatora wewnątrz kodu):

<script src="//cdn.sarehub.com/clients/<twój-identyfikator>.js" async></script>

_images/basic-code.png

Śledzenie użytkowników¶

Podstawowy kod śledzący SAREweb, który należy wstawić w kodzie źródłowym strony internetowej (pamiętając o podmianie identyfikatora wewnątrz kodu):

<script>
   (function (p){window['sareX_params']=p;var s=document.createElement('script');
   s.src='//x.sare25.com/libs/sarex4.min.js';
   s.async=true;var t=document.getElementsByTagName('script')[0];
   t.parentNode.insertBefore(s,t);
   })({
      domain : 'brak.pl',
      doNotTrack : true / false
   });
</script>

W przypadku stron SPA jest możliwość dynamicznej zmiany opcji śledzenia poprzez wykorzystanie pomocniczych funkcji.

Wywołanie poniższej funkcji zablokuje wszystkie działania związane ze śledzeniem użytkownika.

sareX_core.doNotTrackEnable();

Wywołanie poniższej funkcji odblokuje wszystkie działania związane ze śledzeniem użytkownika.

sareX_core.doNotTrackDisable();

Tagowanie użytkowników¶

W przypadku gdy tagowanie użytkowników jest wywołane podczas przeładowania strony należy dodać poniższy kod. Kod powinien znajdować się poniżej podstawowego kodu śledzącego.

sareX_params.addUserTags = ['buty', 'ubrania'];

W przypadku gdy tagowanie użytkowników wywoływane jest dynamicznie, bez ponownego wejścia na stronę należy wywołać metodę:

sareX_core.addUserTags(['buty', 'ubrania']);

Powiadomienia WebPush¶

Dla stron z protokołem HTTPS¶

Domena musi posiadać ważny certyfikat SSL oraz wymaga umieszczenia dwóch plików na serwerze.

Podstawowy kod śledzący SAREweb musi być umieszczony na stronie.

<script src="//cdn.sarehub.com/clients/<twój-identyfikator>.js" async></script>

Pobierz paczkę ze skryptami. Pobrany pakiet będzie zawierał dwa skrypty: manifest.json i sw.js.

Link do paczki: https://x.sare25.com/libs/sareweb_webpush.zip

Na koniec rozpakuj paczkę i dodaj pliki minifest.json i sw.js je do głównego folderu (root) strony.

Zdarzenia koszykowe¶

W celu identyfikacji zalogowanego użytkownika należy przekazać jego unikalny identyfikator w parametrze «_userId» oraz adres e-mail w parametrze «_email».

Parametry «_userId» i «_email» powinny być wysyłane wraz z każdym zdarzeniem zalogowanego użytkownika.

Jeśli adres e-mail _email lub _userId nie jest znany w momencie wykonania któregoś z poniższych zdarzeń to wartość powinna być pusta (lub null).

Jeśli identyfikatorem użytkownika jest adres e-mail to wartość «_userId» i «_email» powinna być taka sama.

Jeśli adres e-mail nie jest znany po zalogowaniu użytkownika, wartość parametru «_email» będzie pusta (lub null).

Przejście w kategorię produktu¶

sareX_params.tag = {'_userId': '123', '_email': 'abc@def', '_category': {'country' : 'PL', 'language': 'pl', 'id': 'nazwa kategorii'}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email': 'abc@def', '_category': {'country' : 'PL', 'language': 'pl', 'id': 'nazwa kategorii'}};
sareX_core.execute(10, execute_params);

Parametr «country» i «language» jest wymagany. Wartość parametru «country» przyjmuje wartość kraju docelowego product feeda w formacie ISO 3166-1 alfa-2. Wartość parametru «language» przyjmuje wartość języka w jakim przygotowanych jest product feed w formacie ISO 639-1.

Przejście na stronę produktu¶

sareX_params.tag = {'_userId': '123', '_email': 'abc@def', '_product': {'country' : 'PL', 'language': 'pl', 'id': '1', 'url' : 'URL produktu' }};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email': 'abc@def', '_product': {'country' : 'PL', 'language': 'pl', 'id': '1', 'url' : 'URL produktu'}};
sareX_core.execute(10, execute_params);

Parametr «country», «language» i «id» jest wymagany. Wartość parametru «country» przyjmuje wartość kraju docelowego product feeda w formacie ISO 3166-1 alfa-2. Wartość parametru «language» przyjmuje wartość języka w jakim przygotowanych jest product feed w formacie ISO 639-1. Parametr «id» to identyfikator produktu.

Dodania produktu do koszyka¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : false, '_cartadd' : {'country' : 'PL', 'language': 'pl', 'cart_id' : '', 'product_id' : '1', 'quantity' : 1, 'url' : 'URL produktu'}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : false, '_cartadd' : {'country' : 'PL', 'language': 'pl', 'cart_id' : '', 'product_id' : '1', 'quantity' : 1, 'url' : 'URL produktu'}};
sareX_core.execute(10, execute_params);

Parametr «country» i «language» jest wymagany. Wartość parametru «country» przyjmuje wartość kraju docelowego product feeda w formacie ISO 3166-1 alfa-2. Wartość parametru «language» przyjmuje wartość języka w jakim przygotowanych jest product feed w formacie ISO 639-1.

Usunięcia produktu z koszyka¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartdel' : {'country' : 'PL', 'language': 'pl', 'cart_id' : '', 'product_id' : '1'}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartdel' : {'country' : 'PL', 'language': 'pl', 'cart_id' : '', 'product_id' : '1'}};
sareX_core.execute(10, execute_params);

Parametr «country» i «language» jest wymagany. Wartość parametru «country» przyjmuje wartość kraju docelowego product feeda w formacie ISO 3166-1 alfa-2. Wartość parametru «language» przyjmuje wartość języka w jakim przygotowanych jest product feed w formacie ISO 639-1.

Zmiana liczby produktów w koszyku¶

Parametr «quantity» przyjmuje wartość na jaką ustawiana jest liczba danego produktu podczas jej edycji:

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartquantity' : {'country' : 'PL', 'language': 'pl', 'cart_id' : '', 'product_id' : '1', 'quantity' : 1}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartquantity' : {'country' : 'PL', 'language': 'pl', 'cart_id' : '', 'product_id' : '1', 'quantity' : 1}};
sareX_core.execute(10, execute_params);

Parametr «country» i «language» jest wymagany. Wartość parametru «country» przyjmuje wartość kraju docelowego product feeda w formacie ISO 3166-1 alfa-2. Wartość parametru «language» przyjmuje wartość języka w jakim przygotowanych jest product feed w formacie ISO 639-1.

Parametr «quantity» powinien przyjmować wartość aktualnego stanu ilości produktu w koszyku, przykładowo jeśli w koszyku były 3 jednostki danego produktu i zwiększamy ilość o 2j. (czyli w sumie na 5j.) wartość parametru «quantity» będzie wynosić 5.

Rozpoczęcie procesu zamówienia¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartinitialized' : {'cart_id' : ''}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartinitialized' : {'cart_id' : ''}}};
sareX_core.execute(10, execute_params);

Podanie danych osobowych¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartregistration' : {'cart_id' : ''}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartregistration' : {'cart_id' : ''}}};
sareX_core.execute(10, execute_params);

Wybór formy dostarczenia¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartdelivery' : {'cart_id' : ''}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartdelivery' : {'cart_id' : ''}}};
sareX_core.execute(10, execute_params);

Wybór sposobu płatności¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartpayment' : {'cart_id' : ''}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartpayment' : {'cart_id' : ''}};
sareX_core.execute(10, execute_params);

Podsumowanie koszyka¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartsummary' : {'cart_id' : ''}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartsummary' : {'cart_id' : ''}};
sareX_core.execute(10, execute_params);

Potwierdzenie zakupu¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartconfirm' : {'cart_id' : ''}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartconfirm' : {'cart_id' : ''}};
sareX_core.execute(10, execute_params);

Finalizacja zakupu¶

sareX_params.event = {'id': '10', 'params' : {'_userId': '123', '_email' : 'abc@def', '_cartpurchased' : {'cart_id' : ''}}};

W przypadku gdy zdarzenie powinno zostać wywołane dynamicznie czyli bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartpurchased' : {'cart_id' : ''}};
sareX_core.execute(10, execute_params);

Problem asynchroniczności¶

Częsty problem developerów objawia się tym, że próbują oni wykorzystać bibliotekę, kiedy nie jest ona jeszcze załadowana.

Pierwszy sposób, poprzez wykorzystanie window.onload:

window.onload = function() {
   var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartpurchased' : {'cart_id' : ''}};
   sareX_core.execute(10, execute_params);
}

Drugi sposób, z wykorzystaniem window.addEventListener(«DOMContentLoaded», …):

window.addEventListener('DOMContentLoaded', function(event){
   var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartpurchased' : {'cart_id' : ''}};
   sareX_core.execute(10, execute_params);
});

Trzeci sposób, dla stron gdzie jest wykorzystana biblioteka jQuery:

$(document).ready(function() {
   var execute_params = {'_userId': '123', '_email' : 'abc@def', '_cartpurchased' : {'cart_id' : ''}};
   sareX_core.execute(10, execute_params);
});

Wysyłanie zdarzeń¶

sareX_params.tag - służy do tagowania danej strony np. oznaczeniem jej daną kategorią oraz przesyłania dodatkowych informacji w momencie wejścia na daną stronę. Przykład:

sareX_params.tag = {'_userId': '123', '_email': 'abc@def', '_category':{'id':'nazwa kategorii'}};

sareX_core.execute – służy do wysyłania informacji na temat danego zdarzenia w przypadku gdy zdarzenie wywoływane jest bez ponownego wejścia na stronę (odświeżenia). Przykład:

var event = 10;
var execute_params = {'_userId': '123', '_email': 'abc@def', '_category':{'id':'nazwa kategorii'}};
sareX_core.execute(event, execute_params);

event - gdzie
- 1 oznacza wejście na stronę,
- 5 to zdarzenie wysłania formularza (szczegółowe informacje http://sareweb.readthedocs.io/pl/latest/form_events.html )
- 10 to zdarzenie koszykowe (szczegółowe informacje http://sareweb.readthedocs.io/pl/latest/carts.html )
execute_params – dodatkowe parametry wysyłane wraz z danym eventem. Wartość tego parametru musi być obiektem.

Przechwytywanie informacji z formularzy¶

Aby zbierać informacje przekazane w formularzu należ wpiąć kody śledzące (główne) na daną stronę oraz wywołać odpowiednią metodę po zdarzeniu kliknięcia w przycisk zapisu formularza: w przypadku gdy formularz przeładowuje stronę należy wykonać metodę sareX_params.event podając interesujące nas parametry przekazane w formularzu. Przykład:

sareX_params.event = {'id': '5', 'params' : {'_email' : 'abc@def', '_extra' : {'imie': 'imie', 'nazwisko' : 'nazwisko'}}};

gdzie wartość parametru id = 5 oznacza wywołanie zdarzenia submit. W parametrze «_email» należy podać adres email osoby wypełniającej formularz (lub zostawić to pole puste), natomiast w parametrze «_extra» można umieścić wszystkie interesujące nas dane.

W przypadku gdy zdarzenie wywoływane jest bez ponownego wejścia na stronę (odświeżenia) należy wywołać metodę:

var execute_params = {'_email': 'abc@def', '_extra' : {'imie': 'imie', 'nazwisko' : 'nazwisko'}};
sareX_core.execute(5, execute_params);

Personalizacja na stronie¶

Podstawowy kod śledzący SAREweb, który należy wstawić stronie internetowej należy wzbogacić o dwa dodatkowe parametry personalization_subject oraz personalization_callback.

Przykład:

(function (p){window['sareX_params']=p;var s=document.createElement('script');
s.src='//x.sare25.com/libs/sarex4.min.js';s.async=true;var t=document.getElementsByTagName('script')[0];
t.parentNode.insertBefore(s,t);
})({
  domain : 'brak.pl',
  personalization_callback: personalization_handler,
  personalization_subject: ["test"]
});

function personalization_handler(msg){
    if (msg.params.body.SAREhub_1_100_1_id) {
        var img = document.createElement("img");
        img.setAttribute("src", msg.params.body.SAREhub_1_100_1_image);
        img.setAttribute("height", "200");
        img.setAttribute("width", "200");

        var text = document.createTextNode(msg.params.body.SAREhub_1_100_1_name);

        document.getElementById("product1").appendChild(text);
        document.getElementById("product1").appendChild(img);
    }
}

personalization_callback - funkcja callback przygotowana w Javascript, która wyzwoli personalizację. Do funkcji zostanie przekazana wiadomość z personalizacją np. rekomendowane produkty. Przykład wiadomości personalizacyjnej:

{
  "type": "message",
  "time": 1558961608,
  "user": {
    "cookie": "123xxxxxxxx"
  },
  "params": {
    "domain": "brak.pl",
    "expire": "600",
    "type": "once",
    "subject": "shoper",
    "body": {
      "SAREhub_1_100_1_id": "3",
      "SAREhub_1_100_1_name": "Półbuty Nikipol, skórzane",
      "SAREhub_1_100_1_image": "https://via.placeholder.com/150",
      "SAREhub_1_100_2_id": "5",
      "SAREhub_1_100_2_name": "Półbuty zamszowe Nikopol",
      "SAREhub_1_100_2_image": "https://via.placeholder.com/150"
    },
    "hub_id": "100"
  }
}

personalization_subject - tablica stworzonych wcześniej w panelu SAREhub dowolny identyfikatorów personalizacji (bloczek Personalizacja na stronie). Pozwala na personalizowanie konkretnej podstrony.

Parametr jest tablicą co umożliwia podanie kilku identyfikatorów personalizacji jednocześnie. W przypadku gdy użytkownik powienien otrzymać kilka wiadomości personalizacyjnych funkcja personalization_callback wywoła się osobno dla każdej wiadomości.

Do prawidłowego działania personalizacji wymagane jest ustawienie takich samych identyfikatrów zarówno w kodzie jak i bloczku Personalizacja na stronie.

Brak zdefiniowania paremetru personalization_subject spowoduje pobranie wszystkich możliwych wiadomości dla danego użytkownika.

_images/personalizcja.png

Piksel śledządzy¶

Wstęp do wdrażania i testów¶

Piksel śledzący jest najprostszym sposobem integracji z SAREweb. Wykorzystanie piksela śledzącego jest wygodniejsze, ponieważ cały proces będzie można zredukować nawet do umieszczenia pojedynczego linku na stronie.

Podstawy wdrożenia i testów¶

Zanim zaczniesz wywoływać piksel śledzący pamiętaj, aby poznać swój unikalny identyfikator z panelu SAREhub. Podczas wysyłania zdarzeń będziemy mieli do czynienia z ustawieniem parametrów takich jak:

domain - Unikalny identyfikator z panelu SAREhub.

email - Nie jest wymagany. Adres email użytkownika.

user_id - Nie jest wymagany. Unikalny identyfikator użytkownika.

cart_event - Przyjmuje typ zdarzenia koszykowego. Należy wybrać jedno z:

category_seen,

product_seen,

cart_added_product,

cart_removed_product,

cart_changed_product_quantity,

cart_checkout_started,

cart_checkout_registration

cart_checkout_delivery,

cart_checkout_payment,

cart_checkout_summary,

cart_checkout_confirm,

cart_checkout_completed

product_id - Identyfikator produktu zgodny z product feedem.

quantity - Przyjmuje ilość produktów. Dotyczy tylko zdarzeń:

cart_added_product,

cart_changed_product_quantity

cart_id - Nie jest wymagany. Przyjmuje unikalny identyfikator koszyka.

country - Nie jest wymagany. Domyślnie zostanie ustawiona wartości PL. Przyjmuje wartość kraju docelowego product feeda w formacie ISO 3166-1 alfa-2.

language - Nie jest wymagany. Domyślnie zostanie ustawiona wartości pl. Przyjmuje wartość języka w jakim przygotowany jest product feed w formacie ISO 639-1.

Każde zdarzenie można dodatkowo wzbogacić o tagi UTM:

utm_source

utm_medium

utm_term

utm_content

utm_campaign

Poprzez wysyłanie zdarzeń można dodatkowo otagować użytkownika w SAREhub:

tags - przyjmuje pojedyńczy tag lub listę tagów rozdzielonych przecinkiem.

Przykłady wdrażania i testów¶

Przejście w kategorię produktu¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=category_seen&category_id=1

Przejście na stronę produktu¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=product_seen&product_id=1

Dodania produktu do koszyka¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_added_product&product_id=1&quantity=2

Usunięcia produktu z koszyka¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_removed_product&product_id=1

Zmiana liczby produktów w koszyku¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_changed_product_quantity&product_id=1&quantity=5

Parametr quantity powinien przyjmować wartość aktualnego stanu ilości produktu w koszyku, przykładowo jeśli w koszyku były 3 jednostki danego produktu i zwiększamy ilość o 2j. (czyli w sumie na 5j.) wartość parametru quantity będzie wynosić 5.

Rozpoczęcie procesu zamówienia¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_checkout_started

Podanie danych osobowych¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_checkout_registration

Wybór formy dostarczenia¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_checkout_delivery

Wybór sposobu płatności¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_checkout_payment

Podsumowanie koszyka¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_checkout_summary

Potwierdzenie zakupu¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_checkout_confirm

Finalizacja zakupu¶

https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_checkout_completed

Przykłady wywolania¶

Wywołanie z użyciem jQuery:

$.ajax({
    url: ''https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_added_product&product_id=1&quantity=2'',
    type: 'GET',
    xhrFields: {
        withCredentials: true
    },
    crossDomain: true
});

Wywołanie za pomocą Fetch:

fetch('https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_added_product&product_id=1&quantity=2', {
    credentials: "include",
    mode: "no-cors"
});

Umieszcznie w kodzie HTML:

<img height="1" width="1" src="https://api.sare25.com/collect?domain=<unikalny_identyfikator>&email=<test@sarehub.pl>&cart_event=cart_added_product&product_id=1&quantity=2">

Read the Docs v: latest

Versions: latest

Downloads: html

On Read the Docs: Project Home; Builds

Free document hosting provided by Read the Docs.