Integrace Customize.cz: skript, feedy a API

Tato stránka shrnuje, co technicky znamená nasazení Customize.cz. Detailní specifikace feedů je v PDF dokumentaci níže. Obecný postup najdete v části Jak to funguje, k nastavení boxů se hodí přehled doporučovacích boxů.

Stáhnout dokumentaci feedů Technická konzultace

Způsoby napojení

JavaScript snippet – viz JavaScript skript.
Google Tag Manager – stejný snippet vložený jako tag typu Custom HTML, spouštěný na stránkách e‑shopu, bez zásahu do šablony.
REST API – Box API a Logger API.
Klikací průvodce – nasazení bez zásahu IT; pozice boxů nastavujeme společně s vámi.

JavaScript skript

Skript tracker.js se načítá asynchronně a příkazy se mu předávají přes frontu _cmq. Pro zobrazení boxu zadáte identifikátor webu, ID boxu, ID elementu, do kterého se box vykreslí, a kontext stránky (ID produktu, kategorie nebo obsah košíku). Po dokončení objednávky se na potvrzovací stránce odešle akce conversion.

Zobrazení boxu

Na místě boxu vložte prázdný element a pod něj příkazy. Tracker načtěte co nejblíže k patičce stránky, před </body>.

<div id="customize_box_detail"></div>
<script>
  var _cmq = _cmq || [];
  _cmq.push(['action', 'show']);
  _cmq.push(['box', 'ID_BOXU']);
  _cmq.push(['web', 'VAS_WEB']);
  _cmq.push(['elementid', 'customize_box_detail']);
  _cmq.push(['userid', '']);
  _cmq.push(['itemid', 'ID_PRODUKTU']);
  _cmq.push(['exceptid', '']);
  _cmq.push(['process']);
</script>

<!-- Customize.cz tracking script -->
<script>
  var cm = document.createElement('script');
  cm.type = 'text/javascript';
  cm.async = true;
  cm.src = '//customize.cz/add/tracker.js';
  var s = document.getElementsByTagName('script')[0];
  s.parentNode.insertBefore(cm, s);
</script>

Konverze po objednávce

Na potvrzovací stránce odešlete číslo objednávky a pro každý produkt jeho ID, jednotkovou cenu s DPH a množství. Řádky itemid, price a quantity opakujte podle počtu produktů v objednávce.

<script>
  var _cmq = _cmq || [];
  _cmq.push(['action', 'conversion']);
  _cmq.push(['web', 'VAS_WEB']);
  _cmq.push(['transaction', 'CISLO_OBJEDNAVKY']);
  _cmq.push(['userid', 'ID_ZAKAZNIKA']);
  _cmq.push(['firstname', 'KRESTNI_JMENO']);
  // pro každý produkt v objednávce:
  _cmq.push(['itemid', 'ID_PRODUKTU']);
  _cmq.push(['price', 'CENA_ZA_KUS_S_DPH']);
  _cmq.push(['quantity', 'MNOZSTVI']);
  _cmq.push(['process']);
</script>
<!-- následuje stejný načítací skript tracker.js jako výše -->

Produktový feed

Produktový XML feed má strukturu Heureka: kořen SHOP a v něm položky SHOPITEM. Feed se importuje pravidelně a z něj se vybírají produkty do boxů.

Pole	Význam
`ITEM_ID`, `PRODUCT`, `URL`, `IMGURL`	Základní údaje o produktu: ID, název, adresa produktu a obrázku.
`PRICE_VAT`	Cena s DPH.
`CAT1` až `CAT4`, `PARAM`	Kategorie a parametry produktu.
`PROFITABILITY`, `ACTION`, `BUYURL`, `DELIVERY_DATE`	Volitelná pole: ziskovost, akce, adresa pro vložení do košíku a dodací lhůta.
`FIELD1` až `FIELD15`	Volitelná doplňková pole; pole 13 až 15 slouží pro slevový kód.

Dokumentace produktového feedu (PDF, 611 KB)

Dostupnostní feed

Volitelný feed, který udržuje aktuální ceny a dostupnost, aby se do boxů nedostalo vyprodané zboží. Obsahuje pole ITEM_ID, PRODUCT, PRICE_VAT, PRICE_VAT_NORMAL a DELIVERY_DATE.

Dokumentace dostupnostního feedu (PDF, 448 KB)

Transakční feed

Volitelný feed s historií objednávek, ze kterého vychází personalizace podle dřívějších nákupů a personalizovaný e‑mailing. Kořen ORDERS obsahuje položky ORDER s poli ORDER_ID, ORDER_CREATED, PRODUCT_ID, PRODUCT_QUANTITY, PRODUCT_PRICE, USER_ID a USER_NAME. Pole USER_ID je hash e‑mailu zákazníka.

Dokumentace transakčního feedu (PDF, 362 KB)

Box API

Box API použijete, když si doporučení vykreslujete sami. Vrací seznam boxů a nastavení a produkty konkrétního boxu. API_KLIC je klíč vašeho e‑shopu.

GET /data/v1.2/API_KLIC/box/list
GET /data/v1.2/API_KLIC/box/get?box=NAZEV_BOXU

Logger API

Logger API přijímá události zobrazení, kliku, vložení do košíku a dokončené objednávky z vašeho vlastního vykreslování. Podporované jsou metody POST i GET.

POST /data/v1.2/API_KLIC/logger/show
POST /data/v1.2/API_KLIC/logger/click
POST /data/v1.2/API_KLIC/logger/buy
POST /data/v1.2/API_KLIC/logger/conversion

Parametr	Význam
`entity`	Typ stránky: `homepage`, `catalog`, `detail`, `basket`, `article` nebo `other`.
`entity_id`	ID produktu, na jehož stránce k události došlo (u `conversion` číslo objednávky).
`place`, `place_id`	Umístění boxu a jedinečné ID konkrétního zobrazení, na které se odkazují následné události.
`recommended_id[]`	ID doporučených produktů (u `click` a `buy` jedno ID).
`url`, `session_id`	Adresa stránky a ID relace návštěvníka, které propojuje události s objednávkou.
`total_price`	Jen u `conversion`: celková cena objednávky.

Úspěšné volání vrací odpověď:

{"status": "ok"}

API pro smazání zákazníka (GDPR)

Na žádost zákazníka o výmaz zavoláte customerDelete. Volání je chráněné autentizací Basic přístupovými údaji vašeho e‑shopu. Identifikátor zákazníka se nevratně anonymizuje. Více o zpracování údajů v Ochraně osobních údajů.

POST /data/v1.2/API_KLIC/customerDelete
Authorization: Basic UZIVATEL:HESLO
customerId=ID_ZAKAZNIKA

Bezpečnost a provoz

Přenos a přístup

Komunikace probíhá přes HTTPS a každý klient má vlastní API klíč.

Domény

CORS je omezený na domény klienta a přesměrování po kliku funguje jen na registrované domény.

Odpovědi na další otázky najdete v časté dotazy, o ceně v části Cena.

Potřebujete poradit s integrací?

Stáhněte si dokumentaci feedů, nebo se spojte s námi a domluvíme technickou konzultaci.

Technická konzultace info@customize.cz