Event API

Systém událostí však neslouží pouze k realizaci remarketingových kampaní, ale i měření konverzí a obecně chování a zájmů uživatelů na stránkách. Pokud tedy chcete měřit efektivitu vašich kampaní co do konkrétních tržeb, je nutné nasadit JS kód Event API minimálně na stránku dokončení objednávky, aby bylo možné změřit hodnotu konverze.

Existují dvě odlišné metody, jak můžete Event API na vašem webu použít. První spoléhá na integraci Google Analytics Enhanced E-commerce (EE) na webu, druhou metodou je zcela nezávislá implementace. V obou případech je potřeba načtením skriptu a konfigurace iniciovat naši EventAPI. Pokud na svém webu máte EE, stačí jej pouze povolit a nakonfigurovat jeho prvky – viz Použití s Google Analytics Enhanced E-commerce. Tato dokumentace se věnuje použití EventAPI s pomocí javascriptů Mailkit Events. V případě, že si chcete vytvořit vlastní skripty, nebo komunikovat s naším backendem v režimu server-to-server, navštivte naši dokumentaci EventAPI backendu.

Inicializace API

Než je možné začít obsluhovat události, je nutné inicializovat samotné API a načíst obslužný skript Mailkit JS API:

Údaj API ID se nastavuje pomocí setAPIID a je k nalezení ve vašem účtu v menu Profil/Integrace. V parametru setDomain musí být uvedeno hostname či jméno domény, na které je kód umístěn a to bez http/https. Doména musí být doplněna i do seznamu povolených domén, ze kterých chcete povolit přístup k vašemu účtu. setMode je operační režim skriptu. Pokud je režim nastaven na “debug”, skript zaznamená protokoly provedených volání do koncového bodu API. Protokol je poté možné zobrazit v JS konzoli Nástroje pro vývojáře ve vašem prohlížeči. 

Při autorizaci každého požadavku pak musí být shoda všech tří autorizačních prvků – referer (stránka, ze které probíhá volání), hodnota setDomain a povolená doména v profilu. Pokud je tedy váš web dostupný na vícero adresách např. www.domena.cz i domena.cz, pak je nutné zajistit, že hodnota v setDomain vždy odpovídá tomu, co je vidět v adresním řádku prohlížeče. Zároveň pak musí být mezi povolenými doménami adresa s www i bez.

Použití s Google Analytics Enhanced E-commerce (synchronizací z DataLayeru)

EventAPI je schopné synchronizovat data košíku z DataLayeru. Pokud chcete tuto funkcionalitu využívat, musíte ji povolit použitím příkazu:

Tím dojde k vytvoření nového mailkit event tagu zvaného cart. Pokud chcete používat enhancedEcommerce synchronizaci, ujistěte se, že neexistuje žádný jiný event s tagem cart. 

EventAPI Mailkitu aktuálně podporuje synchronizaci eventů addToCart, removeFromCart, checkout a purchase. Aby mohla eventAPI sledovat eventy zákazníků, musíte ve skriptu definovat, co má sledovat. To uděláte následujícím nastavením:

Pro více informací o měření pomocí Google Enhanced Ecommerce, klikněte zde.

Pokud použijete synchronizaci událostí s Google Analytics Enhance E-commerce, máte v tuto chvíli vše ohledně nákupních aktivit nastaveno. Pokud to však není váš případ, nebo chcete předávát další typy aktivit z vašich stránek, bude nezbytné implementovat individuální volání pro webové aktivity návštěvníků s použitím následujících funkcí.

Vznik události

Po inicializaci API je vždy nutné volat funkci pro inicializaci/načtení údálosti. Toto volání je nutné provádět na každé stránce, na které má proběhnout jakákoliv manipulace s údálostí, např. pokud chceme průběžně přidávat položky do košíku a zároveň je ukládat do události. Funkce initEvent při svém spuštění vytvoří záznam události na serveru, nebo v případě existence události reaktivuje událost pro další manipulaci.

Žádný z údajů není pro založení události povinný, neboť událost může existovat delší dobu a může být dodatečně doplněna o potřebné údaje.

