Dokumentace

Aktualizace 14.2.2017 16:43

Kodérská dokumentace implementace

Nejdříve je třeba v hlavičce <head> HTML dokumentu spustit následující javascriptový snippet. Buď jej můžeme obalit tagem <script> a nechat jej přímo v hlavičce nebo jej přidat k nějakému již hotovému externímu scriptu:

var _soyka = _soyka || [];
(function(d, t) {
	var g = d.createElement(t), s = d.getElementsByTagName(t)[0], h = d.location.hostname;
	g.src = ("https:" == d.location.protocol ? "https://" : "http://") + "s" + (h.indexOf(".") != h.lastIndexOf(".") ? h.substring(h.indexOf(".")) : "." + h) + "/resources/js/soyka-api.js";
	s.parentNode.insertBefore(g, s);
}(document, 'script'));

Není se třeba bát, že vložení scriptu v hlavičce způsobí zpomalení načítání stránky. Funguje to podobně jako u Google Analytics. Nejdříve se vytvoří globálně dostupné pole _soyka, do kterého můžeme přes standardní metodu push vkládat nové prvky. Jakmile se asynchronně načte externí skript, převezme nad polem kontrolu a zavolá do té doby nashromážděné požadavky a bude obsluhovat i následující.

Pro vývojové prostředí je dostupná speciální verze skriptu obsahující konzoli, která umožní přepínat profily uživatelů a tím na živo testovat personalizaci pro různé uživatele. Tato konzole se aktivuje stisknutím klávesy F2. Pro zpřístupnění této vývojářské funkcionality je třeba použít stejný inicializační skriptem, jen je v něm třeba nahradit v URL soyka-api.js za soyka-api-dev.js. Vždy se vkládá buďto produkční nebo vývojářská verze skriptu, nikoli obě zároveň.

Zápis skriptů

Jednotlivé javascriptové funkce obsahují statické a dynamické parametry. Statické v této dokumentaci zapisujeme v apostrofech a ve skriptech zůstávají tak jak jsou uvedeny v dokumentaci.

_soyka.push(['event', <event_source>, 'page-viewed', <attributes>}]);

Například u zaznamenání návštěvy stránky je statickým parametrem 'event' a 'page-viewed'.

Dynamické parametry jako <event_source> a <attributes> je třeba nahradit konkrétní hodnotou a dbát na zachování správného datového typu, který je u každé události uveden v tabulce s parametry. Pokud je dynamickým parametrem strukturovaný objekt, je ve volání zapsán ve formátu JSON, tedy {název_atributu: hodnota} a jednotlivé atributy jsou oddělovány čárkou.

Výsledný skript by mohl tedy vypadat například takto:

_soyka.push(['event', 'web', 'page-viewed', {id: '1234'}]);

Sbírání událostí

Sběr událostí se provádí zavoláním JS funkce:

_soyka.push(['event', <event_source>, <event_type>, <attributes>}]);
Parametr Typ Popis
event_source String Zdroj události. Obsahuje identifikaci např. podle kanálu (web, eshop, mobil) nebo třeba podle top-level domény cz, sk, ...
event_type String Typ události. Používá se v akceptační podmínce u ovladačů událostí např. _.type == 'product', kde eventType je product.
attributes Object Parametry události, které se zaznamenají do databáze.

Návštěva kategorie

Zavolá se při návštěvě kategorie katalogu.

_soyka.push(['event', <event_source>, 'category-viewed', <category>]);
Atributy objektu category
Parametr Typ Povinný Popis
id String Ano ID kategorie (shodné s ID uvedeném v XML feedu katalogu)

Příklad

_soyka.push(['event', 'web', 'category-viewed', {id: '12345'}]);

Návštěva produktu

Zavolá se při návštěvě produktu.

_soyka.push(['event', <event_source>, 'product-viewed', <product>]);
Atributy objektu product
Parametr Typ Povinný Popis
id String Ano ID produktu (shodné s ID uvedeném v XML feedu katalogu)

Příklad

_soyka.push(['event', 'web', 'product-viewed', {id: '12345'}]);

Přihlášení uživatele

Zavolá se po přihlášení uživatele do systému.

_soyka.push(['event', <event_source>, 'customer-logged', <identification>]);
Atributy objektu identification
Parametr Typ Povinný Popis
cid String Ne Jedinečný identifikátor zákazníka.
email String Ne E-mail zákazníka

Příklad

_soyka.push(['event', 'web', 'customer-logged', {cid: '6e2bb6e053a5', email: 'petr@seznam.cz'}]);

Kontaktní údaje

