Datové feedy

This post is also available in: Angličtina

Pro správně fungující analýzu dat a chytrou personalizaci potřebuje Samba tyto datové zdroje:

V případě, že váš e-shop byl vytvořen jednou z aktuálně podporovaných platforem, nemusíte vytváření feedů vůbec dále řešit a stačí postupovat dle návodu integrace pro příslušnou platformu. Pokud využíváte jinou platformu, nezoufejte, Samba pracuje na integraci dalších nejpoužívanějších platforem. Do té doby využijte integraci vlastního e-shopu podle specifikace v následujícím textu.

Odkazy (veřejně přístupné, případně obsahující přístupové údaje ve formátu https://username:password@vaseshop.cz/adresafeedu.xml) na tyto feedy následně uvedete v sekci Nastavení – Integrace – Datová integrace – Nastavení připojení v Sambě.

Bezpečnost Basic auth ve spojení s HTTPS

Přístupové údaje vyplněné pomocí basic auth autentizace (tj. ve formátu  https://username:password@vaseshop.cz/adresafeedu.xml) jsou díky protokolu HTTPS plně zabezpečené během přenosu, není proto třeba se obávat odposlechnutí třetí stranou. HTTP požadavek je poslán na IP adresu odpovídající doméně a obsahuje až tu část za prvním lomítkem za doménou, takže zpracovaná URL adresa v požadavku neobsahuje basic auth údaje. Basic auth údaje jsou totiž přenášené na úrovni hlavičky požadavku. Bez použití HTTPS ale celý dotaz včetně hlaviček putuje nezašifrovaný a proto důrazně doporučujeme mít tímto protokolem doménu zabezpečenou.

Pro uložení změn stiskněte Uložit konfiguraci.

Jakmile máte všechny údaje vyplněné, stiskněte Zkontrolovat. Samba ihned stáhne feedy dle vašeho nastavení. Obvykle do několika minut uvidíte také výstup z naší kontroly, abyste mohli nedostatky opravit.

Pravidelná aktualizace:

  • Datové feedy se standardně aktualizují 1x denně.
  • Vždy se aktualizují data jako celek. Proto pokud aktualizace selže z jakéhokoli důvodu, tak nejsou zpracována ani částečně zpracovaná data z jednoho feedu.
  • Samba se automaticky pokouší data aktualizovat znovu v postupně se prodlužujících časových intervalech až do času příští naplánované aktualizace.
  • Pokud nechcete některý z feedů využívat a potřebujete zajistit aktualizaci dat, využijte tzv. Prázdné feedy.

Základní vlastnosti feedů

Obecně vyžadujeme od všech feedů:

  • formát XML 
  • kódování UTF-8LE,
  • nepoužívání unicode řídících znaků (kromě CR a LF).
Pozor na speciální znaky

Znaky &, >, <, \, ", ' musí být dle oficiální specifikace XML formátu tzv. escapované a nebo musí být použita tzv. sekce CDATA. Tj. například namísto

  • <VALUE>A&B <> C&D</Value>

použijte escapování takto:

  • <VALUE>A&amp;B &lt;&gt; C&amp;D</Value>

a nebo CDATA sekci takto:

  • <VALUE><![CDATA[A&B <> C&D]]></Value>

Je důležité zachovat referenční integritu mezi feedy, tj. konzistenci ID. Ujistěte se, že ID produktu je stejné ve feedu produktů i objednávek. Totéž platí pro ID zákazníka ve feedu objednávek a zákazníků.

Nejčastější chyby v datových feedech

Podívejte se jaké nejčastější chyby mohou vzniknout při integraci vašeho eshopu do Samby. Článek naleznete zde.

Produktový feed

Produktový feed obsahuje veškerou databázi produktů, které kdy byly na vašem e-shopu prodávány. Pro plnou funkčnost systému  doporučujeme poskytnout co nejvíce nepovinných parametrů. Díky tomuto feedu rozpoznáme vlastnosti produktů (typ produktu, značka, kategorie, cenová kategorie) a můžeme dynamicky vybírat ty správné produkty pro vaše zákazníky. Dále zjistíme, které produkty můžeme propagovat (díky informaci o naskladnění), můžeme zvýrazňovat zlevněné produkty a dále optimalizovat predikce vzhledem k očekávanému přínosu.

Podporované parametry produktu

Podporovány jsou tyto elementy:

 
V případě vícenásobného výskytu parametru se stejným NAME, jsou zpracovány všechny příslušné VALUE. V rámci filtrování tedy lze prohledávat mezi všemi hodnotami.
 

Každý produkt může mít neomezené množství různých variant, tj. stejných produktů s některými odlišnými parametry např. barvou nebo velikostí. Tyto varianty jsou seskupené do jednoho rodičovského produktu, tzv. master produkt. Toto označení zaručí, že se zákazníkovi nebudou doporučovat v jednom reklamním sdělení např. různé varianty téhož produktu.

  • Produkt uvedený jako master je typicky jednou z variant, nebo se může jednat o tzv. rozcestník k variantám (dle implementace vašeho eshopu)
  • Kritérium výběru
    • Master produkt musí splňovat:
      • PRICE > 0
      • STOCK > 0
      • existuje IMAGE
      • existuje URL
    • Jako master produkt se automaticky zpracovává produkt s PRODUCT_ID, který není zanořený v tagu VARIANT.
      • Jestliže takový produkt ale nesplňuje výše zmíněná kritéria, je automaticky jako master produkt vybrána první varianta, která dané kritérium splňuje.
      • Jestliže žádná varianta kritéria nesplňuje, vybere se jako master produkt ten původně určený, tj. produkt nezanořený v tagu VARIANT.
  • Pokud u varianty chybí nějaký atribut, tak je automaticky použit ten, co je uveden v master produktu. To se týká i atributu PRICES viz dále.

Zaokrouhlování cen

Do newsletteru se propisují ceny uvedené v produktovém feedu. Pokud ale máte některé ceny nastaveny na hodnoty typu 419,72 Kč, je možné Sambě říci, aby takovouto cenu zaokrouhlila na vámi požadovaný počet desetinných míst.

Toto nastavení naleznete v sekci Nastavení – Integrace – Datová integrace – Nastavení připojení, kde si zvolíte zda-li a na kolik desetinných míst chcete ceny zaokrouhlovat.

Například toto nastavení by zaokrouhlovalo ceny na celá čísla. Cena 419,72 Kč by se tedy zaokrouhlila na hodnotu 420 Kč.

Skupiny zákazníků s různými cenami

Pomocí atributu PRICES lze definovat různé prodejní ceny a původní ceny před slevou pro různé zákazníky. To se může hodit např. pokud používáte různé slevové programy nebo pracujete se zákazníky typu „VIP“ a „guest“ apod.

Princip fungování:

  • PRICE_CATEGORY se vztahuje pouze na personalizované produkty v e-mailingu. V současné době se nevztahuje na personalizaci ve webové rekomendaci – zde je vrácena pouze výchozí cena (stejná pro všechny klienty). 
  • Pro skupiny lze předefinovat:
    • PRICE – prodejní cena
    • PRICE_BEFORE_DISCOUNT – cena před slevou
  • Každému zákazníkovi, pro kterého je nalezena shoda mezi PRICE_CATEGORY v zákaznickém feedu a PRICES>CATEGORY>NAME v produktovém feedu, je v rámci produktové rekomendace automaticky zobrazena právě tato speciální skupinová cena.
  • Pokud u zákazníka není uvedena žádná PRICE_CATEGORY, nebo je uvedena taková, která není uvedena u aktuálně doporučovaného produktu, tak je pro daného zákazníka použita výchozí výchozí cena daného produktu.
  • Je povoleno použít maximálně 1000 skupin s rozdílnými cenami napříč celým feedem.
    • Produkty překračující tento limit nebudou zpracovány.
    • Zákazníci přesahující tento limit jsou zpracováni, ale nebudou aplikovány speciální skupinové ceny.

Příklad produktového feedu

<?xml version="1.0" encoding="utf-8"?> 
<PRODUCTS>
     <PRODUCT>
          <PRODUCT_ID>D45S8741545SD</PRODUCT_ID>
          <BRAND>Product Brand</BRAND>
          <TITLE>Product name</TITLE>
          <DESCRIPTION>Detailed description of this product</DESCRIPTION>
          <PRICE>40.1</PRICE>
          <PRICE_BEFORE_DISCOUNT>42.1</PRICE_BEFORE_DISCOUNT>
          <STOCK>60</STOCK>
          <URL>http://www.myeshop.com/path/to/the/product</URL>
          <IMAGE>http://www.myeshop.com/path/to/the/image.jpg</IMAGE>
          <CATEGORYTEXT>Clothes | Men | Trousers</CATEGORYTEXT>
          <PRICES>
               <CATEGORY>
                    <NAME>guest</NAME>
                    <PRICE>41</PRICE>
                    <PRICE_BEFORE_DISCOUNT>42.1</PRICE_BEFORE_DISCOUNT>
               </CATEGORY>
               <CATEGORY>
                    <NAME>vip</NAME>
                    <PRICE>40</PRICE>
                    <PRICE_BEFORE_DISCOUNT>45.1</PRICE_BEFORE_DISCOUNT>
               </CATEGORY>
          </PRICES>
          <PARAMETERS>
               <PARAMETER>
                    <NAME>Color</NAME>
                    <VALUE>White</VALUE>
               </PARAMETER>
          </PARAMETERS>
          <VARIANT>
               <PRODUCT_ID>D45S8741545SD-XXL</PRODUCT_ID>
               <TITLE>Product name XXL</TITLE>
               <DESCRIPTION>Detailed description of this product XXL</DESCRIPTION>
               <PARAMETERS>
                    <PARAMETER>
                         <NAME>Size</NAME>
                         <VALUE>XXL</VALUE>
                    </PARAMETER>
                    <PARAMETER>
                         <NAME>EAN</NAME>
                         <VALUE>467891186861118</VALUE>
                    </PARAMETER>
               </PARAMETERS>
               <PRICE>40.1</PRICE>
               <PRICES>
                    <CATEGORY>
                         <NAME>guest</NAME>
                         <PRICE>41</PRICE>
                         <PRICE_BEFORE_DISCOUNT>42.1</PRICE_BEFORE_DISCOUNT>
                    </CATEGORY>
                    <CATEGORY>
                         <NAME>vip</NAME>
                         <PRICE>40</PRICE>
                         <PRICE_BEFORE_DISCOUNT>45.1</PRICE_BEFORE_DISCOUNT>
                    </CATEGORY>
               </PRICES>
               <STOCK>10</STOCK>
               <IMAGE>http://www.myeshop.com/path/to/the/imageXXL.jpg</IMAGE>
               <URL>http://www.myeshop.com/path/to/the/product?variant=xxl</URL>
          </VARIANT>
          <VARIANT>
               <PRODUCT_ID>D45S8741545SD-L</PRODUCT_ID>
               <TITLE>Product name L</TITLE>
               <DESCRIPTION>Detailed description of this product L</DESCRIPTION>
               <PARAMETERS>
                    <PARAMETER>
                         <NAME>Size</NAME>
                         <VALUE>L</VALUE>
                    </PARAMETER>
                    <PARAMETER>
                         <NAME>EAN</NAME>
                         <VALUE>467891186861118</VALUE>
                    </PARAMETER>
               </PARAMETERS>
               <PRICE>40.1</PRICE>
               <PRICES>
                    <CATEGORY>
                         <NAME>guest</NAME>
                         <PRICE>41</PRICE>
                         <PRICE_BEFORE_DISCOUNT>42.1</PRICE_BEFORE_DISCOUNT>
                    </CATEGORY>
                    <CATEGORY>
                         <NAME>vip</NAME>
                         <PRICE>40</PRICE>
                         <PRICE_BEFORE_DISCOUNT>45.1</PRICE_BEFORE_DISCOUNT>
                    </CATEGORY>
               </PRICES>
               <STOCK>10</STOCK>
               <IMAGE>http://www.myeshop.com/path/to/the/imageL.jpg</IMAGE>
               <URL>http://www.myeshop.com/path/to/the/product?variant=l</URL>
          </VARIANT>
     </PRODUCT>
</PRODUCTS>

Zákaznický feed

Zákaznický feed by měl obsahovat celou databázi vašich zákazníků. Díky tomu Samba může přizpůsobit personalizaci na základě dalších metaparametrů jako je pohlaví nebo doba od registrace.

Samba podporuje 3 úrovně přihlášení k odběru newsletteru:

  • every day – odběr denních novinek,
  • special occasions –  odběr speciálních akcí, např. týdenní, měsíční,
  • never –  uživatel je odhlášen od newsletterů.

Samba cílí pouze na ty zákazníky, kteří si opravdu přejí dostávat newslettery.

Informace ohledně vlivu počtu zákazníků na váš platební plán najdete v tomto článku.

Podporované parametry zákazníka

Název taguTypPovinnýPopis
CUSTOMER_IDStringanozákaznické ID
NEWSLETTER_FREQUENCYEnum: every day | special occasions | neveranoinformace o odběru newsletteru (never = odhlášen)
NLF_TIMEDatetime (as string)nedatetime ve formátu YYYY-MM-DDThh:mm:ss.sTZD (více informací)
Čas změny stupně přihlášení
EMAILStringnevalidní emailová adresa. Jedná se o povinný prvek v případě, že na zákazníka budete odesílat newslettery.
REGISTRATIONDatetime (as string)nedatetime registrace zákazníka ve formátu YYYY-MM-DDThh:mm:ss.sTZD (více informací), výchozí hodnota: "1. 1. 1970"
FIRST_NAMEStringnekřestní jméno
LAST_NAMEStringnepříjmení
ZIP_CODEStringnePSČ
PHONEStringnetelefonní číslo ve formátu odpovídajícím International Telecommunication Union. Mělo by obsahovat symbol plus ("+") jako mezinárodní předponu, kód státu a samotné číslo, například"+420777123456" pro Českou Republiku
SMS_FREQUENCYEnum: every day | special occasions | neverneinformace o odběru novinek formou SMS (never = odhlášen), výchozí hodnota: "never"
DATA_PERMISSIONEnum: full | do_not_personalize | anonymized_onlynevýchozí hodnota: "full"
PRICE_CATEGORYStringneskupina zákazníka pro určení speciální ceny - viz PRICES v produktovém feedu
PARAMETERS[NAME, VALUE]nedalší parametry zákazníka, NAME nemusí být unikátní, vizte příklad

V případě vícenásobného výskytu parametru se stejným NAME, jsou zpracovány všechny příslušné VALUE. V rámci filtrování tedy lze prohledávat mezi všemi hodnotami. Při použití v šabloně pomocí vkládání dynamické proměnné se použije náhodně jedna z hodnot.

Atribut <NLF_TIME>

Tento atribut dává Sambě informaci o přesném čase, kdy zákazník změnil stupeň svého přihlášení. V případě, že se odhlášený zákazník znovu přihlásí k odběru newsletteru, Samba bude vědět, jaká akce je aktuální. Pokud není tento atribut uveden, má vždy přednost informace ze Samby – odhlášení skrze odhlašovací link resp. úpravy provedené v rámci Správy databáze.

Atribut <DATA_PERMISSION>

Zákazníci s hodnotou anonymized_only tohoto atributu nebudou zacíleni žádným kanálem. Samba použije jejich anonymizovaná data (o chování) pouze pro vylepšování našich algoritmů. Více informací naleznete zde.

Příklad zákaznického feedu

<?xml version="1.0" encoding="utf-8"?>
<CUSTOMERS>
     <CUSTOMER>
          <CUSTOMER_ID>D45S8741545SD</CUSTOMER_ID>
          <EMAIL>jan.novak@email.cz</EMAIL>
          <REGISTRATION>2014-12-31T03:53:43.962Z</REGISTRATION>
          <FIRST_NAME>Jan</FIRST_NAME>
          <LAST_NAME>Novák</LAST_NAME>
          <NEWSLETTER_FREQUENCY>every day</NEWSLETTER_FREQUENCY>
          <NLF_TIME>2014-12-31T03:56:43.962Z</NLF_TIME>
          <ZIP_CODE>15000</ZIP_CODE>
          <PRICE_CATEGORY>vip</PRICE_CATEGORY>
          <PARAMETERS>
               <PARAMETER>
                    <NAME>Bonus points</NAME>
                    <VALUE>100</VALUE>
               </PARAMETER>
               <PARAMETER>
                    <NAME>Gender</NAME>
                    <VALUE>male</VALUE>
               </PARAMETER>
          </PARAMETERS>
     </CUSTOMER>
</CUSTOMERS>

Inkrementální zákaznický feed

Samba podporuje tzv. inkrementální datový feed, to znamená, že tento feed obsahuje jen ty zákazníky, u kterých došlo za poslední dobu k nějaké změně. Díky tomu snížíte zátěž serverů, kdy postačí jen pro prvotní update nagenerovat kompletní databázi zákazníků a každý další den už jen zmíněný inkrement.

Postup

  1. Iniciální import zákazníků
    1. Nastavte zákaznický feed na typ Kompletní.
    2. Vložte URL adresu kompletního feedu.
    3. Proveďte datový update v Sambě.
  2. Inkrementální zpracování
    1. Nastavte zákaznický feed na typ Inkrementální.
    2. Vložte URL adresu inkrementálního feedu.
    3. Proveďte datový update v Sambě.

Celý proces funguje tak, že jakmile přepnete typ na Inkrementální, tak Samba automaticky udržuje dosud nasbíranou historii zákazníků a každý nový inkrement do této historie agreguje metodou upsert přes CUSTOMER_ID. To znamená, že

  • v inkrementu se objeví nové CUSTOMER_ID – záznam je zpracován a přidán do akumulované databáze v Sambě
  • v inkrementu se objeví již dříve zpracované CUSTOMER_ID – dosud existující zákaznický záznam je zahozen a zpracují se k danému zákazníkovi jen parametry uvedené v inkrementu

Dokud nepřepnete nastavení zpět na typ Kompletní, tak Samba drží tuto akumulovanou historii ve své databázi.

Typ inkrementu

Samba podle způsobu dynamizace URL rozlišuje tyto typy inkrementů:

  • Statická URL
    • Použijte v případě, kdy na jedné určité a neměnné URL adrese generujete vždy všechny zákazníky, u kterých za nějaké vybrané období (délka období je na vás, typicky 7 dní) došlo ke změně.
    • Např. https://samba.ai/export/customers/customers_increment.xml
  • Specifické datum
    • Použijte v případě, kdy periodicky generujete nový soubor pro určitou časovou periodu – například každý den generujete nový denní inkrement.
    • Např. https://samba.ai/export/customers/customers_increment_{date}.xml
  • Datum Od – Do
    • Použijte v případě, kdy máte na své straně připravenou službu vracet exporty objednávek podle atributů from/to.
    • Samba automaticky volí from jako datum posledního úspěšného běhu, to se volí jako „dnes“. Při dalším běhu tak dochází k opětovnému přenačtení hraničních dat, která mohla být v době zpracování ještě nekompletní.
    • Např. https://samba.ai/export/customers/customers_increment_{from}_{to}.xml

Pomocí volby „Nejnovější inkrement dostupný X dní zpět“ můžete nastavit, aby Samba např. stahovala inkrement s 1 denním zpožděním (např. dne 17.3.2021 bude Samba stahovat nanejvýš inkrement s datem 16.3.2021 a ne novější). Tím lze předejít tomu, aby celý datový update selhával kvůli nedostupnosti dat na vaší straně.

Logika inkrementu

Doporučujeme nastavit logiku takovou, aby se v inkrementu objevili všichni zákazníci, u kterých došlo v dané období k nějaké změně. Pokud nastavíte logiku např. jen na datum registrace zákazníka, které je neměnné, tak budou v Sambě chybět aktualizovaná data zákazníka.

Objednávkový feed

Objednávkový feed by měl ideálně obsahovat historii všech objednávek na vašem eshopu (doporučujeme historii za poslední 2 roky, ale můžete nahrát i celou historii případně v zápětí využít inkrementálního datového feedu – viz níže). Tento feed Sambě slouží k analýze nákupních vzorů vašich zákazníků, které poté dále aplikuje v personalizaci. Veškeré produkty v tomto feedu musí být obsaženy v produktovém feedu, jinak budou nevalidní objednávky systémem automaticky ignorovány.

Pokud neuvedete cenu produktu v objednávce, automaticky se předpokládá aktuální cena produktu v době zpracování.

Samba podporuje 3 stavy objednávek:

  • finished – dokončená objednávka, kdy zákazník zaplatil nebo převzal zboží. Pouze tyto objednávky jsou aktuálně systémem Samba zpracovávány,
  • created – právě vytvořená objednávka čekající na dokončení (provedení platby, doručení atd.),
  • canceled – zrušená nebo smazaná objednávka ze strany zákazníka nebo e-shopu.

Pokud nevyplníte stav objednávky, automaticky se předpokládá jako dokončená (stav finished). Pokud je objednávka ve stavu finished a neexistuje u ní atribut FINISHED_ON, předpokládá se jako datum dokončení hodnota v CREATED_ON.

Při volbě zpracování kompletního objednávkového feedu platí následující: Pokud je vašim zákazníkům umožněno vytvářet objednávky bez registrace, vkládejte do tohoto feedu namísto CUSTOMER_ID element EMAILa pokud máte k dispozici, doplňte i PHONE a ZIP_CODE. Samba z těchto údajů vytvoří zákazníky, na které budete moci ve svých kampaních cílit.

Detailně: Pokud je uvedené u objednávky neznámé CUSTOMER_ID (nebo není uvedeno vůbec) a přitom v zákaznickém feedu existuje zákazník s daným EMAIL, je tato objednávka automaticky přiřazena zákazníkovi s tímto EMAILze zákaznického feedu. Pokud ale neexistuje ani EMAIL v zákaznickém feedu, tak bude hodnota v EMAIL dočasně použita jako nové zákaznické ID, aby mohla být objednávka zpracována. Objednávky bez uvedeného EMAIL i CUSTOMER_ID nebudou zpracovány.

Podle znění vašich obchodních podmínek vyberte volbu v nastavení připojení (u Datové integrace) pro takto vytvořené zákazníky:

Pozor! Dle GDPR máte právo přihlásit k odběru newsletterů neregistrované zákazníky, kteří provedli objednávku (resp. jste držiteli právního titulu „oprávněný zájem„) a manuální souhlas tedy není potřebný. Dávejte si, nicméně, pozor na funkční a aktuální odhlašovací odkaz v patičce newsletteru.

Podporované parametry objednávky

Název taguTypPovinnýPopis
ORDER_IDStringanoID objednávky
CUSTOMER_IDStringneID zákazníka
CREATED_ONDatetime (as String)anodatetime vytvoření objednávky ve formátu YYYY-MM-DDThh:mm:ss.sTZD (více informací).
ITEMSanoprodukty v objednávce
FINISHED_ONDatetime (as String)nedatetime dokončení objednávky ve formátu YYYY-MM-DDThh:mm:ss.sTZD (více informací). Nepoužívejte nebo ponechte prázdné, pokud dosud nebyla objednávka dokončena.
STATUSStringnestav objednávky. Povolené hodnoty: created, finished, canceled.
EMAILStringnevalidní emailová adresa
PHONEStringnetelefonní číslo ve formátu odpovídajícím International Telecommunication Union. Mělo by obsahovat symbol plus ("+") jako mezinárodní předponu, kód státu a samotné číslo, například"+420777123456" pro Českou Republiku
ZIP_CODEStringnePSČ adresy doručení
COUNTRY_CODEStringneMezinárodní identifikace země adresy doručení dle ISO 3166-1 alpha-2, např. "CZ"

ITEMS – položky objednávky

Každá objednávka musí obsahovat všechny produkty z dané zakázky. Cena produktu zde určuje prodejní cenu, kterou zákazník zaplatil (bez dopravného a balného, včetně DPH).

Název taguTypPovinnýPopis
PRODUCT_IDStringanoID produktu nebo produktové varianty
AMOUNTNumber (integer, >0)nepočet kusů objednaného produktu (default: 1)
PRICENumber (>=0)nesumární cena všech kusů daného produktu včetně DPH.
Zpracování PRICE v objednávce

Pokud daná ITEM v objednávce

  • nemá specifikovanou PRICE, nebo
  • má specifikovanou PRICE s chybou (např. je prázdná, není to číslo, je to záporné číslo),

pak se Samba pokusí dohledat aktuální cenu na základě PRODUCT_ID v produktovém feedu. Pokud v produktovém feedu daný produkt neexistuje, tak nebude položka objednávky zpracována.

Pokud má položka v objednávce definovanou PRICE vícekrát, položka nebude vůbec zpracována.

Objednávka bez validních položek nebude zpracována.

Samba pracuje ve svých analytických metodách pouze s dokončenými objednávkami a položkami s kladnými cenami.

Příklad objednávkového feedu

<?xml version="1.0" encoding="utf-8"?>
<ORDERS>
       <ORDER>
             <ORDER_ID>5ds465d</ORDER_ID>
             <CUSTOMER_ID>d4s5a6sd6as</CUSTOMER_ID>
             <CREATED_ON>2014-12-31T03:53:43.962Z</CREATED_ON>
             <FINISHED_ON>2015-01-05T03:53:43.962Z</FINISHED_ON>
             <STATUS>finished</STATUS>
             <ZIP_CODE>15500</ZIP_CODE>
             <COUNTRY_CODE>CZ</COUNTRY_CODE>
             <ITEMS>
                    <ITEM>
                          <PRODUCT_ID>DAS656</PRODUCT_ID>
                          <AMOUNT>6</AMOUNT>
                          <PRICE>36</PRICE>
                    </ITEM>
              </ITEMS>
        </ORDER>
        <ORDER>
             <ORDER_ID>35DS45</ORDER_ID>
             <EMAIL>jan.novak@email.cz</EMAIL>
             <CREATED_ON>2014-12-31T03:53:43.962Z</CREATED_ON>
             <FINISHED_ON>2015-01-05T03:53:43.962Z</FINISHED_ON>
             <STATUS>finished</STATUS>
             <ZIP_CODE>15500</ZIP_CODE>
             <COUNTRY_CODE>CZ</COUNTRY_CODE>
             <ITEMS>
                    <ITEM>
                          <PRODUCT_ID>DAS656</PRODUCT_ID>
                          <AMOUNT>6</AMOUNT>
                          <PRICE>36</PRICE>
                    </ITEM>
              </ITEMS>
         </ORDER>

 </ORDERS>

Inkrementální objednávkový feed

Samba podporuje tzv. inkrementální datový feed, to znamená, že tento feed obsahuje jen ty objednávky, u kterých došlo za poslední dobu k nějaké změně. Díky tomu snížíte zátěž serverů, kdy postačí jen pro prvotní update nagenerovat kompletní historii a každý další den už jen zmíněný inkrement.

Postup

  1. Iniciální import historie
    1. Nastavte objednávkový feed na typ Kompletní.
    2. Vložte URL adresu kompletního feedu.
    3. Proveďte datový update v Sambě.
  2. Inkrementální zpracování
    1. Nastavte objednávkový feed na typ Inkrementální.
    2. Vložte URL adresu inkrementálního feedu.
    3. Proveďte datový update v Sambě.

Celý proces funguje tak, že jakmile přepnete typ na Inkrementální, tak Samba automaticky udržuje dosud nasbíranou historii objednávek a každý nový inkrement do této historie agreguje metodou upsert přes ORDER_ID. To znamená, že

  • v inkrementu se objeví nové ORDER_ID – záznam je zpracován a přidán do akumulované databáze v Sambě
  • v inkrementu se objeví již dříve zpracované ORDER_ID – dosud existující objednávkový záznam je zahozen a zpracují se k dané objednávce jen parametry (a položky) uvedené v inkrementu

Dokud nepřepnete nastavení zpět na typ Kompletní, tak Samba drží tuto akumulovanou historii ve své databázi.

Typ inkrementu

Samba podle způsobu dynamizace URL rozlišuje tyto typy inkrementů:

  • Statická URL
    • Použijte v případě, kdy na jedné určité a neměnné URL adrese generujete vždy všechny objednávky, u kterých za nějaké vybrané období (délka období je na vás, typicky 7 dní) došlo ke změně.
    • Např. https://samba.ai/export/orders/orders_increment.xml
  • Specifické datum
    • Použijte v případě, kdy periodicky generujete nový soubor pro určitou časovou periodu – například každý den generujete nový denní inkrement.
    • Např. https://samba.ai/export/orders/orders_increment_{date}.xml
  • Datum Od – Do
    • Použijte v případě, kdy máte na své straně připravenou službu vracet exporty objednávek podle atributů from/to.
    • Samba automaticky volí from jako datum posledního úspěšného běhu, to se volí jako „dnes“. Při dalším běhu tak dochází k opětovnému přenačtení hraničních dat, která mohla být v době zpracování ještě nekompletní.
    • Např. https://samba.ai/export/orders/orders_increment_{from}_{to}.xml

Pomocí volby „Nejnovější inkrement dostupný X dní zpět“ můžete nastavit, aby Samba např. stahovala inkrement s 1 denním zpožděním (např. dne 17.3.2021 bude Samba stahovat nanejvýš inkrement s datem 16.3.2021 a ne novější). Tím lze předejít tomu, aby celý datový update selhával kvůli nedostupnosti dat na vaší straně.

Logika inkrementu

Doporučujeme nastavit logiku takovou, aby se v inkrementu objevily všechny objednávky, u kterých došlo v dané období k nějaké změně. Pokud nastavíte logiku jen např. na datu vytvoření objednávky, tak mohou chybět v Sambě informace o stornovaných objednávkách a vratkách.

Informace ke zpracování

Zpracovány a akumulovány do historie jsou jen ty objednávky z inkrementu, které jsou v danou chvíli validní – jsou správně všechny povinné atributy. Samba pak pro daný datový update vyčte jen ty objednávky, které jsou plně určené z hlediska existence zákazníka v zákaznickém feedu a existence produktu v produktovém feedu.

Zákazník v objednávce

Pokud je uvedené u objednávky neznámé CUSTOMER_ID (nebo není uvedeno vůbec) a přitom v zákaznickém feedu existuje zákazník s daným EMAIL, je tato objednávka automaticky přiřazena zákazníkovi s tímto EMAILze zákaznického feedu.

Pokud ale neexistuje ani dané EMAIL v zákaznickém feedu, tak bude hodnota v EMAIL dočasně použita pro nagenerování virtuálního zákazníka s ID rovno hodnotě EMAIL a tato objednávka je zahrnuta do akumulované databáze. Zpracována je však jen po dobu, kdy je objednávka součástí inkrementu. Kdykoli později již není zákazník generován a ani objednávka proto není zpracována, dokud se v zákaznickém feedu znovu neobjeví zákazník s CUSTOMER_ID  rovným EMAILa tím může být objednávka z akumulované historie opět zpracována.

Inkrementální zákaznický feed

Pokud ovšem použijete také inkrementální typ zákaznického feedu, tak poté se ani tito virtuální zákazníci nikdy neztratí a jsou neustále generováni tak, aby mohly být jejich objednávky zpracovány.

Jestliže někdy v průběhu času zmizí zákazník CUSTOMER_ID uvedený u objednávky, která prošla inkrementálním zpracování a byla uloženo do akumulované databáze, nebude v Sambě zpracován a vyčten dokud se opět v zákaznickém feedu zmíněné CUSTOMER_ID neobjeví.

Objednávky bez uvedeného EMAILi CUSTOMER_ID nebudou zpracovány.

Produkt v objednávce

Při využití inkrementů lze obecně říci, že (analogicky jako výše pro zákazníka v objednávce) se zpracují pouze ty produktové položky, které obsahují produkty uvedené v produktovém datovém feedu. V případě inkrementálního datového feedu funguje si předveďme fungování na následujícím příkladě:

  • Předpokládejme, že proběhlo jednorázové načtení kompletních dat v rámci datového feedu a nyní jsou v rámci stejného účtu využívány jednodenní inkrementy.
  • V rámci příkladu je v objednávkovém inkrementu obsažena objednávka „Obj1“ z 1. ledna, která obsahuje produkt „Prod1“.
  1. Nejprve se 1. ledna stáhne inkrement objednávkového feedu, který obsahuje objednávku „Obj1“ a zároveň je v produktovém feedu ve stejný den obsažen produkt „Prod1“. Objednávka se v takovém případ zpracuje.
  2. Den poté (tedy 2. ledna) se již objednávka „Obj1“ v inkrementu nenachází a produkt „Prod1“ se nenachází ani v produktovém datovém feedu. Objednávka se v takovém případě nezpracuje, ale bude stále uložena v akumulované historii objednávek.
  3. Následující den (tedy 3. ledna) se objednávka „Obj1“ v inkrementu nadále nenachází, ale produkt „Prod1“ se objevil v produktovém datovém feedu. Objednávka se v tomto případě znovu zpracuje.

Rozhodující tedy pro Sambu je, zda se produkt nachází v produktovém datovém feedu v okamžik posledního zpracování objednávky z inkrementu – v takovém případě totiž dochází k jejímu správnému uložení do akumulované historie objednávek. Následující dny se pak v Sambě objednávka zpracuje v případě, že se daný produkt aktuálně v produktovém datovém feedu nachází.

Feed kategorií

Feed kategorií by měl obsahovat strom kategorií produktů použitých v produktovém feedu. TITLE musí být konzistentní s názvy kategorií CATEGORYTEXT v produktovém feedu. Tento feed je nezbytný, pokud chcete, aby Samba zpracovávala také návštěvy samotných kategorií a bylo možné upravovat jejich personalizaci.

Podporované parametry kategorií

Příklad feedu kategorií

<?xml version="1.0" encoding="utf-8"?>
<CATEGORY>
     <ITEM>
          <TITLE>Nadkategorie</Title>
          <URL>http://www.mujeshop.cz/cesta/k/nadkategorii</URL>
          <ITEM>
               <TITLE>Podkategorie</Title>
               <URL>http://www.mujeshop.cz/cesta/k/podkategorii</URL>
          </ITEM>
     </ITEM>
     <ITEM>
          <TITLE>Nadkategorie A</Title>
          <URL>http://www.mujeshop.cz/cesta/k/nadkategoriia</URL>
          <ITEM>
               <TITLE>Podkategorie A</Title>
               <URL>http://www.mujeshop.cz/cesta/k/podkategoriia</URL>
               <ITEM>
                    <TITLE>Podkategorie B</Title>
                    <URL>http://www.mujeshop.cz/cesta/k/podkategoriib</URL>
               </ITEM>
          </ITEM>
     </ITEM>
</CATEGORY>

Prázdné feedy

Pokud některé z feedů nepoužíváte a potřebujete, aby proběhl v Sambě datový update, můžete jednoduše využít následující odkazy na tzv. prázdné feedy. To se vám může hodit zejména například  v případě, kdy chcete mít v Sambě naintegrovanou jen zákaznickou databázi a potřebujete, aby docházelo k synchronizaci odhlášených zákazníků a přepočítávání zákaznických filtrů.

Typ feedu URL
Produktový https://samba-feed-examples.s3.eu-west-1.amazonaws.com/empty/products_empty.xml
Objednávkový https://samba-feed-examples.s3.eu-west-1.amazonaws.com/empty/orders_empty.xml
Zákaznický https://samba-feed-examples.s3.eu-west-1.amazonaws.com/empty/customers_empty.xml

This post is also available in: Angličtina

Upraveno 5 srpna, 2022

Byl pro vás tento článek užitečný?

Mohlo by vás zajímat