Data Feed (źródło danych)

This post is also available in: Czeski Angielski

Do prawidłowego działania, Samba.ai wymaga integracji z następującymi źródłami danych (feedami produktowymi):

Jeśli stworzyłeś swój sklep internetowy w oparciu na jednej ze wspieranych platform e-commerce, nie musisz przejmować się integracją danych. Po prostu postępuj zgodnie z instrukcją krok po kroku, którą znajdziesz tutaj. Jeśli używasz innej, nieobsługiwanej jeszcze przez Sambę platformy, to nie martw się, bo obecnie pracujemy nad integracją innych popularnych systemów sklepowych i jest bardzo prawdopodobne, że już niebawem będzie dostępna. Do czasu ich ukończenia, postępuj zgodnie z przewodnikiem krok po kroku, który znajdziesz poniżej.

Linki (publicznie dostępne lub zawierające dane dostępowe w formacie https://username:password@twojsklep.com/feedname.xml) do tych kanałów można wstawić w sekcji Ustawienia Konta -> Ustawienia Integracji -> Integracja Danych -> Ustawienia Połączenia panelu Samba.

Podstawowe zabezpieczenie autoryzacji z HTTPS

Dane uwierzytelniające dostęp, uzupełnione przy użyciu podstawowego uwierzytelniania (przykładowo w formacie https://username:password@twojsklep.com/feed.xml) są w pełni zabezpieczone podczas połączenia, dzięki protokołowi HTTPS, więc nie musisz się martwić o ich przechwycenie przez osobę trzecią. Żądanie HTTP jest wysyłane na adres IP odpowiadający domenie i zawiera tylko fragment po pierwszym ukośniku po domenie (czyli /feed.xml), a więc przetwarzany adres URL w żądaniu nie zawiera podstawowych danych uwierzytelniających. Dzieje się tak dzięki temu, że podstawowe dane autentykacyjne są przekazywane na poziomie żądania nagłówka. Jednak bez certyfikatu HTTPS, całe żądanie, w tym nagłówki, przekazują się niezaszyfrowane, więc zdecydowanie zaleca się, aby domena była zabezpieczona tym protokołem.

Aby zapisać zmiany, kliknij Zapisz Konfigurację.

Po wypełnieniu wszystkich danych, naciśnij przycisk Odśwież, a Samba natychmiast pobierze kanały zgodnie z Twoimi ustawieniami. Zwykle zobaczysz dane wyjściowe z naszej walidacji w ciągu kilku minut, więc możesz w tym czasie poprawić ewentualne błędy.

Regularne aktualizacje:

  • Źródło danych (data feed) jest domyślnie aktualizowany raz dziennie.
  • Źródło danych jest zawsze aktualizowane jako całość, dlatego jeśli aktualizacja z jakiegokolwiek powodu nie powiedzie się, nawet częściowo przetworzone dane z jednego kanału nie będą zaktualizowane.
  • Samba automatycznie próbuje ponownie zaktualizować dane w stopniowo coraz dłuższych odstępach czasu, aż do następnej zaplanowanej aktualizacji.

Jeśli nie chcesz korzystać z jednego z feedów, a potrzebujesz zaktualizować dane, użyj tzw. Pustych feedów.

Właściwości Data Feed

  • format XML
  • Kodowanie UTF-8LE
  • NIE używaj znaków sterujących unicode (z wyjątkiem znaków CR i LF))
Znaki specjalne

Znaki specjalne  &, >, <, \, ", ' muszą być zastępowane zgodnie z oficjalną specyfikacją formatu XML lub należy zastosować tzw. sekcję CDATA. Na przykład zamiast:

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

użyj w zastępstwie:

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

lub użyj sekcji CDATA tak, jak poniżej:

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

Ważnym jest, aby zachować integralność referencyjną pomiędzy feedami, tj. spójność ID w w różnych kanałach. Upewnij się, że ID produktu jest takie samo w feedzie produktu i feedzie zamówienia. To samo dotyczy również ID klienta w feedzie zamówień i feedzie klientów.

Najczęstsze błędy

Zapoznaj się z najczęstszymi problemami, które możesz napotkać podczas integracji Twojego sklepu z Sambą. Link do artykułu znajduje się tutaj.

Feed Produktowy (Products Feed)

Ten feed zawiera bazę danych wszystkich Twoich produktów, które oferujesz w swoim sklepie internetowym. Aby uzyskać najlepsze rezultaty, zalecamy uzupełnienie w nim jak największej liczby opcjonalnych parametrów. Dzięki temu Samba jest w stanie rozpoznać parametry produktów (typ, marka, kategoria, kategoria cenowa, kolor, rozmiar, itd.), a następnie przedstawić ten produkt odpowiedniemu klientowi. Samba pracuje również na informacjach o stanie magazynowym i ofertach specjalnych, więc nie zaoferuje produktu, którego nie ma w magazynie, a zamiast niego wyświetli produkt, który jest w sprzedaży.

Wspierane parametry

NameTypeRequiredDescription
PRODUCT_IDStringyesproduct ID
TITLEStringyesproduct name
PRICEFloat, >=0yesselling price (tax included, without shipping and handling)
URLStringyesproduct URL
IMAGEStringnoproduct picture URL (approx 300x300 px)
DESCRIPTIONStringnodetail description of the product (without HTML tags)
BRANDStringnoproduct brand
STOCKInteger, >=0, default:1nonumber of pieces in stock
PRICE_BEFORE_DISCOUNTFloat, >0, PRICE_BEFORE_DISCOUNT > PRICEnoprice before discount (tax included)
PRICE_BUYFloat, >0nocost price of the product (for calculating profit margin)
PRICES[NAME, VALUE]nospecial prices for different customer groups, see PRICE_CATEGORY in the customer feed
CATEGORYTEXTStringnocategories that include the product, seperated by "|"
PRODUCT_LINEStringnoproduct line
VARIANTProducts listnosee product variants below
SHOWBoolean, default: TRUEnocan we show this product?
PARAMETER[NAME, VALUE]noOther parameters (NAME does not have to be unique, please see example below)

W przypadku wielokrotnego wystąpienia parametru o tej samej wartości NAME, przetwarzane są wszystkie odpowiednie wartości VALUE. W ramach filtrowania jest możliwe wyszukiwanie wśród wszystkich wartości.

Warianty Produktów

Każdy produkt może mieć nieograniczoną liczbę różnych wariantów, czyli takich samych produktów o nieco innych parametrach, np. kolorze lub rozmiarze. Warianty te, zgrupowane są w jeden produkt nadrzędny, tzw. produkt główny (master). Takie oznaczenie gwarantuje, że różne warianty tego samego produktu nie są polecane klientowi w tym samym przekazie reklamowym.

  • Produkt wymieniony jako produkt główny, jest zazwyczaj jednym z wariantów lub może być katalogiem do wariantów (w zależności od implementacji Twojego sklepu internetowego)
  • Kryteria wyboru
    • Produkt główny musi posiadać poniższe wartości:
      • PRICE > 0
      • STOCK > 0
      • IMAGE
      • URL
    • Produkt z parametrem PRODUCT_ID, który nie jest zagnieżdżony w znaczniku VARIANT jest automatycznie traktowany jako produkt główny
      • Jeśli jednak taki produkt nie spełnia powyższych kryteriów, to pierwszy wariant spełniający kryteria jest automatycznie oznaczony jako produkt główny. 
      • Jeśli żaden wariant nie spełnia powyższych kryteriów, to jako produkt główny wybierany jest pierwotnie określony produkt, czyli produkt nie wymieniony w znaczniku VARIANT.
  • Jeśli brakuje atrybutu w wariancie, automatycznie używany jest ten określony w produkcie głównym. Dotyczy to również atrybutu PRICES tak, jak poniżej.

Zaokrąglanie cen

Ceny w newsletterze są uzupełniane cenami znajdującymi się w feedzie produktowym. Jeśli jednak niektóre ceny masz ustawione na takie, jak na przykład 419,72 zł, możesz ustawić w Sambie, aby zaokrąglała tę cenę do wybranej przez Ciebie liczby miejsc po przecinku.

Aby znaleźć tę opcję, otwórz Ustawienia -> Integracja -> Integracja Danych -> Ustawienia Połączeń, gdzie możesz wybrać czy i do ilu miejsc po przecinku chcesz zaokrąglić swoje ceny. 

Przykładowo użycie opcji „Liczba miejsc po przecinku: 0” sprawi, że ceny zostaną zaokrąglone do liczb całkowitych. W tym przypadku, cena 419,72 zł zostanie zaokrąglona do 420 zł.

Grupy klientów z różnymi cenami

Używając atrybutu PRICES , możesz definiować różne ceny sprzedaży przed rabatem dla klientów różnego typu. Może to być przydatne na przykład wtedy, gdy używasz różnych programów rabatowych lub pracujesz z klientami “VIP”, gośćmi, itd.

Zasada działania:

  • PRICE_CATEGORY dotyczy tylko produktów personalizowanych w mailingu. Obecnie nie dotyczy personalizacji w rekomendacjach na stronie – zwracana jest tam jedynie cena domyślna (taka sama dla wszystkich klientów).
  • Dla grup można przedefiniować:
    • PRICE – cena sprzedaży
    • PRICE_BEFORE_DISCOUNT – cena przed rabatem
  • Każdemu klientowi, dla którego znaleziono dopasowanie pomiędzy PRICE_CATEGORY w feedzie klienta i PRICES>CATEGORY>NAME w feedzie produktu, ta specjalna cena grupowa jest automatycznie wyświetlana w rekomendacji produktu.
  • Jeżeli dla konkretnego klienta nie jest wybrana żadna kategoria cenowa z PRICE_CATEGORY lub jest wybrana taka, która nie jest wymieniona dla aktualnie polecanego produktu, dla tego klienta będzie używana domyślna cena tego produktu.
  • W całym feedzie dozwolone jest maksymalnie 1000 grup o różnych cenach.
    • Produkty przekraczające ten limit nie będą przetwarzane.
    • Klienci przekraczający ten limit są przetwarzani, ale specjalne ceny grupowe nie będą stosowane.

Przykład Feedu Produktowego (Product Feed)

<?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>

 

Feed Klientów (Customer Feed)

Feed Klientów powinien zawierać całą bazę danych Twoich klientów. Samba może dostosować swoją personalizację na podstawie innych metaparametrów, takich jak płeć czy data rejestracji. 

Samba potrafi wyróżnić 3 poziomy subskrypcji newslettera:

  • every day – codziennie
  • special occasions – specjalne okazje
  • never – nigdy

Samba celuje tylko w tych klientów, którzy naprawdę chcą otrzymywać newslettery. 

Aby dowiedzieć się, jak liczba klientów wpływa na plan płatności, zobacz ten artykuł.

Wspierane parametry

NameTypeRequiredDescription
CUSTOMER_IDStringyesCustomer ID
NEWSLETTER_FREQUENCYEnum: every day | special occasions | neveryesSubscription frequency (never = unsubscribed)
NLF_TIMEDatetime (as string)noDatetime in the YYYY-MM-DDThh:mm:ss.sTZD format (more info)
Time of the customer's subscription change
EMAILStringnoA valid email address
REGISTRATIONDate & time (as a String)noDate and time of registration in the following format: YYYY-MM-DDThh:mm:ss.sTZD (more info), default: "1970-01-01"
FIRST_NAMEStringnoFirst name
LAST_NAMEStringnoLast name
ZIP_CODEStringnoZIP code
PHONEStringnoPhone number with the Incl. plus sign and country code (e.g. "+420xxxxxxxxx" for Czech Republic, or +11234567890 for USA)
SMS_FREQUENCYEnum: every day | special occasions | nevernoSMS subscription frequency (never = unsubscribed), default: "never"
DATA_PERMISSIONEnum: full | do_not_personalize | anonymized_onlynodefault: "full"
PRICE_CATEGORYStringnocustomer group for determining special product prices - see PRICES in products feed
PARAMETERS[NAME, VALUE]noOther parameters (NAME does not have to be unique, please see example below)

W przypadku wielokrotnego wystąpienia parametru o tej samej wartości NAME, przetwarzane są wszystkie odpowiednie wartości VALUE. W ramach filtrowania jest możliwe wyszukiwanie wśród wszystkich wartości. W przypadku użycia w szablonie poprzez wstawienie zmiennej dynamicznej, jedna z wartości jest używana losowo.

Atrybut <NLF_TIME>

Ten atrybut daje Sambie informację o dokładnym czasie, kiedy klient zmienił status subskrypcji. Jeśli wypisany klient zapisze się ponownie, Samba będzie wiedziałą, która akcja powinna być priorytetowa. Jeśli atrybut ten nie jest obecny, priorytetem jest informacja z Samby – wypisanie się z subskrypcji poprzez link w stopce i/lub poprzez Administrację bazą danych.

Atrybut <DATA_PERMISSION>

Klienci posiadający wartość DATA_PERMISSION = anonymized_only nie będą targetowani przez żaden kanał. System wykorzystuje jedynie ich zanonimizowane dane (wzorce zachowań) w celu trenowania naszych algorytmów. Więcej informacji znajdziesz tutaj.

Przykład Feeda Klientów (Customer Feed)

<?xml version="1.0" encoding="utf-8"?>
<CUSTOMERS>
     <CUSTOMER>
          <CUSTOMER_ID>D45S8741545SD</CUSTOMER_ID>
          <EMAIL>jan.kowalski@adres.pl</EMAIL>
          <REGISTRATION>2014-12-31T03:53:43.962Z</REGISTRATION>
          <FIRST_NAME>Jan</FIRST_NAME>
          <LAST_NAME>Kowalski</LAST_NAME>
          <NEWSLETTER_FREQUENCY>every day</NEWSLETTER_FREQUENCY>
          <NLF_TIME>2014-12-31T03:56:43.962Z</NLF_TIME>
          <ZIP_CODE>50-113</ZIP_CODE>
          <PRICE_CATEGORY>vip</PRICE_CATEGORY>
          <PARAMETERS>
               <PARAMETER>
                    <NAME>Punkty bonusowe</NAME>
                    <VALUE>100</VALUE>
               </PARAMETER>
               <PARAMETER>
                    <NAME>Płeć</NAME>
                    <VALUE>mężczyzna</VALUE>
               </PARAMETER>
          </PARAMETERS>
     </CUSTOMER>
</CUSTOMERS>

Przyrostowe zasilanie danymi (Incremental Data Feed)

Samba obsługuje tzw. przyrostowe zasilanie danymi, co oznacza, że baza klientów będzie zasilana wyłącznie tymi klientami, którzy zostali ostatnio utworzeni lub zmienieni, zamiast codziennego zaciągania całej bazy klientów. Zmniejsza to obciążenie serwerów i wystarczy, że jedynie wygenerujesz kompletną bazę klientów dla początkowej aktualizacji, a później baza będzie się aktualizować każdego dnia wyłącznie o nowych klientów oraz o tych, u których nastąpiła zmiana. 

Procedura:

  1. Zainicjuj import danych historycznych
    1. Ustaw kanał klientów na typ Ukończone.
    2. Podaj adres URL kompletnego feedu.
    3. Wykonaj aktualizację danych w Sambie.
  2. Zasilanie przyrostowe:
    1. Ustaw kanał klientów na typ Przyrostowo.
    2. Wpisz adres URL przyrostowego feedu.
    3. Wykonaj aktualizację danych w Sambie.

Sposób działania całego procesu polega na tym, że po przełączeniu typu na Przyrostowo, Samba automatycznie utrzymuje historię klientów zebraną do tej pory i agreguje każdy nowy przyrost tej historii używając metody upsert na CUSTOMER_ID. Oznacza to, że:

  • w przyroście pojawia się nowy CUSTOMER_ID – rekord jest przetwarzany i dodawany do zgromadzonej bazy danych w Sambie.
  • w przyroście pojawia się wcześniej przetwarzany CUSTOMER_ID – istniejący rekord klienta jest odrzucany i dla klienta przetwarzane są tylko parametry (i pozycje) określone w przyroście.

Dopóki nie zmienisz ponownie ustawienia na typ Ukończone, Samba przechowuje tę zgromadzoną historię w swojej bazie danych.

Typ przyrostu

Samba rozróżnia następujące typy przyrostów w oparciu o sposób dynamizacji adresu URL:

  • Statyczny URL:
    • Używaj, gdy zawsze generujesz na jednym konkretnym i niezmiennym adresie URL wszystkich klientów, którzy zmienili się w wybranym okresie (długość okresu zależy od Ciebie, zwykle jest to 7 dni).
    • Przykład: https://samba.ai/export/customers/customers_increment.xml
  • Konkretna data:
    • Użyj, gdy okresowo generujesz nowy plik dla określonego okresu czasu – na przykład generujesz nowy przyrost dzienny każdego dnia.
    • Przykład:
      https://samba.ai/export/customers/customers_increment_{date}.xml
  • Data od – do (from/to):
    • Używaj, gdy masz po swojej stronie usługę gotową do zwrotu eksportu zamówień według atrybutów from/to.
    • Samba automatycznie wybiera from jako datę ostatniego udanego uruchomienia, a to jest wybierane jako “dzisiaj”. Zapewnia to następne uruchomienie, aby ponownie załadować dane graniczne, które mogły być niekompletne w momencie przetwarzania.  
    • Przykład:
      https://samba.ai/export/customers/customers_increment_{from}_{to}.xml

Używając opcji “Ostatni przyrost dostępny X dni temu”, można skonfigurować Sambę tak, aby np. pobierała przyrost z 1-dniowym opóźnieniem (np. 27 marca Samba pobierze przyrost z datą 26 marca, a nie nowszy). Może to zapobiec niepowodzeniu całej aktualizacji danych z powodu niedostępności danych po stronie użytkownika.

Logika przyrostu

Zalecamy ustawienie logiki tak, aby w przyroście pojawili się wszyscy klienci, którzy przeszli zmianę w danym okresie. Jeśli ustawisz logikę tylko na np. datę rejestracji klienta, która jest statyczna, to w Sambie zabraknie zaktualizowanych danych klienta.

 

Feed zamówień (Order Feed)

Feed zamówień (order feed) powinien w idealnym przypadku zawierać historię zamówień, które miały miejsce w Twoim sklepie internetowym (zalecamy, aby historia miała co najmniej 2 lata, ale preferowana jest cała historia lub możesz również użyć przyrostów, jak wyjaśniono poniżej). Samba wykorzystuje ten feed do analizowania wzorców zakupowych Twoich klientów, które są następnie wykorzystywane do personalizacji. Wszystkie produkty w tym pliku danych muszą znajdować się w feedzie produktowym, lub zostaną oznaczone jako „Nieprawidłowe zamówienia” i system Samby je zignoruje.

Jeśli nie podasz ceny produktu w zamówieniu, zamiast niej będzie użyta cena produktu z feeda produktowego.

Samba aktualnie obsługuje trzy typy statusów:

  • finished (ukończone) – zrealizowane zamówienia, w których użytkownik opłacił lub otrzymał zamawiane towary. Jest to jedyny status, z którym Samba faktycznie pracuje.
  • created (utworzone) – zamówienie zostało utworzone i oczekuje na realizację (zapłatę, dostawę, etc.)
  • canceled (anulowane) – anulowane lub usunięte zamówienia (przez klienta lub sklep).

Jeśli nie uzupełnisz statusu zamówienia, Samba zobaczy zamówienie jako zrealizowane. Jeżeli zamówienie jest w stanie ukończonym, a atrybut FINISHED_ON nie występuje jako data/godzina zakończenia zamówienia, to przyjmowana jest wartość daty w elemencie CREATED_ON .

Jeśli pozwalasz klientowi na dokonywanie zamówień bez rejestracji, użyj elementu EMAIL zamiast CUSTOMER_ID oraz jeśli to możliwe, także PHONE i ZIP_CODE . Samba utworzy wtedy wirtualnych klientów, których możesz następnie użyć do targetowania podczas tworzenia kampanii. 

Szczegóły: Jeśli CUSTOMER_ID jest zdefiniowany jako nieznany (lub w ogóle nie jest określony) w konkretnym zamówieniu i istnieje klient (w customer feedzie) z takim samym adresem EMAIL , jaki został użyty w tym zamówieniu, to zamówienie to, jest automatycznie przypisywane do tego klienta na podstawie elementu EMAIL . Jeśli jednak w pliku danych klienta nie ma takiego adresu EMAIL , wartość adresu EMAIL zostanie tymczasowo użyta jako nowy CUSTOMER_ID , aby można było przetworzyć to zamówienie. Zamówienia bez prawidłowego adresu EMAIL oraz CUSTOMER_ID nie będą w ogóle przetwarzane.

Na podstawie warunków klienta możesz wybrać następującą opcję w ustawieniach połączenia dla tych klientów:

Czy mam prawo, aby dodać do listy subskrypcji niezarejestrowanych klientów, którzy złożyli zamówienie?

RODO stanowi, że masz do tego prawo, ale musisz upewnić się, że jesteś do tego uprawniony (jest to nazywane “Uzasadnionym interesem”). Na terenie Unii Europejskiej jednak, powinieneś mieć dodatkową zgodę klienta na przetwarzanie jego danych w celu otrzymywania komunikatów marketingowych. Upewnij się również, że w stopce newslettera znajduje się poprawnie działający link “anuluj subskrypcję”.

Obsługiwane parametry

NameTypeRequiredDescription
ORDER_IDStringyesOrder ID
CUSTOMER_IDStringnoCustomer ID
CREATED_ONDate & time (as a String)yesDate and time in the following format: YYYY-MM-DDThh:mm:ss.sTZD (more info).
ITEMSyesProducts included in this order
FINISHED_ONDate &n time (as a String)noDate and time in the following format: YYYY-MM-DDThh:mm:ss.sTZD (more info). Please don't use this parameter or leave it blank if the order wasn't finished.
STATUSStringnoState of the order: "created", "finished", or "canceled".
EMAILStringnoA valid email address
PHONEStringnoIncl. plus sign and country code (e.g. "+420xxxxxxxxx" for Czech Republic)
ZIP_CODEStringnoDelivery ZIP code
COUNTRY_CODEStringnoInternational identification code of the country (e.g. "CZ" or "US")

ITEMS

Każde zamówienie musi zawierać wszystkie produkty z tego zamówienia. Cena produktu określa tutaj cenę sprzedaży, wartość do zapłaty przez klienta (bez wysyłki i obsługi, włączając VAT).

NameTypeRequiredDescription
PRODUCT_IDStringyesID of the product or its variant
AMOUNTNumber (integer, >0)noQuantity of the product (default: 1)
PRICENumber (>=0)noSubtotal of all of the pieces of the product, tax included, without shipping and handling.
Przetwarzanie PRICE w zamówieniu

Jeżeli ITEM w zamówieniu:

  • nie zawiera parametru PRICE, lub
  • zawiera parametr PRICE z błędem (np. jest pusty, nie jest liczbą, jest liczbą ujemną)

to Samba spróbuje znaleźć jego aktualną cenę na podstawie PRODUCT_ID w kanale produktu. Jeśli produkt nie istnieje w Product Feedzie, to pozycja zamówienia nie zostanie przetworzona.

Jeśli pozycja ma zdefiniowaną cenę (PRICE) więcej niż raz w zamówieniu, to pozycja w ogóle nie zostanie przetworzona.

Zamówienie bez zwalidowanych pozycji nie zostanie zrealizowane.

W metodach analitycznych Samba, brane są pod uwagę tylko zrealizowane zamówienia i pozycje z dodatnimi cenami.

Przykład Feeda Zamówień (Orders Feed)

<?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>50-113</ZIP_CODE>
             <COUNTRY_CODE>PL</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.kowalski@adres.pl</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>50-113</ZIP_CODE>
             <COUNTRY_CODE>PL</COUNTRY_CODE>
             <ITEMS>
                    <ITEM>
                          <PRODUCT_ID>DAS656</PRODUCT_ID>
                          <AMOUNT>6</AMOUNT>
                          <PRICE>36</PRICE>
                    </ITEM>
              </ITEMS>
         </ORDER>

 </ORDERS>

Przyrostowe zasilanie danymi zamówień (Incremental Orders Feed)

Samba obsługuje tzw. przyrostowy feed danych, co oznacza, że feed ten zawiera tylko te zlecenia, które zostały ostatnio utworzone lub zmienione. Zmniejsza to obciążenie serwerów, gdzie wystarczy wygenerować pełną historię dla początkowej aktualizacji i niewielki przyrost z każdego następnego dnia.

Procedura:

  1. Wstępny import historii
    1. Ustaw typ feedu na Ukończone.
    2. Wstaw adres URL kompletnego feedu.
    3. Wykonaj aktualizację danych w Sambie.
  2. Przetwarzanie przyrostowe
    1. Ustaw typ feedu na Przyrostowo.
    2. Wstaw adres URL feedu przyrostowego.
    3. Wykonaj aktualizację danych w Sambie.

Sposób działania całego procesu polega na tym, że po przełączeniu typu feedu na przyrostowy (inkrementalny), Samba automatycznie utrzymuje zebraną do tej pory historię zamówień i agreguje każdy nowy przyrost do tej historii, za pomocą metody upsert na ORDER_ID. Oznacza to, że:

  • w przyroście pojawia się nowy ORDER_ID – rekord jest przetwarzany i dodawany do zgromadzonej bazy danych w Sambie
  • w przyroście pojawia się poprzednio przetwarzany ORDER_ID – istniejący rekord zamówienia jest odrzucany i dla zamówienia przetwarzane są tylko parametry (i pozycje) określone w przyroście. 

Dopóki nie przełączysz ustawienia z powrotem na typ Ukończony, Samba przechowuje tę zgromadzoną historię w swojej bazie danych.

Typ przyrostu

Samba rozróżnia następujące typy przyrostów w oparciu o sposób dynamizacji adresu URL:

  • Statyczny URL
    • Użyj gdy zawsze generujesz na jednym konkretnym i niezmiennym URL wszystkie zamówienia, które zmieniły się w wybranym okresie (długość okresu zależy od Ciebie, zwykle jest to 7 dni).
    • Przykład: https://samba.ai/export/orders/orders_increment.xml
  • Określona data
    • Użyj gdy okresowo generujesz nowy plik dla określonego okresu czasu – na przykład generujesz nowy przyrost dzienny codziennie
    • Przykład:  https://samba.ai/export/orders/orders_increment_{date}.xml
  • Data Od – Do
    • Użyj gdy masz po swojej stronie usługę gotową do zwrócenia eksportu zamówień według atrybutów from/to.
    • Samba automatycznie wybiera from jako datę ostatniego udanego uruchomienia, a to jest oznaczone jako “dzisiaj”. To zapewnia, że następne uruchomienie ponownie załaduje dane graniczne, które mogły być niekompletne w trakcie przetwarzania.
    • Przykład: https://samba.ai/export/orders/orders_increment_{from}_{to}.xml

Używając opcji „Ostatni przyrost dostępny X dni temu” można ustawić Sambę, aby np. pobierała przyrost z 1-dniowym opóźnieniem (np. 27 marca Samba pobierze przyrost z datą 26 marca, a nie nowszy). Może to zapobiec niepowodzeniom pełnej aktualizacji danych z powodu niedostępności danych po stronie Twojego sklepu.

Logika przyrostu

Zaleca się ustawienie logiki w taki sposób, aby w przyroście pojawiały się wszystkie zamówienia, które uległy zmianie w danym okresie. Jeśli na przykład ustawisz logikę tylko na datę utworzenia zamówienia, to możesz w Sambie pominąć informację o anulowanych zamówieniach i zwrotach.

Przetworzone dane

Przetwarzane i gromadzone w historii są tylko te zamówienia z przyrostu, które są w danym momencie walidowane – oznacza to, że wszystkie wymagane atrybuty muszą być poprawne. Następnie dla danej aktualizacji danych, Samba przetwarza tylko te zamówienia, które są w pełni zdeterminowane pod względem istnienia klienta w feedzie klientów (customer feed) oraz istnienia produktu w feedzie produktowym (product feed).

Klient w zamówieniu

Jeśli w konkretnym zamówieniu nieznany jest CUSTOMER_ID (lub nie jest określony wcale) i istnieje klient (w feedzie klientów) z tym samym adresem EMAIL, który został użyty w tym zamówieniu, to zamówienie to, zostaje automatycznie przypisane do tego klienta na podstawie elementu EMAIL.

Jeśli jednak w karcie klienta nie ma takiego adresu EMAIL, to wartość w EMAIL zostanie tymczasowo wykorzystana do wygenerowania nowego wirtualnego klienta o ID równym EMAIL i to konkretne zamówienie zostanie włączone do zgromadzonej historii. Idąc dalej, to zamówienie jest przetwarzane tylko tak długo, jak zamówienie jest częścią przyrostu. Później, w dowolnym czasie, klient nie jest już generowany, a zatem zamówienie nie jest przetwarzane, do czasu, aż klient o CUSTOMER_ID równym wartości EMAIL nie pojawi się ponownie w feedzie klientów (customer feed).

Przyrost Feeda Klientów (Incremental Customers Feed)

Jeżeli jednak zastosujesz również przyrostowy typ feeda klientów, to nawet ci wirtualni klienci nigdy nie są traceni i są stale generowani, aby ich zamówienia mogły być przetwarzane przez Sambę.

Jeśli w pewnym momencie zniknie CUSTOMER_ID klienta, wylistowane dla zamówienia, które przeszło proces przyrostu i zostało zapisane w zgromadzonej bazie danych, to zamówienie to, nie zostanie przetworzone i odczytane w Sambie do czasu, aż CUSTOMER_ID nie pojawi się ponownie w feedzie klienta (Customer Feed).

Zamówienia bez ważnego EMAIL i CUSTOMER_ID nie będą w ogóle realizowane. 

Produkt w zamówieniu

W przypadku korzystania z przyrostów, można w skrócie określić, że (analogicznie do klienta w zamówieniu, patrz powyżej) przetwarzane są tylko te pozycje produktów, które zawierają produkty wymienione w feedzie produktowym. W przypadku przyrostowego data feeda, na poniższym przykładzie zademonstrujemy jak to działa:

  • Załóżmy, że nastąpiło jednorazowe pobieranie pełnych danych w obrębie data feeda, a teraz w ramach tego samego konta, używane są przyrosty z dnia na dzień.
  • W przykładzie mamy zamówienie “Ord1” w przyroście (od 1 stycznia), które zawiera produkt o nazwie “Prod1”:
  1. W dniu 1 stycznia pobierany jest przyrostowy feed zamówień (order feed), zawierający zamówienie “Obj1” i jednocześnie tego samego dnia feed produktowy (product feed) zawiera produkt “Prod1”. W tym przypadku zamówienie jest realizowane.
  2. Dzień później (2 stycznia) zamówienia “Ord1” nie ma już w przyroście, a produktu “Prod1” nie ma w feedzie produktowym. Zamówienie nie zostanie w tym przypadku zrealizowane, ale nadal będzie przechowywane w zgromadzonej historii zamówień.
  3. Następnego dnia (3 stycznia) zamówienia “Obj1” nie ma już w przyroście, ale w feedzie produktowym pojawił się produkt “Prod1”. W takim przypadku zamówienie ponownie będzie realizowane. 

Jak możemy zauważyć, momentem decydującym dla Samby jest to, czy produkt znajduje się w feedzie produktowym (product feed) w czasie ostatniego przetworzenia przyrostu – tylko w takim przypadku historia danych jest poprawnie zapisywana do skumulowanej historii zamówień. W kolejnych dniach, zamówienie zostanie ponownie zrealizowane wyłącznie w przypadku, gdy produkt znajduje się aktualnie w feedzie produktowym.

Feed Kategorii (Category Feed)

Feed kategorii powinien zawierać drzewko kategorii używanych w feedzie produktowym (product feed). TITLE w tym feedzie musi odpowiadać CATEGORYTEXT w feedzie produktowym.

Obsługiwane parametry

Tag nameTypeRequiredDescription
TITLEStringyesCategory name
URLStringyesCategory URL
PARAMETER[par1,par2]noOther category parameters

Przykład feedu kategorii

<?xml version="1.0" encoding="utf-8"?>
<CATEGORY>
     <ITEM>
          <TITLE>Kategoria</Title>
          <URL>http://www.mojsklep.pl/sciezka/do/kategorii</URL>
          <ITEM>
               <TITLE>Podkategoria</Title>
               <URL>http://www.mojsklep.pl/sciezka/do/podkategorii</URL>
          </ITEM>
     </ITEM>
     <ITEM>
          <TITLE>Kategoria A</Title>
          <URL>http://www.mojsklep.pl/sciezka/do/kategorii-a</URL>
          <ITEM>
               <TITLE>Podkategoria A</Title>
               <URL>http://www.mojsklep.pl/sciezka/do/podkategorii-a</URL>
               <ITEM>
                    <TITLE>Podkategoria B</Title>
                    <URL>http://www.mojsklep.pl/sciezka/do/kategorii-b</URL>
               </ITEM>
          </ITEM>
     </ITEM>
</CATEGORY>

Używanie pustych feedów

Jeśli nie używasz niektórych feedów, a musisz aktualizować dane w Sambie, możesz po prostu użyć poniższych linków do tzw. pustych kanałów. Może to być szczególnie przydatne, jeśli chcesz tylko zintegrować bazę danych klientów w Sambie i potrzebujesz zsynchronizować niezapisanych klientów i przeliczyć filtry klientów.

Feed type URL
Products https://samba-feed-examples.s3.eu-west-1.amazonaws.com/empty/products_empty.xml
Orders https://samba-feed-examples.s3.eu-west-1.amazonaws.com/empty/orders_empty.xml
Customers https://samba-feed-examples.s3.eu-west-1.amazonaws.com/empty/customers_empty.xml

 

This post is also available in: Czeski Angielski

Zaktualizowano na 12 września, 2022

Czy ten artykuł był pomocny?

Artykuły powiązane