Zavolá se při při přihlášení, registraci, změně kontaktních údajů…

_soyka.push(['event', <event_source>, 'contact-updated', <contacts>]);
Atributy objektu contacts
Parametr Typ Povinný Popis
email String Ne E-mail zákazníka
firstName String Ne Křestní jméno zákazníka
lastName String Ne Příjmení zákazníka
phone String Ne Telefonní číslo zákazníka
zip String Ne PSČ zákazníka

Příklad

_soyka.push(['event', 'web', 'contact-updated', {email: 'petr@seznam.cz', firstName: 'Petr', lastName: 'Vomáčka'}]);

Změna zboží v košíku

Zavolá se při přidání nebo odebrání zboží z košíku, smazání celého košíku či při dokončení objednávky.

_soyka.push(['event', <event_source>, 'basket-updated', <basket>]);
Parametry objektu basket
Parametr Typ Povinný Popis
state String Ano Stav košíku: 'pending' - přidání / odebrání zboží, 'purchased' - dokončení objednávky, 'cancelled' - smazání celého košíku
items String[] Ne Pole ID atributů zboží, které je aktuálně v košíku. Parametr má smysl jen u stavu 'pending'
order String Ne ID objednávky. Má smysl jen u stavu 'purchased'

Příklad

_soyka.push(['event', 'web', 'basket-updated', {state: 'pending', items: ['95454', '32691', '369552']}]);

Zdroj návštěvy uživatele

Tato funkce zjišťuje jednotlivé UTM parametry kampaní a také šifrovanou emailovou adresu v parametru CMID, která slouží k identifikaci uživatelů přicházejících z newsleteru. Tato funkce musí být vložena na všech stránkách webu (například v patičce), kde má být zdroj sledován.

_soyka.push(['campaign', <event_source>]);

Příklad

_soyka.push(['campaign', 'web']);

Personalizace

Žádost o personalizovaný obsah pro daného uživatele se provádí voláním JS funkce:

_soyka.push(['personalize', <locationId>, <callback>, <options>]);
Parametr Typ Povinný Popis
locationId String Ano Id personalizované lokace z administrace Soyky.
callback Function Ano Funkce, která se zavolá s parametry dat z JSONP.
options Object Ne Volitelná konfigurace
Nepovinný parametr options
Parametr Typ Popis
beforeshow Function Funkce, která se zavolá před zavoláním JSONP.
onerror Function Funkce, která se zavolá, pokud nastane během nahrávání JSONP chyba.
parameters Object Objekt nesoucí parametry pro ovladač personalizace.
jsonpTimeout Integer Jak dlouho (v ms) se čeká na nahrání jsonp skriptu než se zavolá onerror. Výchozí hodnota je 10 000 (10s).
Jak to chronologicky funguje?
  1. Zavolá se _soyka.push
  2. Volitelně: Spustí se beforeshow, např. nastavení class="ajax-loading" personalizovanému <div> elementu
  3. Zavolá se JSONP na danou lokaci
  4. Ten vrátí pomocí script novou funkci s argumentem, která obsahuje json data
  5. Vyvolá se funkce callback, a předají se jí hodnoty pro personalizaci
Funkce onerror

Funkce onerror má zpropagovaný objekt v this.error, který může mít následující hodnoty errorCode a errorStatus:

errorCode errorStatus
1 Callback is not a function
2 JSONP request failed
3 JSONP request timed out

Naposledy prohlížené produkty

Vrací seznam naposledy prohlížených produktů s možností omezení na daný počet dní zpět a zvolenou kategorii.

_soyka.push(['personalize', 'lastViewedProducts', function() {
    if (typeof this.products !== 'undefined') {
    // v this.products jsou IDčka produktů
    }
}, {parameters: <parameters>}]);
Parametry požadavku
Parametr Typ Povinný Výchozí hodnota Popis
maxAgeInDays Integer Ne 30 Maximální stáří, kdy byl produkt prohlídnut
limit Integer Ne 5 Maximální počet produktů, které má Soyka vrátit
category String Ne   ID kategorie, do které musí produkty patřit

Příklad:

_soyka.push(['personalize', 'lastViewedProducts', function() {
    if (typeof this.products !== 'undefined') {
    // ...
    }
}, {parameters: {maxAgeInDays: 45, category: '123456'}}]);

Oblíbené kategorie

Vrací seznam oblíbených kategorií katalogu. Požadavek nemá žádné parametry.

_soyka.push(['personalize', 'topCategories', function() {
    if (typeof this.categories !== 'undefined') {
    // v this.categories jsou IDčka kategorií
    }
}]);

