Instrukcja wdrożenia YouLead na stronie WWW

Standardowe wdrożenie systemu YouLead na stronie WWW polega na wykonaniu następujących operacji:

1. Instalacja kodu śledzącego
2. Podłączenie formularzy kontaktowych  za pomocą
   • API JavaScript
   • API serwerowego
3. Trackowanie oglądania produktów
4. Trackowanie linków zewnętrznych
5. Trackowanie dowolnych zdarzeń na stronie
6. Personalizowane elementy na stronie WWW

Instalacja kodu śledzącego

Kod śledzący jest krótkim kodem JavaScript, który powinien zostać umieszczony na stronach WWW, które mają być podłączone do YouLead. Kod należy umieścić bezpośrednio przed tagiem zamykającym </body> strony WWW. W kodzie należy podmienić <clientId> na swój unikalny identyfikator klienta uzyskany od zespołu YouLead.

<script type="text/javascript">
var youleadId = 'clientId';
var youleadDC = true; 

(function() {
	var yl = document.createElement('script');
	yl.type = 'text/javascript';
	yl.async = true;
	yl.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'm-' + youleadId + '.youlead.pl/m.js?ts=' + (new Date()).getTime();
	document.getElementsByTagName('body')[0].appendChild(yl);
})();
</script>

Kod śledzący dodatkowo znajdziesz w sekcji Ustawienia/Integracja aplikacji YouLead.

Podłączenie formularzy kontaktowych

Formularze kontaktowe mogą być zintegrowane z YouLead na dwa sposoby:

• za pomocą API JavaScript 
• za pomocą API serwerowego

Różnica pomiędzy tymi dwoma podejściami jest zasadnicza. W przypadku API JavaScript dane są przesyłane bezpośrednio z przeglądarki internetowej do YouLead bez udziału serwera, na którym hostowany jest serwis WWW. Z kolei API serwerowe umożliwia przekazanie danych do YouLead z poziomu serwera WWW. Pierwszy sposób jest szybszy w implementacji, ale może być bardziej zawodny, ponieważ zależy od specyfiki konkretnego serwisu WWW (np. czy strona się przeładowuje po wypełnieniu formularza czy nie). Drugi sposób jest bardziej złożony w implementacji, ponieważ każde wywołanie wymaga uwierzytelnienia, ale jest bardziej niezawodny.

W poniższy sposób należy wykonać integrację wszystkich formularzy w serwisie WWW.

Podłączenie formularzy za pomocą API JavaScript

W celu podłączenia istniejących w serwisie WWW formularzy kontaktowych do systemu YouLead należy wykonać następujące operacje:

a) Do każdego pola w formularzu (input), którego wartość ma zostać zapisana w YouLead, należy dodać klasę css z o nazwie rozpoczynającej się od prefiksu yl- . Wartość występująca po prefiksie zostanie użyta jako identyfikator przekazywanego do YouLead pola formularza i będzie wyświetlana np. w historii wypełnionych przez Kontakt formularzy. Jeśli identyfikator przekazywanego pola pokrywać się będzie z aliasem któregoś z atrybutów zdefiniowanych w YouLead – podczas zapisywania formularza dojdzie również do aktualizacji wartości tego atrybutu w Kontakcie, który wypełniał formularz. Analogicznie sytuacja wygląda w przypadku zgód, jeśli takie zdefiniowano w YouLead. Oznaczenie któregoś z pól w formularzu klasą css, która po prefiksie yl- zawiera ciąg znaków odpowiadający aliasowi jednej ze zgód w YouLead, może spowodować zmianę wartości tej zgody w Kontakcie po wypełnieniu przez niego formularza. Spodziewane wartości pól dotyczących zgód to true lub false.

Przykład

W formularzu jedno z pól zdefiniowane jest w następujący sposób:

<input type="text" id="hobby" class="yl-hobby userdefinedclass1 userdefinedclass2" value="describe your hobby" />

Kontakt wypełnia formularz podając w powyższym polu wartość „running”. Po zapisaniu formularza w karcie Kontaktu znajdzie się informacja o wypełnionym formularzu z polem: hobby:running. Jeśli wśród zdefiniowanych w YouLead atrybutów znajduje się taki, którego aliasem jest hobby, to wartość tego atrybutu również zostanie ustawiona na running w Kontakcie, który wypełniał formularz (nadpisując poprzednią wartość tego atrybutu).

W systemie istnieją predefiniowane atrybuty, których aliasów można użyć do standardowych pól formularzy:

• adres email: yl-email
• imię: yl-name
• nazwisko: yl-lastName
• telefon: yl-phone
• miejscowość: yl-city

Jeśli formularz zawiera inne pola (dla których nie istnieją w YouLead pasujące atrybuty), należy utworzyć nazwy klas css dla tych pól w dowolny sposób pozwalający na późniejsze ich rozróżnienie, np.:

• pole Treść wiadomości może mieć klasę css yl-message
• pole Tytuł może mieć klasę css yl-title

W powyższy sposób do YouLead można również przekazywać wartości pól typu hidden (należy analogicznie jak w powyższych przykładach nadać im odpowiednią klasę css).