email – e-mailová adresa návštěvníka (pokud je známa), na kterou budou směřovány případné zprávy. V případě, že bude uvedena hodnota detect místo e-mailové adresy, proběhne automatická identifikace návštěvníka na základě předchozích aktivit. Na automatickou detekci se však není možné spolehnout, neboť tento údaj není vždy k dispozici. Kdykoliv je tento údaj k dispozici, snažte se ho předávat. Předání e-mailové adresy pomáhá eliminovat duplicity a především je nezbytné k odeslání zprávy.
event_tag – slouží k rozlišení vícero eventů v rámci stránek. Je možné mít jednu z událostí bez uvedení tagu a další již mít otagovavné, nicméně doporučujeme z důvodu přehlednosti vždy tagovat všechny události. Tag nesmí obsahovat mezery ani speciální znaky. Tento tag se následně uvádí u remarketingové kampaně jako filtr, tzn. že se má zpráva zaslat jen pro události označené určitým tagem.
return_url – návratová adresa, na kterou povede odkaz z e-mailu události. Obvykle se jedná o URL nákupního košíku. (max. 1024 znaků), URL musí začínat http/https.
description – doplňující popis, který lze použít v tělě zprávy události, (max 2048 znaků)
language – jazyk události v formátu ISO 639-1. Tento dvojpísmenný kód jazyka je možné použít ve zprávách jako podmínku pro určení jazyka textu zprávy.
currency – měna položky ve formátu ISO 4217 – třípísmenná zkratka, např. CZK, EUR, USD. Kód měny je vhodné používat v případech, kdy provozujete eshop s vícero měnami. Mailkit vám v reportech následně zobrazí částky sjednocené do vaší domácí měny.
decimal_separator – vzhledem k tomu, že každá země používá jiné formátování čísel, je nutné specifikovat, jaký budete používat oddělovač. Na základě toho, zda budete používat pro oddělování desetin . nebo , uveďte vámi používaný oddělovač.
first_name – jméno návštěvníka, pokud je známé. Tento údaj je následně možné ve zprávě použít k personalizaci.
last_name – příjmení návštěvníka, pokud je známé. Tento údaj je následně možné ve zprávě použít k personalizaci.
gender – pohlaví návštěvníka (M = muž/F = žena), pokud je známé. Tento údaj je následně možné ve zprávě použít k personalizaci.
order_no – číslo objednávky. Kdykoliv je to možné, snažte se doplnit unikátní číslo objednávky. Je to jeden z údajů, které pomohou zabránit duplicitním událostem, které mohou vzniknout v případě, že návštěvník přejde z jednoho počítače na druhý, atp.
promo – pokud ve vašem systému generujete slevové kupony motivující k dalším aktivitám, můžete zde uvést tento slevový kód. Tento kód je pak možné vložit do obsahu zprávy.
promo_value – pokud poskytujete slevový kód, tak doporučujeme uvést i jeho hodnotu, kterou pak můžete vložit do obsahu zprávy.
promo_teaser – často je vhodné do předmětu nebo těla zprávy vložit doplňující text pro nalákání zákazníka.
lifetime – vlastní délka platnosti sledovací cookie události (standardně 30 dní), tzn. hodnota (ve dnech) udává, jak dlouho má nedokončený event čekat na dokončení. Při každé aktualizaci nedokončené události dojde k resetu počítadla a čas nastavený v parametru lifetime začne běžet od začátku.

Položky události

Vytvořenou událost je nutné následně plnit konkrétním obsahem. To lze provést jak na jednom místě, např. na stránce nákupního košíku, tak průběžně v okamžiku, kdy návštěvník klikne na přidání položky do košíku. Zde je nutné upozornit, že systém nesupluje nákupní košík, ani neprovádí vlastní počítání položek a je úkolem provozovatele stránek korektně předávat ceny, počty položek, přidávat položky i odstraňovat položky.

Základní funkce pro přidání položky do eventu se nazývá addItem:

event_tag – identifikátor události založené přes initEvent. Pokud není u eventu definován event_tag, pak ani zde nebude. Pokud však byl event založen s tagem, pak je nutné identifikovat i položky.
product_id (povinné) – identifikátor produktu (skladové číslo). Jedná se o unikátní údaj a tudíž v události může figurovat pouze jedna položka s daným product_id. Pokud bude předáno více položek se stejným product_id, budou tyto položky ignorovány, nikoliv přičteny do počtu položek. (max. 32 znaků)
name – název produktu. Tento údaj lze následně použít v těle zprávy. (max. 256 znaků)
description – popis produktu. Tento údaj lze následně použít v těle zprávy. (max. 2048 znaků)
teaser – doplňující text k produktu. Tento údaj lze následně použít v těle zprávy. (max. 256 znaků)
price – cena produktu (jednotková). Tento údaj lze následně použít v těle zprávy. Hodnota musí být číslem bez znaků a symbolů.
price_orig – původní cena produktu (jednotková) před slevou. Tento údaj lze následně použít v těle zprávy. Hodnota musí být číslem bez znaků a symbolů.
item_qty – počet jednotek (možno i desetinná čísla). Hodnota musí být číslem bez znaků a symbolů.
item_total – celková cena za produkt při daném počtu jednotek (násobek price a item_qty). Výpočet musí být proveden na straně obchodu – Mailkit nevykonává nad údaji žádné počty. Hodnota musí být číslem bez znaků a symbolů.
item_discount – výše slevy na produktu ať už procentuálně nebo jako částka. Tento údaj lze následně použít v těle zprávy. (max. 8 znaků)
item_available – dostupnost produktu ať už počet kusů, nebo např. název prodejny. Tento údaj lze následně použít v těle zprávy. (max. 64 znaků)
product_url – URL produktové stránky. Tento údaj lze následně použít v těle zprávy. (max. 256 znaků)
product_category – název produktové kategorie produktu. Tento údaj lze následně použít v těle zprávy. (max. 64 znaků)
product_cat_url – URL stránky produktové kategorie. Tento údaj lze následně použít v těle zprávy. (max. 256 znaků)
image_url – URL obrázku produktu. Tento údaj lze následně použít v těle zprávy. (max. 256 znaků)