Zboží v košíku (zapomenutý košík)

Vrací seznam produktů v košíku uživatele. Požadavek nemá žádné parametry.

_soyka.push(['personalize', 'productsInBasket', function() {
    if (typeof this.products !== 'undefined') {
    // v this.products jsou IDčka produktů
    }
}]);

Doporučené produkty

Vrací seznam doporučených produktů na míru pro daného uživatele na základě jeho předchozího chování. Umožňuje volitelně odfiltrovat již zakoupené nebo aktuálně nedostupné produkty, případně explicitně uvést seznam nežádoucích produktů (např. na stránce již zobrazených v nepersonalizovaném doporučení).

_soyka.push(['personalize', 'recommendedProducts', function() {
    if (typeof this.products !== 'undefined') {
    // v this.products jsou IDčka produktů
    }
}, {parameters: <parameters>}]);
Parametry požadavku
Parametr Typ Povinný Výchozí hodnota Popis
excludePurchased Boolean Ne false Nevracet již zakoupené produkty
excludeOutOfStock Boolean Ne false Nevracet produkty, které nejsou skladem
limit Integer Ne 10 Maximální počet produktů, které má Soyka vrátit
excludeProducts String[] Ne   Pole hodnot typu String, kde každá hodnota je ID produktu, který má být odfiltrován z výstupu
_soyka.push(['personalize', 'recommendedProducts', function() {
    if (typeof this.products !== 'undefined') {
    // ...
    }
}, {parameters: {excludePurchased: true, excludeOutOfStock: true, limit: 20}}]);

Podobné produkty

Vrací doporučení podobných produktů k zadaným produktům (např. k právě zobrazenému produktu). Umožňuje volitelně odfiltrovat již zakoupené nebo aktuálně nedostupné produkty, případně explicitně uvést seznam nežádoucích produktů (např. na stránce již zobrazených v nepersonalizovaném doporučení).

_soyka.push(['personalize', 'similarProducts', function() {
    if (typeof this.products !== 'undefined') {
    // v this.products jsou IDčka produktů
    }
}, {parameters: <parameters>}]);
Parametry požadavku
Parametr Typ Povinný Výchozí hodnota Popis
products String[] Ano   Pole hodnot typu String, kde každá hodnota je ID produktu
excludePurchased Boolean Ne false Nevracet již zakoupené produkty
excludeOutOfStock Boolean Ne false Nevracet produkty, které nejsou skladem
limit Integer Ne 10 Maximální počet produktů, které má Soyka vrátit
excludeProducts String[] Ne   Pole hodnot typu String, kde každá hodnota je ID produktu, který má být odfiltrován z výstupu

Příklad:

_soyka.push(['personalize', 'similarProducts', function() {
    if (typeof this.products !== 'undefined') {
    // ...
    }
}, {parameters: {products: ['12345'], excludePurchased: true, excludeOutOfStock: true, limit: 5}}]);

Doporučené produkty v kategorii

Vrací seznam doporučených produktů v dané kategorii na míru pro daného uživatele na základě jeho předchozího chování nebo případně dle globální popularity produktů. Umožňuje volitelně odfiltrovat již zakoupené nebo aktuálně nedostupné produkty, případně explicitně uvést seznam nežádoucích produktů (např. na stránce již zobrazených v nepersonalizovaném doporučení).

_soyka.push(['personalize', 'recommendedProductsInCategory', function() {
    if (typeof this.products !== 'undefined') {
    // v this.products jsou IDčka produktů
    }
}, {parameters: <parameters>}]);
Parametry požadavku
Parametr Typ Povinný Výchozí hodnota Popis
category String Ano   ID kategorie katalogu
excludePurchased Boolean Ne false Nevracet již zakoupené produkty
excludeOutOfStock Boolean Ne false Nevracet produkty, které nejsou skladem
limit Integer Ne 10 Maximální počet produktů, které má Soyka vrátit
excludeProducts String[] Ne   Pole hodnot typu String, kde každá hodnota je ID produktu, který má být odfiltrován z výstupu

Příklad:

_soyka.push(['personalize', 'recommendedProductsInCategory', function() {
    if (typeof this.products !== 'undefined') {
    // ...
    }
}, {parameters: {category: '123456', excludePurchased: true, excludeOutOfStock: true}}]);

Obohacení webové analytiky o segmenty uživatele

Pro obohacení webové analytiky lze ze Soyky získat segmenty, do kterých je uživatel zařazen a ty pak poslat do analytického nástroje.