b) Po poprawnym zwalidowaniu formularza należy wywołać funkcję Monitor.TrackForm dostępną w API JavaScript YouLead. Funkcja jest dostępna na stronie WWW po instalacji kodu monitorującego YouLead. Wywołanie funkcji wysyła  dane z formularza do systemu YouLead.

Przykładowe wywołanie:

Monitor.TrackForm('contactForm', postForm);

Szczegółowy opis funkcji oraz jej parametrów znajduje się w specyfikacji API.

Należy zwrócić uwagę na następujące kwestie:

1) wywołanie funkcji Monitor.TrackForm powinno mieć miejsce po poprawnym zwalidowaniu formularza

2) jeśli wysłanie formularza do serwera (submit) powoduje przeładowanie strony, należy najpierw wywołać API JavaScript przekazujące dane do YouLead, a przekazanie danych do serwera (przeładowanie strony) wykonać dopiero w funkcji callback przekazanej do Monitor.TrackForm jako parametr – szczegóły w specyfikacji API.

3) status SMS oraz status E-mail mogą być ustawiane w Kontakcie na kilka sposobów podczas wypełniania formularza (przy czym kolejność opisywanych sposobów ma znaczenie, jeśli zaistnieje jeden, następne w kolejności nie są brane pod uwagę):

• poprzez jawne przekazanie ich wartości podczas wywoływania Monitor.TrackForm
• jeśli powyższe nie miało miejsca, wówczas ustawienie statusów może nastąpić automatycznie w związku z wartością zgód przekazanych w formularzu (wg zasad zawartych w opisie modułu zgód)
• jeśli powyższe nie miało miejsca, wówczas należy założyć, że wraz z zapisem formularza zostały przekazane domyślne wartości statusów, zgodnie z opisem w API JavaScript

Podłączenie formularzy za pomocą API serwerowego

W celu podłączenia istniejących w serwisie WWW formularzy kontaktowych do systemu YouLead należy wywołać metodę /Command/Contact/FillForm z metod Api Serwerowego opisaną w specyfikacji API.

Minimalny zestaw danych, które muszą być przekazane do systemu to parametr formData. Parametr ten powinien przyjąć postać JSON zawierającego zestaw informacji o przekazywanych polach formularza. Użyte identyfikatory pól będą wyświetlane w historii wypełnionych przez Kontakt formularzy. Jeśli identyfikator pola pokryje się z aliasem któregoś z atrybutów zdefiniowanych w YouLead – dodatkowo wartość tego pola zostanie wpisana do atrybutu dla Kontaktu podczas wypełniania formularza.

Przykład

Dla formularza rejestracji na stronie WWW parametr formData może przyjąć wartość:

"formData" : {
'email': 'john@doe.com', 
'name': 'John', 
'lastName': 'Doe', 
'phone': '500111222', 
'city': 'Warsaw', 
'consent_processing': '1', 
'consent_marketing': '1'}

W systemie istnieje kilka predefiniowanych atrybutów, których aliasów można użyć do standardowych formularzy, np:

• adres email: email
• imię: name
• nazwisko: lastName
• telefon: phone
• miejscowość: city

Uwaga: Mimo, że poniższe parametry metody FillForm nie są obowiązkowe, zasadniczo powinny być także przekazywane (chyba, że istnieją bardzo uzasadnione przeszkody, może to jednak powodować niepoprawne działanie niektórych funkcjonalności systemu):

• ylid (zawartość ciasteczka ylid)
• pageUrl (adres url strony, na której wypełniono formularz)
• referrer (adres strony odwiedzonej przed aktualnie odwiedzoną stroną; sposób odczytu zależy od konkretnego serwera WWW, który będzie wywoływał API YouLead)
• sessionId (zawartość ciasteczka ylssid)
• utm (zawartość ciasteczka ylutm)
• formId (identyfikator html wypełnionego formularza)

Po poprawnym wywołaniu metody /Command/Contact/FillForm w systemie rejestrowane jest nowe wypełnienie formularza. Jeśli adres email przekazany w wywołaniu istnieje już w systemie, formularz jest dopisywany do kontaktu posiadającego ten adres e-mail.

Należy pamiętać, aby po wywołaniu metody /Command/Contact/FillForm  wydrukować w kodzie strony ciąg zwracany w parametrze returnCode – szczegóły w opisie metody w pliku ze specyfikacją API.

Należy również zwrócić uwagę na fakt, że wywołanie metody /Command/Contact/FillForm powinno mieć miejsce po poprawnej walidacji formularza.

Uwaga: jeśli strona internetowa korzysta z tzw. modelu double-opt-in, przy czym e-mail aktywacyjny jest wysyłany przez silnik strony WWW a nie przez YouLead – konieczne jest przekazywanie informacji o klikach w e-maile aktywacyjne do YouLead. Można to zrealizować np. poprzez wywołanie metody /Command/Contact/UpsertsByEmail z metod Api Serwerowego opisaną w specyfikacji API z parametrem statusEmail ustawionym na wartość 3 (Aktywny). Przykładowa wartość contacts w wywołaniu tej metody:

