Google Tag Manager (GTM) to jeden z rekomendowanych sposobów wdrożenia skryptu śledzącego Positive User na Twojej stronie. Gdy GTM dostarczy skrypt, Positive User zaczyna śledzić osoby odwiedzające stronę, tworzy profile kontaktów i pozwala wzbogacać je o dane istotne dla Twojego biznesu.
Ten przewodnik obejmuje trzy zagadnienia:
Instalację podstawowego skryptu wdrożeniowego;
Identyfikację kontaktów przy pomocy Contact ID;
Rozszerzenie konfiguracji o dodatkowe dane kontaktu oraz callbacki.
Aktywny workspace Positive User.
Klucz workspace oraz informacja o subdomenie (znajdziesz je w „ustawieniach workspace" → „API & Integrations" → sekcja „Setup & Integrations").
Dostęp do kontenera GTM zainstalowanego na Twojej stronie.
Wdrożona strategia cookies/zgód.
Jeśli Twoja strona korzysta z Content Security Policy, upewnij się, że domeny Positive User są dodane do białej listy.
Skrypt wdrożeniowy definiuje obiekt konfiguracyjny (window.civchat), a następnie ładuje „widget.js". Dodanie go przez GTM oznacza, że możesz go wdrażać, aktualizować lub wstrzymywać bez ponownej ingerencji w kod strony.
Pobierz klucz workspace i subdomenę
W swoim workspace Positive User przejdź do „ustawień workspace" → „API & Integrations" → „Setup & Integrations", aby znaleźć klucz workspace, oraz zanotuj subdomenę workspace (np. yourapp.user.com).
Utwórz tag Custom HTML w GTM
Zaloguj się do kontenera GTM i przejdź do „Tags" → „New" → „Tag Configuration" → „Custom HTML", a następnie wklej poniższy skrypt. Zamień YOUR_KEY na klucz workspace z kroku 1, a yourapp.user.com na swoją subdomenę workspace:
<script data-cfasync="false" type="text/javascript">
window.civchat = {
apiKey: 'YOUR_KEY'
};
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Ustaw wyzwalacz w kontenerze GTM
W sekcji „Triggering" wybierz wyzwalacz pasujący do Twojej konfiguracji zgód – zazwyczaj jest to zdarzenie „cookie_consent_update" (lub jego odpowiednik). Dzięki temu skrypt ładuje się dopiero po zaakceptowaniu cookies przez osobę odwiedzającą stronę. Jeśli nie masz warstwy zgód, wyzwalacz „All Pages" sprawdzi się jako punkt wyjścia.
Zapisz, przetestuj w trybie Preview i opublikuj
Nadaj tagowi nazwę (np. „Positive User - Tracking Script"), kliknij „Save", a następnie uruchom tryb „Preview" w GTM, aby potwierdzić, że tag się uruchamia, a widget się ładuje. Po weryfikacji prześlij i opublikuj kontener GTM.
Wskazówka: Aby sprawdzić, czy skrypt jest w pełni załadowany na stronie, otwórz konsolę przeglądarki i uruchom typeof UE === 'object' && typeof userengage === 'function'. Jeśli zwróci true, Positive User jest gotowy do działania.
Domyślnie Positive User śledzi osoby odwiedzające stronę anonimowo, za pomocą cookie (__ca__chat). Aby przekształcić anonimowego odwiedzającego w rozpoznawany kontakt – i zachować spójność jego historii pomiędzy urządzeniami i sesjami – przekaż Contact ID przez pole (atrybut) „user_id" w obiekcie „window.civchat".
Wybór odpowiedniego Contact ID
Wartość użyta jako Contact ID zależy od tego, jak Twoja firma identyfikuje osoby. Nie ma jednego właściwego wyboru; powinien to być stabilny, unikalny identyfikator, który możesz przekazywać konsekwentnie we wszystkich punktach styku. Trzy najczęściej stosowane opcje to:
Wewnętrzne ID z bazy danych: najbardziej stabilna opcja, ponieważ nigdy się nie zmienia, nawet jeśli kontakt zaktualizuje swój e-mail. Używane w przykładach w tym artykule.
E-mail zapisany małymi literami: prosty do wdrożenia i czytelny w workspace, ale powiązany z aktualnym adresem e-mail kontaktu.
Hash SHA-256 e-maila zapisanego małymi literami: ta sama unikalność co e-mail, ale przez GTM ani zmienne przeglądarki nie przechodzą surowe dane osobowe.
Więcej o ID przeczytasz w naszym artykule. [LINK]
Wybierz jedną strategię i stosuj ją konsekwentnie na całej stronie oraz we wszystkich środowiskach. Zmiana formatu Contact ID w późniejszym czasie może skutkować zduplikowanymi profilami kontaktów lub utratą ciągłości śledzenia.
Contact ID musi być dostępny w momencie zdefiniowania „window.civchat" – czyli zanim załaduje się „widget.js". Standardowe podejście polega na odczytaniu go z dataLayer, który Twoja strona uzupełnia dla zalogowanych kontaktów, a następnie warunkowym przypisaniu go do obiektu „civchat".
Znajdź Contact ID w swoim dataLayer
Na większości platform e-commerce (Magento, Shopify, WooCommerce, PrestaShop itp.) dataLayer jest już uzupełniony informacjami o zalogowanym kliencie – w tym ID klienta, e-mailem i podstawowymi polami profilu. Nie musisz pisać samodzielnie żadnego JavaScriptu; wystarczy, że wiesz, który klucz dataLayer przechowuje wartość, którą chcesz wykorzystać jako Contact ID.
Aby sprawdzić, co jest dostępne:
Otwórz GTM i kliknij „Preview" w prawym górnym rogu.
Wpisz adres URL swojej strony i zaloguj się jako testowy klient w oknie podglądu.
W GTM Tag Assistant otwórz zakładkę „Data Layer" przy dowolnym zdarzeniu.
Przejrzyj wpisy w poszukiwaniu obiektu zawierającego informacje o kliencie lub użytkowniku. Najczęściej spotykane nazwy kluczy to „visitorId", „user_id", „customerId" lub podobne.
Jeśli Contact ID nie znajduje się w Twoim DataLayer: skontaktuj się z deweloperem lub administratorem platformy i poproś o przesyłanie stabilnego identyfikatora klienta do dataLayer dla zalogowanych użytkowników. Jest to drobna zmiana po stronie platformy i częsty wymóg dla każdego narzędzia śledzącego lub personalizacyjnego integrowanego przez GTM.
Utwórz lub wykorzystaj istniejącą zmienną dataLayer w GTM
W GTM przejdź do „Variables" i sprawdź, czy zmienna dla Twojego ID klienta już istnieje – w kontenerach skonfigurowanych przez agencję lub w ramach istniejącej integracji analitycznej często tak jest. Szukaj zmiennych typu „Data Layer Variable" wskazujących na klucze takie jak „customer_id" lub „user_id". Jeśli taka zmienna już istnieje, możesz ją wykorzystać i przejść do następnego kroku.
Jeśli jeszcze nie istnieje, przejdź do „Variables" → „New" → „Data Layer Variable" i ją utwórz. W polu „Data Layer Variable Name" wpisz dokładną nazwę klucza, którą znalazłeś w swoim dataLayer (np. „customer_id"). Nadaj zmiennej rozpoznawalną nazwę, na przykład „DLV - user_id".
Zaktualizuj tag
Edytuj tag Custom HTML i przypisz Contact ID warunkowo, tak aby był dodawany tylko wtedy, gdy odwiedzający jest faktycznie zalogowany:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Gdy „user_id" jest obecny, Positive User używa go jako głównego identyfikatora. Jeśli ID już istnieje w Twoim workspace, śledzenie przełącza się na profil tego kontaktu; jeśli nie, ID zostaje przypisane do bieżącej sesji anonimowej i tworzony jest nowy kontakt.
Gdy kontakt zostanie zidentyfikowany, możesz wzbogacić jego profil o dodatkowe atrybuty – pola danych zapisywane w profilu kontaktu. Przekaż te wartości na głównym poziomie obiektu konfiguracyjnego civchat, obok „user_id":
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
// Custom attributes go at the same level
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Kilka rzeczy, o których warto pamiętać:
Atrybuty standardowe vs. niestandardowe: Atrybuty standardowe (takie jak „Email", „Phone number", „Gender", „Status") są rozpoznawane przez Positive User automatycznie. Atrybuty niestandardowe (takie jak „Plan type") muszą wcześniej istnieć w workspace – utwórz je wcześniej. (Sprawdź „How to Create a Custom Attribute")
Format ma znaczenie: Zawsze wybieraj odpowiedni typ atrybutu, ponieważ definiuje on dalsze możliwości filtrowania. Pełną listę zasad formatowania znajdziesz w dokumentacji deweloperskiej lub w artykule „What Is an Attribute".
Wartości nadpisują istniejące dane: Każdy przekazany tutaj atrybut zastąpi wartość zapisaną już w profilu kontaktu. Przekazuj atrybuty tylko wtedy, gdy masz rzeczywistą wartość – właśnie dlatego trzymamy je wewnątrz bloku „if" powyżej.
Callbacki pozwalają Twojemu kodowi reagować na to, co dzieje się wewnątrz widgetu Positive User – na przykład, gdy widget zakończy ładowanie lub gdy nadejdzie nowa wiadomość czatu. Definiuje się je jako funkcje wewnątrz tego samego obiektu konfiguracyjnego „civchat", obok „apiKey" oraz „user_id".
Dostępne callbacki
SDK Positive User udostępnia następujące callbacki:
onLoad: uruchamia się po zakończeniu ładowania skryptu widgetu i jego zasobów. Przydatny do kolejkowania innych tagów GTM zależnych od gotowości Positive User.
onMessage: uruchamia się przy każdym odebraniu wiadomości czatu. Obiekt „message" zawiera flagę „isAdmin" wskazującą, czy wiadomość pochodzi od członka zespołu/automatyzacji (true), czy od kontaktu (false).
onOpen / onClose: uruchamia się, gdy widget czatu zostanie rozwinięty lub zminimalizowany.
onPayloadReceived: uruchamia się, gdy widget otrzyma payload z modułu automatyzacji „Send Code".
Pełne informacje znajdziesz w dokumentacji deweloperskiej.
Poniższy skrypt pokazuje pełną konfigurację łączącą wszystko z tego przewodnika: callback onLoad, Contact ID, e-mail oraz dodatkowe dane kontaktu. To wersja, której możesz użyć jako punkt wyjścia w środowisku produkcyjnym:
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY',
// Notify GTM once the widget is fully loaded
onLoad: function() {
dataLayer.push({ event: 'Positive User - Widget Ready' });
}
};
// Identify the contact and pass their data only when logged in
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
W GTM możesz następnie utworzyć wyzwalacz „Custom Event" nasłuchujący na „Positive User - Widget Ready" i wykorzystywać go w każdym tagu, który wymaga dostępności SDK Positive User.
GTM jest wygodny, ale dodaje jedną dodatkową warstwę pomiędzy Twoją stroną a Positive User. Jeśli skrypt nie wydaje się uruchamiać:
Sprawdź w trybie „Preview" w GTM, czy tag faktycznie uruchamia się na stronie.
Upewnij się, że kontener GTM jest opublikowany, a nie tylko zapisany.
Sprawdź w konsoli przeglądarki, czy nie występują błędy JavaScript, które mogłyby zatrzymać wykonanie skryptu.
Potwierdź, że adblockery, narzędzia do zarządzania zgodami lub Twoje CSP nie blokują GTM ani domeny Positive User.
Zweryfikuj, czy zmienne dataLayer prawidłowo się rozwijają w trybie Preview – jeśli zmienna jest pusta, odpowiadające jej pole w obiekcie „civchat" również będzie puste.
How to Configure a Chat Widget [LINK]
IDs Concept [LINK]