_soyka.push(['personalize', 'tags', function() {
    // v this.tags je pole uživatelských segmentů např. ['ACTIVE_VISITOR', 'GENDER_MALE']
    if (typeof this.tags !== 'undefined') {
        // Zde pošleme data do analytického nástroje, např. do dimenze GA:
        // ga('set', 'dimension5', this.tags.toString());
    }
}]);

Měření úspěšnosti personalizace

Reportování úspěšnosti personalizované lokace se provádí voláním JS funkce:

_soyka.push(['locationSuccess', <locationId>, <parameters>])
Parametr Typ Popis
locid String Id personalizované lokace z administrace Soyky
parameters Object Volitelné parametry volání, aktuálně se nepoužívá

Příklad:

Pro reportování úspěšného prokliknutí doporučené nabídky produktů by mělo být volání funkce navěšené na onclick v tomto formátu

_soyka.push(['locationSuccess', 'recommendedProducts']);

a to v obou variantách obsahu, ve výchozím nepersonalizovaném, tak i personalizované nabídce. O vše se postará Soyka interně pomocí vestavěného A/B testu.

Jak to funguje?

Části návštěvníků v rámci A/B testu po dobu jejich návštěvy Soyka záměrně nevrací personalizovaný obsah a ponechává výchozí variantu. Porovnáním úspěšnosti nabídek na webu s a bez personalizace následně měříme úspěšnost personalizace.

Ladění implementace

Ladění implementace Soyky usnadní debugovací režim. Ve vývojářské konzoli prohlížeče, lze režim zapnout příkazem _soyka.debug(true);. Debugovací režim vypisuje do konzole veškerou komunikaci webové stránky se Soykou. Události, volání personalizace i návratové hodnoty personalizace. Vypnout režim lze příkazem _soyka.debug(false);.

Soyka debug

Specifikace XML importu

Tento dokument popisuje XML strukturu integračního rozhraní poskytující data třetí strany do systému Soyka. Tyto data jsou používána ke zpřesnění informací o uživatelském profilu při vyhodnocování jeho chování v integrovaném systému. Aktuálně jsou do systému Soyka importovány informace o katalogu e-shopu a o dokončených objednávkách (transakcích).

XML feedy jsou vystaveny prezentací e-shopu na předem domluvených URL, ze kterých si Soyka periodicky stahuje jejich obsah.

Nedílnou součástí tohoto dokumentu je XSD schéma definující strukturu importních feedů. O URL adresu schématu požádejte svého konzultanta systému Soyka.

Katalog

XML feed katalogu obsahuje vždy všechny aktuálně aktivní produkty. Pokud je nějaký produkt vyřazen z prodeje, není do exportu zahrnut.

Catalog

  Povinný Popis
categories Ne Seznam kategorií v katalogu
products Ne Seznam produktů v katalogu

Category

  Povinný Popis
uid Ano Unikátní identifikátor kategorie. UID musí odpovídat identifikátoru kategorie, který se používá při sběru dat z webu.
name Ano Název kategorie
url Ne URL adresa kategorie
subcategories Ne Seznam podkategorií

Product

  Povinný Popis
uid Ano Unikátní identifikátor produktu. UID musí odpovídat identifikátoru produktu, který se používá při sběru dat z webu
name Ano Název produktu
brand Ano Značka produktu
price Ano Cena produktu
availability Ano

Dostupnost produktu. Platné hodnoty jsou:

  • IN_STOCK – Skladem
  • ON_DEMAND – Na dotaz
  • OUT_OF_STOCK - Nedostupný
categories Ano Kategorie v kterých je produkt zařazen
url Ne URL adresa produktu
relations Ne Seznam vazeb na další produkty
tags Ne Obecné značky produktu

Relation

  Povinný Popis
uid Ano Unikátní identifikátor produktu
type Ano

Typ vazby. Platné hodnoty jsou:

  • ACCESSORY – Příslušenství
  • ALTERNATIVE – Alternativní produkt
  • BUNDLE – Set ve kterém produkt obsažen
  • GIFT – Dárek
  • RECOMMENDATION – Doporučený produkt

