Integracja danych transakcyjnych pomiędzy zewnętrzną platformą a SALESmanago

SALESmanago jest to idealne narzędzie dla branży eCommerce i B2C. Pozwala na automatyzację działań marketingowo – sprzedażowych w sieci, poprzez monitorowanie aktywności kontaktów na stronie www, budowanie profili 360 stopni klientów, personalizację komunikacji z nimi, a także pełną automatyzację prowadzonych kampanii. Dodatkowo zawiera rozbudowane panele analityczne pozwalające m.in. na dokładną analizę źródeł transakcji, wartości transakcji, a także analitykę produktów. Aby móc w pełni wykorzystać potencjał jaki daje SALESmanago, ważne jest poprawne zintegrowanie swojej platformy sklepowej z SALESmango.

WAŻNE: Artykuł, który czytasz przeznaczony jest dla osób, które chcą same zintegrować swój sklep z SALESmanago. Wskazówki, które znajdują się w tym opisie są bardzo ważne. Niezastosowanie się do nich skutkuje tym, że nie będziesz w stanie móc w pełni wykorzystać potencjału jakie daje SALESmanago.

Lista platform eCommerce, dla których posiadamy gotowe integracje >>

 

PODSTAWOWE POJĘCIA

  • e-sklep – zdefiniowany w systemie SALESmanago sklep internetowy,
  • feed produktowy – zbiór informacji o produktach oferowanych przez e-sklep
  • transakcja / zdarzenie zewnętrzne (dane transakcyjne) – informacja o transakcji lub innym zdarzeniu (np. dodanie do koszyka produktu) przesyłana z e-sklepu do systemu SALESmanago (przez interfejs API).

 

CZYM JEST E-SKLEP

E-sklep jest rozumiany jako pojedynczy sklep internetowy (np. strona WWW), który posiada w swojej ofercie produkty. E-sklep w SALESmanago jest to zbiór informacji o sklepie, który posiadasz. W E-sklepie definiujemy takie wartości jak:

  • nazwa
  • ID e-sklepu
  • waluta e-sklepu – czyli w walutę w jakiej przesyłane są wartości dokonywanych zakupów w zdarzeniach zewnętrznych
  • język e-sklepu – czyli w jakim języku przesyłane są informacje o produktach znajdujące się w e-sklepie
  • URL feedu produktowego – czyli dodajemy plik zawierający informacje o produktach zawartych w sklepie

Aby zdefiniować taki sklep w systemie SALESmanago potrzebny jest unikalny identyfikator sklepu – np. nazwa domeny pod jaką działa sklep, a także kompletny i prawidłowy zbiór produktów (tzw. feed produktowy – źródło danych o produktach), w którym znajdują się wszystkie produkty, dostępne w sklepie wraz z unikalnym identyfikatorem produktu i unikalnym adresem URL pod którym znajduje się produkt na stronie WWW. Taki feed produktowy powinien być dostępny dla systemu SALESmanago do pobrania z zdefiniowanego adresu URL w postaci pliku XML.

1 sklep = 1 unikalny identyfikator (ID e-sklepu) = 1 feed produktowy (źródło danych)

WAŻNE: przy tworzeniu swoich sklepów WWW warto zwrócić uwagę, by każdy produkt miał swój unikalny adres URL. To znacznie ułatwia późniejsze analizy związane z identyfikacją ruchu kontaktów na stronie WWW i jest praktyką zalecaną również dla celów SEO.

PRZYKŁAD: jeżeli posiadamy 2 sklepy: www.shop.pl i www.shop.com, a także korzystamy z jednego konta w systemie SALESmanago powinniśmy mieć zdefiniowane 2 e-sklepy dla każdej strony www osobny e-sklep.

 

CZYM JEST UNIKALNY ID E-SKLEPU?

Identyfikator ten służy do połączenia transakcji raportowanych do systemu SALESmanago z e-sklepem i w konsekwencji produktów przesyłanych w transakcji z odpowiednim feedem produktowym . Może on zawierać maksymalnie 36 znaków bez spacji (wartość może zawierać znaki od a do z, cyfry 1-9, /_-.).
W celu prawidłowego przesłania danych przez API identyfikator ten musi być przesyłany zawsze w wartość pola “location” w przesyłanych zdarzeniach zewnętrznych z danego sklepu.