"contacts":[
   {
      "requestId":123,
      "emailKey":"john@doe.com",
      "statusEmail":3
   }
]

Trackowanie oglądania produktów

Mówiąc o trackowaniu oglądania produktów należy wziąć pod uwagę dwa elementy:

a. przygotowanie i przekazanie urla do feeda produktowego (szczegółowy opis pliku znajduje się w  YouLead – specyfikacja feeda produktowego)
b. We wszystkich miejscach w serwisie WWW gdzie przeglądane są produkty należy użyć funkcji product z API JavaScript – przekazując w wywołaniu identyfikator produktu/produktów odpowiadających identyfikatorom zawartym w przekazywanym feedzie produktowym. W przypadku, gdy do YouLead importowanych jest kilka feedów, w których identyfikatory produktów mogą się powtarzać (np. kilka feedów w różnych językach, ale z tymi samymi produktami) – po identyfikatorach produktów należy dodać @feed, gdzie feed to identyfikator feeda produktowego, w którym znajduje się aktualnie oglądany produkt.

Przykłady

ylData.push({ 'product': { 'products': ['a6d08b92-42ca-4457-9633-829e8371f76b@PL', 'a6d08b92-42ca-4457-9633-829e8371f76b@EN'] } });

ylData.push({ 'product': { 'products': ['a6d08b92-42ca-4457-9633-829e8371f76b'] } });

Trackowanie linków zewnętrznych

W celu przekazania do systemu YouLead informacji o kliknięciu przez użytkownika na stronie WWW w link zewnętrzny (czyli kierujący do strony, na której nie są jest osadzony kod śledzący YouLead, np. stron WWW mediów społecznościowych, portali) należy do elementu html <a> dodać klasę css yl-link

Przykład:

<a href="www.abcdefg.com" target="_blank" class="some_css_class yl-link">link zewnętrzny</a>

W analogiczny sposób można również trackować kliki w linki do plików PDF, DOC, JPG itd.

Kliknięcia w linki zewnętrze mogą być użyte w YouLead do uruchomienia zdefiniowanych reguł i scenariuszy.

Trackowanie dowolnych zdarzeń na stronie

W celu przekazania do systemu YouLead informacji o zdarzeniu na stronie należy wywołać funkcję event z API JavaScript. Dzięki przekazaniu informacji o zdarzeniu do systemu, możliwe jest definiowanie reguł i scenariuszy w YouLead, które uruchamiane są po zaistnieniu zdarzenia.

Przykłady zdarzeń, których wystąpienia można przekazać do YouLead:

• Przewinięcie slajdera na podstronie serwisu
• Odsłonięcie przez usera numeru telefonu
• Wyświetlenie popupu
• Przechodzenie przez użytkownika poszczególnych etapów kreatora/konfiguratora

Personalizowane elementy na stronie WWW

YouLead pozwala na wyświetlanie spersonalizowanych elementów na stronie WWW np.banerów, slajderów, widgetów. Dodanie takiego elementu na stronie WWW sprowadza się do umieszczenia w kodzie HTML strony odpowiedniego tagu <div> w miejscu, w którym powinien pojawić się element. Po załadowaniu strony WWW dodany tag div zostanie zamieniony przez skrypty YouLead na element spersonalizowany dla konkretnego użytkownika.

Dodawany tag <div> musi spełniać następujące warunki:

• atrybut id tagu div musi mieć taką samą wartość jak identyfikator (alias) spersonalizowanego elementu zdefiniowanego w YouLead
• tag div powinien być oznaczony klasą css o nazwie yldynamiccontent

Szerokość, wysokość i miejsce umieszczenia tagu div zależą od przeznaczenia i funkcji elementu personalizowanego.

Uwaga

Wdrożenie YouLead oznacza zintegrowanie go z  określoną strukturą strony WWW oraz w niektórych przypadkach – feeda produktowego. Zmiany tych struktury bez uzgodnienia z YouLead mogą spowodować, że zdefiniowane mechanizmy (śledzenie na stronach, zapisywane formularze, popupy etc.) przestaną poprawnie funkcjonować. W związku z tym YouLead powinien być informowany o zmianach w strukturze strony WWW lub feeda, w tym w szczególności o:

• wszelkich zmianach w formularzach na stronie WWW (w tym html id formularzy)
• zmianach w strukturze strony WWW, gdy są tam osadzone treści generowane przez YouLead (np. ramki rekomendacyjne)
• zmianach w adresach URL stron (mogą od nich zależeć np. reguły i scenariusze)
• zmianach w strukturze feeda produktowego (np. nowe kolumny w pliku csv albo zmiany w pliku xml). Należy również wziąć pod uwagę, że YouLead w komunikacji używa takich informacji o produktach (nazwy, ceny, zdjęcia), jakie zostały zaimportowane podczas ostatniego importu feeda produktowego. Jeśli baza produktów klienta uległa zmianie po ostatnim imporcie feeda, YouLead użyje w komunikacji nieaktualnych danych o produktach.