Příklad

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
	<categories>
		<category>
			<uid>195e9b00</uid>
			<name>Kategorie 1</name>
		</category>
		<category>
			<uid>915519fd</uid>
			<name>Kategorie 2</name>
			<url>www.mujeshop.cz/kategorie-2</url>
			<subcategories>
				<category>
					<uid>25da22e1</uid>
					<name>Podkategorie 1</name>
				</category>
				<category>
					<uid>20e8b5924</uid>
					<name>Podkategorie 2</name>
				</category>
			</subcategories>
		</category>
	</categories>
	<products>
		<product>
			<uid>0b8ef698</uid>
			<name>Produkt 1</name>
			<brand>Sony</brand>
			<price>1000</price>
			<availability>IN_STOCK</availability>
			<categories>
				<uid>195e9b00</uid>
			</categories>
			<url>www.mujeshop.cz/kategorie-1/produkt-1</url>
			<relations>
				<relation>
					<uid>0b8ef698</uid>
					<type>ACCESSORY</type>
				</relation>
			</relations>
		</product>
		<product>
			<uid>0b8ef698</uid>
			<name>Produkt 2</name>
			<brand>LG</brand>
			<price>500</price>
			<availability>OUT_OF_STOCK</availability>
			<categories>
				<uid>915519fd</uid>
				<uid>20e8b5924</uid>
			</categories>
			<url>www.mujeshop.cz/kategorie-2/produkt-2</url>
		</product>
		<product>
			<uid>0b8ef698</uid>
			<name>Produkt 3</name>
			<brand>Apple</brand>
			<price>100</price>
			<availability>ON_DEMAND</availability>
			<categories>
				<uid>195e9b00</uid>
			</categories>
			<tags>
				<tag>NEW</tag>
				<tag>SALE</tag>
			</tags>
		</product>
	</products>
</catalog>

Objednávky

Objednávky jsou synchronizovány inkrementálně. Velikost inkrementu je řízena Soykou pomocí URL parametru since v GET požadavku na URL feedu. Parametr definuje minimální časové razítko změny objednávek (např. jejího stavu), které mají být zahrnuty do exportu. Jeho hodnota se předává jako počet milisekund od začátku epochy.

Např. požadavek http://www.example.com/export/orders.xml?since=1415660400000 žádá o všechny objednávky změněné od 11.11.2014 00:00:00.

Order

  Povinný Popis
uid Ano Unikátní identifikátor objednávky
created Ano Datum vytvoření objednávky
state Ano

Stav objednávky. Platné hodnoty jsou:

  • NEW – Nová objednávka
  • COMPLETED – Dokončená objednávka
  • CANCELLED – Zrušená objednávka
customer Ano Informace o zákazníkovi
items Ano Seznam položek objednávky
totalPrice Ano Celková cena objednávky
delivery Ne Identifikátor dopravy
payment Ne Identifikátor platby

Order Item

  Povinný Popis
productUid Ano Unikátní identifikátor produktu. UID musí odpovídat identifikátoru produktu, který je vystavován ve feedu katalogu.
amount Ano Množství zakoupených položek
price Ano Cena za jednu položku
type Ano

Typ zakoupené položky. Platné hodnoty jsou:

  • ACCESSORY – Příslušenství
  • COUPON – Slevová poukázka
  • GIFT – Dárek
  • PRODUCT – Produkt
  • SERVICE – Služba

Customer

  Povinný Popis
uid Ano Unikátní identifikátor zákazníka
email Ano Emailová adresa zákazníka
firstName Ne Křestní jméno zákazníka
lastName Ne Příjmení zákazníka
company Ne Společnost
address Ne Adresa zákazníka
phone Ne Telefon zákazníka

Příklad

<?xml version="1.0" encoding="UTF-8"?>
<orders>
	<order>
		<uid>ab351ecd</uid>
		<created>2014-01-01T10:00:00.000Z</created>
		<state>COMPLETED</state>
		<customer>
			<uid>2608a540</uid>
			<email>test@etnetera.cz</email>
			<firstName>John</firstName>
			<lastName>Doe</lastName>
			<company>Etnetera a.s.</company>
			<address>Milady Horákové 108, Praha 6 16000</address>
			<phone>602603000</phone>
		</customer>
		<items>
			<item>
				<productUid>0b8ef698</productUid>
				<amount>1</amount>
				<price>999</price>
				<type>PRODUCT</type>
			</item>
		</items>
		<totalPrice>1099</totalPrice>
		<delivery>PICK_UP</delivery>
		<payment>CREDIT</payment>
	</order>
	<order>
		<uid>ab351ecd</uid>
		<created>2014-01-01T10:00:00.000Z</created>
		<state>COMPLETED</state>
		<customer>
			<uid>2608a540</uid>
			<email>test@etnetera.cz</email>
		</customer>
		<items>
			<item>
				<productUid>0b8ef698</productUid>
				<amount>1</amount>
				<price>1399</price>
				<type>SERVICE</type>
			</item>
		</items>
		<totalPrice>1399</totalPrice>
	</order>
</orders>