WAŻNE: jeżeli posiadasz wgrany tylko jeden feed produktowy, system automatycznie połączy przesyłane zdarzenia z feedem produktowym wgranym do systemu. Natomiast, gdy korzystasz z opcji wielu sklepów (multistore) ważne jest zachowanie spójności w przesyłaniu zdarzeń zewnętrznych z unikalnym identyfikatorem, czyli każdy sklep ma mieć swój unikalny ID e-sklepu i swój unikalny feed produktowy.

 

CZYM JEST FEED PRODUKTOWY (URL ŹRÓDŁA DANYCH)?

Jest to plik zawierający opis i atrybuty produktów dostępnych w ofercie sklepu internetowego. W SALESmanago przyjmowany jest on w postaci XML.

WAŻNE: dla każdego e-sklepu powinien być zdefiniowany jeden unikalny, kompletny XML zawierający unikalne ID dla każdego produktu wraz z unikalnym adresem URL.
Dodatkowe źródła produktów nie będą uwzględniane w analityce i raportowaniu, mogą być wykorzystywane jedynie do tworzenia zaawansowanych treści dynamicznych.

Szczegółowe informacje o XML >>
Dowiedz się jak dodać XML do systemu SALESmanago >>

ID Produktu – musi być unikalne w obrębie e-sklepu, składające się z ciągu cyfr. ID produktu nie powinno zawierać żadnych innych znaków, oraz nie powinny być w nim przekazywane żadne dodatkowe informacje np. rozmiar produktu.

Poprawne ID produktu: 4567
Niepoprawne ID produktu: 4567_M ; 4xb567 ; 4-5-677

 

DLACZEGO WAŻNE JEST POSIADANIE W XMLu TYCH SAMYCH ID, KTÓRE PRZESYŁANE SĄ W ZDARZENIACH ZEWNETRZNYCH?

Jeżeli przesyłamy zdarzenie zewnętrzne zawierające np. 3 ID produktów: 2346, 7899, 1222 i okaże się, że w momencie przesyłania przynajmniej jeden ID produktu nie zostanie dopasowany do informacji zawartych w XMLu, wówczas całe zdarzenie zewnętrzne jest ignorowane w analityce i nie będzie zaliczone do żadnych statystyk dostępnych w systemie SALESmanago. Dlatego w celu poprawnego korzystania z systemu konieczne jest posiadanie XMLa ze wszystkimi produktami dostępnymi w sklepie.

 

DLACZEGO WAŻNE JEST, ABY KAŻDY PRODUKT POSIADAŁ UNIKALNY ADRES URL na STRONIE WWW I TAKI SAM W XMLu?

Jedną z funkcjonalności systemu SALESmanago jest monitorowanie aktywności kontaktów na stronie www. Monitorowanie to odbywa się m.in. na podstawie zapisywania adresów URL, które odwiedził kontakt na stronie www. Mając adres URL strony którą odwiedził kontakt, możemy ją dopasować z adresem URL produktu, który posiadamy w XMLu. Dzięki temu możemy zidentyfikować dokładnie, jaki produkt został odwiedzony przez kontakt, a następnie te informacje wykorzystać przy rekomendowaniu produktów np. w ramkach rekomendacji, czy mailach dynamicznych. W momencie gdy URL produktu na stronie www jest inny niż URL produktu w XMLu dopasowanie znacznie się komplikuje i uniemożliwia w całości wykorzystanie potencjału jaki niesie system SALESmanago.

 

JAK PRZESYŁAĆ DANE TRANSAKCYJNE DO SALESmanago

Przesyłanie zdarzeń zewnętrznych pomiędzy platformą sklepową, a systemiem SALESmanago odbywa się za pomocą zdarzeń zewnętrznych (external events) przesyłanych przez API. (Metoda addContactExtEvent)