Nikdy nezapomínejte, že unikátním identifikátorem položky v události je vždy product_id, které musí být vždy unikátní. Pokud tedy chcete např. změnit počet kusů určité položky, je nutné nejprve provést odstranění položky a následně provést její nové vložení s uvedením nového počtu.

Pro přidání/aktualizaci produktů v košíku můžete alternativně využít metodu addItemU. Základní rozdíl mezi touto metodou a addItem je v tom, že addItemU je míněna jako doplňková funkce pro aktualizaci. Voláním funkce addItemU se množství položky zvýší.

Zde je příklad pro volání addItemU:

Všimněte si, že v tomto volání chybí parametr item_total. Důvodem je, že případě addItemU probíhá součet na pozadí. Takže pokud přidáte 5 položek, kdy cena každé je 5 $, a následně přidáte dalších pět se stejnou cenou, na pozadí bude spočítána celková částka ve výši 50 $. 

Pro odstranění položky dat z události (vyřazení položky z košíku) lze volat funkci removeItem:

Pokud chcete odebrat konkrétní množství daného produktu, můžete za tímto účelem zavolat funkci removeItemU.

removeItemU, stejně jako addItemU, také nebere v úvahu item_total. Částky jsou zpracovány samostatně na backendu. 

Případně lze smazat všechny položky události pomocí clearItems:

Skript eventAPI také poskytuje funkci pro předání informace o návštěvách pro pokročilé sledování chování návštěvníků. Toto je obzvláště důležité v případě, že budete využívat napojení na systémy třetích stran pro vytváření doporučení (např. Recombee) pomocí předávání událostí. Každé zobrazení stránky detailu produkty by mělo být předáno voláním funkce viewItem.

Reset události

Za určitých situací je vhodné provést reset události, tzn. zrušení průběhu existující události a založení zcela nové. K tomu účelu je možné volat funkci resetEvent, která fakticky smaže existující identifikátor události z prohlížeče návštěvníka a vyžádá nový identifikátor:

Při zavolání funkce resetEvent dojde ke skončení platnosti cookie v prohlížeči zákazníka, takže se při dalším zavolání initEvent založí nový prázdný event, který je potřeba znovu naplnit položkami. Původní (resetovaný) event zůstane zachován a bude nadále zobrazován v reportu nedokončených událostí (i s položkami, které v něm byly ve chvíli resetu), ale kampaň, která je s eventem propojena, již na tento resetovaný event reagovat nebude.

Aktualizace události

V kterékoliv fázi procesu dojde k volání funkce initEvent pro uživatele s již přidělenou cookie události s novými parametry, dojde k aktualizaci existujících údajů události. Toto je obzvláště vhodné např. v situaci, kdy uživatel v průběhu operace uvede e-mailovou adresu, provede přihlášení, nebo např. dojde k přidělení unikátního čísla objednávky, atd. Vždy pamatujte, že čím více údajů je u události dostupných, tím lépe můžete vaše remarketingové zprávy personalizovat a zvýšit tak jejich účinnost.

Ukončení události

V případě, že založená událost je zdařile dokončena, tzn. např. dojde k úspěšné objednávce, je zapotřebí událost dokončit pomocí funkce finishEvent:

V tomto okamžiku dojde na straně Mailkitu k nastavení stavu události na dokončenou, uloží se případné číslo objednávky/faktury, doplňující URL, text poděkování a tato událost se stává úspěšnou konverzí v případě, že k došlo k dokončení na základě kliknutí na odkaz v remarketingovém e-mailu. V případě, že dokončení proběhlo bez remarketingové aktivity, bude konverze připočítána k původní kampani, pokud zde bude existovat taková vazba.

Všechny předávané parametry lze samozřejmě použít v těle remarketingové kampaně, např. pro notifikaci o vystavené faktuře.