Wyróżniamy w tym przypadku 4 typy zdarzeń zewnętrznych:
CART, PURCHASE, CANCELLATION, RETURN.

  • CART – dotyczy informacji o koszyku
    • każde dodanie produktu do koszyka powinno być przesłane jako osobne zdarzenie zewnętrzne o typie CART
    • każde zdarzenie powinno w polu “value” zawierać wartość produktów dodanych do koszyka w zdarzeniu
    • zdarzenia nie powinny być usuwane, ani modyfikowane
  • PURCHASE – dotyczy informacji o dokonanym zakupie
    • każda sfinalizowana transakcja powinna być przesłana jako zdarzenie zewnętrzne z typem PURCHASE
    • każde zdarzenie powinno w polu “value” zawierać wartość produktów zakupionych w zdarzeniu
    • zdarzenia nie powinny być usuwane, ani modyfikowane
  • CANCELLATION – dotyczy informacji o zwrocie / anulowaniu zakupu
    • w przypadku, gdy chcemy zaraportować zmianę dotyczącą anulowania całej transakcji powinien być użyty typ zdarzenia zewnętrznego CANCELLATION. W tym zdarzeniu powinny znajdować się dokładnie te same ID produktów, które były przesłane we wcześniejszej transakcji, która ma zostać zaraportowana jako anulowana.
    • każde zdarzenie powinno w polu “value” zawierać wartość anulowanych produktów przesyłanych w zdarzeniu
    • zdarzenia nie powinny być usuwane, ani modyfikowane
  • RETURN – dotyczy informacji o zwrocie jednego z zakupionych produktów
    • w przypadku, gdy chcemy zaraportować zwrot jednego lub kilku produktów ze wcześniejszej transakcji powinien być użyty typ zdarzenia zewnętrznego RETURN. W tym zdarzeniu powinny znajdować się ID produktów, które wcześniej zostały zakupione.
    • każde zdarzenie powinno w polu “value” zawierać wartość zwracanych produktów przesyłanych w zdarzeniu
    • zdarzenia nie powinny być usuwane, ani modyfikowane

Poniżej znajduje się przykładowe zapytanie wysłane przez API rejestrujące zdarzenie zewnętrzne.

{
  "clientId":"your-client-id-123",
  "apiKey":"your-api-key-123",
  "requestTime":1356180568127,
  "sha":"3e4ec39722326150aae60f41e038d1def4450f46",
  "owner":"admin@vendor.pl",
  "email":"konrad@benhauer.com",
  "forceOptOut": true,
  "contactEvent":{
      "date":1356180568153,
      "description":"Zakup z kartą \"Super Bonus\"",
      "products":"123,478",
      "location":"shop_123",
      "value":1234.43,
      "contactExtEventType":"PURCHASE",
      "detail1":"C.ID: *** *** 234",
      "detail2":"Płatość kartą",
      "detail3":null,
      "externalId":"A-123123123",
      "shopDomain":"shop.salesmanago.pl"
  }
}

 

Pole Maksymalna długość Opis
cientId pole obowiązkowe – Twój unikalny identyfikator konta w SALESmanago. Dostępny w zakładce ustawieniach ->Inne
apiKey pole obowiązkowe – Twój unikalny klucz konta w SALESmanago. Dostępny w zakładce ustawieniach ->Inne
requestTime timestamp data przesłania requestu
owner 255 pole obowiązkowe – właściciel kontaktu / adres email kont w systemie SALESmanago
email / contactID 255 e-mail kontaktu lub unikalny ID kontaktu (unikalny ID – opcja dostępna dla wybranych klientów)
email forceOptOut true / false

Status kontaktu – false – kontakt będzie posiadał status opt-out (brak zgody na otrzymywanie wiadomości drogą elektroniczną) opt-in (zgoda na otrzymywanie wiadomości drogą elektroniczną)

date timestamp pole obowiązkowe – data wystąpienia transakcji w sklepie (realna data zakupu w sklepie)
description 255 dodatkowy opis transakcji
products 512 pole obowiązkowe – lista ID produktów oddzielonych przecinkiem.

Przykład:
Jeżeli ktoś kupi 2 takie same produkty o ID 234, poprawny format przesyłanych danych to “234,234”.

Jeżeli kontakt zakupi 1 produkt o ID 234, poprawny format przesyłanych danych to “234”

location 36

pole obowiązkoweunikalny ID e-sklepu, służący do połączenia informacji przesyłanych w zdarzeniu zewnętrznym z informacjami zawartymi w e-sklepie. 

WAŻNE:

wartość może zawierać litery a-z, cyfry 1-9, /_-. bez spacji – wielkość liter ma znaczenie – dozwolone są tylko małe litery.

 

value 19 (+ 2 po kropce)

pole obowiązkowe – jest to suma wartości wszystkich produktów przesyłanych w zdarzeniu. Wartość tego pola nie powinna być pusta ani posiadać wartości “null”.

Przykład:
W zdarzeniu przesyłamy 2 produkty:
buty (ID 345) o wartości 150,50 zł
torba sportowa (ID 678) o wartości 200,20 zł

w polu product prześlemy wartości: “345,678”
w polu value prześlemy wartość: “350.70”

WAŻNE:

W polu value nie przekazujemy informacji o walucie! Walutę definiujemy przy dodawaniu XML do e-sklepu w systemie SALESmanago. Należy pamiętać, że 1 sklep powinien posiadać 1 walutę. Jest to ważne przy analizowaniu sumy sprzedanych produktów. Jeżeli w jednym sklepie będzie dokonana transakcja o wartości 200$, a druga transakcja o wartości 300 euro – to pierwsze zdarzenie zewnętrzne będzie miało wartość value 200, a drugie value 300 i na dashboardzie analitycznym suma sprzedaży będzie pokazana 500. Co nie będzie dokładnie oddawało sumy 200 $+300 euro.

contact ExtEvent Type 255 pole obowiązkowe – Typ: CART, PURCHASE, CANCELLATION, RETURN
detail 1-20

możliwość przesyłania 20 różnych szczegółów o produktach znajdujących się w zdarzeniu zewnętrznym lub innych szczegółach dotyczących transakcji.

Jeżeli w obrębie jednego szczegółu przesyłamy kilka wartości dotyczących produktów, kolejność wartości szczegółów powinna odpowiadać kolejności przesłanych ID produktów, rozdzielonych przecinkiem.

Przykład:

W zdarzeniu przesyłamy 2 produkty:
buty (ID 345) detal1 czarne
torba sportowa (ID 678) detal1 czerwona

w polu product prześlemy wartości: “345,678”
w polu detal1 prześlemy wartość: “czarne,czerwona”

ShopDomain miejsce na przesłanie domeny sklepu. Pole opcjonalne.

 

Aby upewnić się, że integracja danych transakcyjnych pomiędzy zewnętrzną platformą a SALESmanago przebiegła pomyślnie, skorzystaj z poniższej checklisty i sprawdź krok po kroku czy na wszystkie pytania odpowiedź jest twierdząca.

 

1. WERYFIKACJA Z KAŻDYM KLIENTEM

Przygotowanie feedu produktowego (XML)

  • Czy XML zawiera wszystkie produkty, które są dostępne w sklepie?
  • Czy każdy produkt posiada unikalne ID produktu składające się z samych cyfr?
  • Czy każdy produkt posiada unikalny adres URL do produktu?
  • Czy każdy produkt posiada cenę?
  • Czy klient prowadzi uaktualnienia w feedzie produktowym, dzięki którym mamy na bieżąco informacje o produktach dostępnych w sklepie?
  • Czy w XMLu znajdują się ceny produktów w tej samej walucie?

Dodanie feedu produktowego do SALESmanago

  • Czy każdy sklep posiada w systemie jedno konto e-sklep z feedem produktowym?
  • Jeżeli dla jednego sklepu mamy więcej niż jedno konto e-sklep z feedem produktowym, to czy jest zaznaczona w głównym e-sklepie opcja: ustaw ten sklep jako domyślny?
  • Czy w e-sklepie z feedem produktowym jest uzupełnione pole ID e-sklepu (location) – czyli wartość jaka jest przesyłana w zdarzeniach zewnętrznych w polu location?

1. WERYFIKACJA Z KLIENTEM W ZALEŻNOŚCI OD TYPU INTEGRACJI

INTEGRACJA ZDARZEŃ ZEWNĘTRZNYCH PRZEZ API

  • Czy przesyłane są zdarzenia zewnętrzne o typie: CART, PURCHASE, CANCELATION, RETURN?
  • Czy nie są prowadzone zmiany / uaktualnienia w zdarzeniach zewnętrznych?
  • Czy w zdarzaniach zewnętrznych w polu location przesyłane jest unikalne ID e-sklepu?
  • Czy w zdarzaniach zewnętrznych wartość pola date jest przesyłana w formacie timestamp?
  • Czy w zdarzeniach zewnętrznych poprawnie przesyłane są w polu products ID produktów?
  • Czy w zdarzeniach zewnętrznych poprawnie przesyłana jest wartość pola value i nie jest pusta?

INTEGRACJA ZDARZEŃ ZEWNĘTRZNYCH PRZEZ WTYCZKĘ SALESmanago

  • Czy klient ma zainstalowaną najnowszą wersję wtyczki?

 

WAŻNE: Pamiętaj, aby na wszystkie powyższe pytania odpowiedzieć twierdząco. Tylko wtedy masz pewność, że integracja danych transakcyjnych pomiędzy zewnętrzną platformą a SALESmanago jest wykonana poprawnie.