Wstęp¶
System¶
W SAREhubie mianem systemu określamy element, który potrafi generować własne zdarzenia i odpowiednio reagować na wybrane zdarzenia generowane przez inne systemy, które zostały do niego skierowane.
Moduł systemu¶
System może być podzielony na wiele modułów w zależności od danej funkcjonalności. Każdy moduł może być zarówno producentem jak i konsumentem zdarzeń.
Podłączenie do SAREhub¶
Zewnętrzny system, który chce podłączyć się do SAREhub musi uzyskać login i hasło do systemu. Nadana mu zostanie także nazwa systemu identyfikująca go w SAREhub. Nazwa systemu może składać się z od 3 do 32 znaków, wyłącznie z małych liter alfabetu łacińskiego oraz liczb (np. system1). Dodatkowo musi określić sposób kolejkowania zadań dla każdego z modułów (single, multi, none):
- w trybie kolejkowania “single” zdarzenia wszystkich podłączonych kont SAREhub’a są przesyłane do jednej kolejki. System otrzymuje dostęp do kolejek o nazwie zgodnej z formatem C<nazwasystemu>_<moduł>
- tryb “multi” pozwala na przesyłanie zdarzeń ze wszystkich podłączonych kont SAREhub’a do wielu kolejek. System w trybie “multi”, otrzymuje dostęp do kolejek o nazwie zgodnej z formatem C<nazwasystemu>_<moduł>_<hubId>
- tryb “none” oznacza brak kolejki
System ma prawo zapisu wyłącznie do exchange o nazwie zgodnej z nadaną nazwą systemu poprzedzonej literami PC, czyli PC<nazwasystemu>
Schemat wymiany zdarzeń pomiędzy systemami¶
Powyższy diagram przedstawia sposób przepływu wymiany zdarzeń pomiędzy systemami. Zdarzenia kierowane są do kolejek właściwych odbiorców, dzięki użyciu klucza routingu (routing_key). Mogą być one przesyłane zarówno z modułu, który jest wyłącznie producentem (Module3, Module4) lub konsumentem (Module5), jak również z modułu, który spełnia rolę producenta oraz konsumenta (Module1, Module2). Klucz routingu, który kieruje zdarzenia do exchange systemu, przyjmuje wartość hubId.#. Zdarzenie kierowane jest następnie do exchange klienta SAREhub’a (hubId), a później do wybranej kolejki modułu danego systemu. W tym przypadku wartość klucza routingu przyjmuje np. hubId.system1_module2
System może posiadać dowolną liczbę modułów.
Zdarzenie¶
- Określa wystąpienie jakieś akcji np. wejście na stronę internetową.
- Jest generowane przez zintegrowane w SAREhabie systemy.
- Wywołuje odpowiednie akcje w nasłuchujących go systemach podłączonych do SAREhuba.
Specyfikacja zdarzenia¶
Każde zdarzenie posiada swoją specyfikację, którą dostarcza zintegrowany z SAREhubem system. Specyfikacja ta określa:
- identyfikator typu zdarzenia
- listę atrybutów zdarzenia
- opis
Magistrala zdarzeń¶
Jest to serce platformy SAREhub. Przez nie pomopowane są zdarzenia do zintegrowanych systemów. Rolę tej magistrali pełni w SAREhubie broker wiadomości RabbitMQ
Strumienie zdarzeń¶
- To ciąg zdarzeń.
- Zawiera jeden lub więcej typów zdarzeń.
- Jest przetwarzany przez rurociąg przetwarzania.
Rurociąg(pipeline) przetwarzania¶
Rurociągiem przetwarzania nazywamy odpowiednie połączenie źródła(source) strumienia zdarzeń ze “zlewami”(sinks) do których po kolei wpadają zdarzenia.
Źródła zdarzeń¶
System podłączony do SAREhuba może generować zdarzenia specyficzne dla siebie np. Zdarzenie wejścia na podaną stronę internetową. Takie zdarzenie może przekazać do systemu który jest zainteresowany jego obsługą. W odpowiedzi na zdarzenia system może również generować zdarzenia innych typów, które przekaże innym systemom do których może je publikować.
RabbitMQ¶
Podstawowym źródłem zdarzeń które są generowane przez inne systemy są kolejki Rabbita. Moduł danego systemu otrzymuje dostęp do kolejki o odpowiednim identyfikatorze do której kierowane są zdarzenia z innych systemów.
Zlewy dla zdarzeń¶
Zlewy(sink) to miejsca do których trafiają zdarzenia by zostać poddane dalszemu przetworzeniu. Moduł systemu posługuje się nimi by zbudować rurociąg przetwarzania. W rurociągu na podstawie zdarzenia wejściowego system może wykonywać odpowiednie akcje(np.wysłać maila, włączyć ulubioną muzykę na odwiedzanej stronie itp.).
RabbitMQ¶
Zdarzenia wygenerowane przez system przeznaczone dla innych systemów trafiają poprzez dedykowany exchange systemu poprzez odpowiedni routing key do kolejki danego modułu innego systemu.
Przykłady interakcji pomiędzy systemami¶
Przykład 1¶
Powyższy diagram pokazuje prostą reakcję kilku zintegrowanych z SAREhubem systemów na zdarzenie wejścia użytkownika na stronę internetową.
- Użytkownik wchodzi na stronę www.example.com/page1 system X wysyła zdarzenie(UserViewedPageEvent) do SAREhuba.
- System Y nasłuchuje na zdarzenia typu UserViewedPageEvent i reaguje na nie w postaci wysłania kolejnego zdarzenia(RequestedSendMailEvent) do SAREhuba.
- System Z nasłuchuje na zdarzenia typu RequestedSendMailEvent i wysyła odpowiedni mail do użytkownika zapisanego w atrybutach zdarzenia oraz zdarzenie(SentMailEvent) do SAREhuba.
Podstawowe typy zdarzeń¶
Każde zdarzenie w systemie SAREhub powinno posiadać swoją ścieżkę routingu, która definiuje gdzie (do jakiego modułu) komunikat zostanie dostarczony. Klucz routingu składa się z od dwóch do pięciu elementów oddzielonych kropką:
- hub[hub_id].destination
- hub[hub_id].destination.key1
- hub[hub_id].destination.account_id.key1
- hub[hub_id].destination.account_id.type.key1
- hub[hub_id].destination.type.key1
- hub[hub_id].type.key1
Pierwszy element (hubId) oznacza identyfikator huba do którego chcemy publikować dane (np. hub112).
Element destination oznacza miejsce docelowe (moduł) gdzie zdarzenie ma trafić.
Element account_id oznacza idetyfikator zintegrowanego konta klienta w zdalnym systemie (module) do którego publikujemy dane.
Część type definiuje typ zdarzenia:
- discover – wiadomości z prośbą o informacje użytkowniku,
- user – wiadomości przekazujące informacje na temat użytkownika,
- message – wiadomości zawierające przekaz (wiadomość dla użytkownika).
Ostatni element służy do określenia typu klucza użytkownika. Aktualnie są obsługiwane następujące rodzaje kluczy:
- emailmd5
- cookie
- mobile
- phone
- postal
Poprawnymi kluczami routingu są, np.:
- hub122.sare
- hub123.sare.1
- hub234.sare.1.message.email
- hub100.message.email
- hub987.user.cookie
Podstawowe zdarzenia¶
- dla zdarzeń typu user:
- online - informuje, że użytkownik właśnie pojawił się online. Obiekt params MUSI zawierać atrybut time zawierający timestamp zdarzenia. W przypadku jeżeli użytkownik odwiedza stronę WWW, obiekt params POWINIEN zawierać atrybut url zawierający URL odwiedzaną stronę,
- info - obiekt params MOŻE zawierać wartości innych kluczy, które powiązane są z tym użytkownikiem,
- tag - użytkownik został oznaczony tagiem. Obiekt params MUSI zawierać atrybut name. Wartością atrybutu name może być nazwa tagu lub tablica tagów,
- funnel - użytkownik wszedł w lejek sprzedażowy. Obiekt params MUSI zawierać atrybut time zawierający timestamp zdarzenia oraz POWINIEN zawierać atrybut level z wartością określającą poziom zaangażowania użytkownika w wartościach od 0 do 100 (osiągnięto cel).
- dla zdarzeń typu discover:
- discover - payload MUSI zawierać przynajmniej jeden z kluczy. Jest to komunikat z prośbą o informacje o użytkowniku identyfikowanym przez klucz. Obiekt params może zawierać atrybut search. Jego wartością jest string (lub tablica stringów) określający szukane parametry, w szczególności klucze (email, emailmd5, cookie, mobile, phone, postal).
- dla zdarzeń typu message:
- message – payload MUSI zawierać przynajmniej jeden z kluczy. Obiekt params POWINIEN zawierać atrybut body, którego wartością jest treść wiadomości skierowanej do użytkownika. Obiekt params może zawierać również atrybuty będące nazwami kluczy których wartościami są obiekty.
Dla klucza email obiekt params POWINIEN być zbudowany wg następującego schematu (dopuszczalne są dodatkowe argumenty):
{
"from": "nadawca emaila",
"to": "odbiorca emaila",
"subject": "tytuł emaila",
"body": {
"txt": "string lub object z parametrem url",
"html": "string lub object z parametrem url"
}
}
Dla klucza mobile obiekt params POWINIEN być zbudowany wg następującego schematu (dopuszczalne są dodatkowe argumenty):
{
"from": "nadawca sms",
"to": "odbiorca sms",
"body": "treść sms"
}
Struktura zdarzeń w SAREhub¶
Każde zdarzenie ma następujący format:
{
"type": "object",
"title": "Zdarzenie użytkownika.",
"properties": {
"type": {
"type": "string",
"title": "Typ zdarzenia."
},
"user": {
"type": "object",
"title": "Klucze identyfikujące użytkownika.",
"properties": {}
},
"time": {
"type": "integer",
"title": "Czas wystąpienia zdarzenia."
},
"params": {
"type": "object",
"title": "Atrybuty opisujące konkretne zdarzenie.",
"properties": {}
}
},
"required": [
"type",
"user",
"time",
"params"
]
}
Lista zdarzeń oraz atrybutów je opisujących¶
- tag - Tagowanie użytkownika.
{
"type": "object",
"title": "Atrybuty zdarzenia tag.",
"properties": {
"name": {
"type": "string",
"title": "Nazwa tagu."
}
},
"required": [
"name"
]
}
Przykład:
{
"type": "tag",
"user": {
"cookie": "33413026813181711"
},
"time": 1475756549,
"params": {
"name": "4|flowchart-filter_previous_block-1461074520658|flowchart-alert-1461074548667"
}
}
- discover - Prośba o informacje o użytkowniku identyfikowanym przez dany klucz.
{
"type": "object",
"title": "Atrybuty zdarzenia discover.",
"properties": {
"search": {
"type": "string",
"title": "Typ klucza użytkownika.",
"description": "Typ Klucza użytkownika dla którego wyszukiwane są informacje."
},
"processing_message": {
"type": "object",
"title": "Wiadomość zwrotna.",
"description": "Zdarzenie które ma być wywołane po powrocie komunikatu z szukanymi informacjami. Do niego może zostać wstrzyknięta znaleziona wartość klucza.",
"properties": {}
}
},
"required": [
"search"
]
}
Przykład:
{
"type": "discover",
"user": {
"cookie": "33413026813181711"
},
"time": 1475756549,
"params": {
"search": "id",
"processing_message": {
"type": "tag",
"user": {
"cookie": "33413026813181711"
},
"time": 1475756549,
"params": {
"name": "4|flowchart-filter_previous_block-1461074520658|flowchart-alert-1461074548667"
}
}
}
}
- info - Zawiera informacje na temat danego klucza powiązanym z danym użytkownikiem.
{
"type": "object",
"title": "Atrybuty zdarzenia info.",
"properties": {}
}
Przykład:
{
"type": "info",
"user": {
"cookie": "83966095470796834"
},
"time": 1475756549,
"params": {
"email": [
"it@sarehub.com"
]
}
}
- online - Zdarzenie informuje, że użytkownik właśnie pojawił się online.
{
"type": "object",
"title": "Atrybuty zdarzenia online.",
"description": "Atrybuty zdarzenia online wysyłanego przez system SAREweb.",
"properties": {
"url": {
"type": "string",
"title": "Url strony."
},
"url_norm": {
"type": "string",
"title": "Znormalizowany url strony."
},
"uri": {
"type": "string",
"title": "Uri strony."
},
"domain": {
"type": "string",
"title": "Domena strony."
},
"ref_type": {
"type": "string",
"title": "Typ referera."
},
"seconds_on_domain": {
"type": "integer",
"title": "Czas pobyt na danej domenie."
},
"visited_sites": {
"type": "integer",
"title": "Liczba odwiedzonych stron"
},
"ip": {
"type": "integer",
"title": "Ip użytownika.",
"description": "IP użytkownika zapisane w formie liczby całkowitej."
},
"tmp_cookie": {
"type": "string",
"title": "Sesja użytkownika."
},
"extra": {
"type": "string",
"title": "Dodatkowe parametry."
},
"utm_source": {
"type": "string",
"title": "Tag Google Analitycs utm_source."
},
"utm_medium": {
"type": "string",
"title": "Tag Google Analitycs utm_medium."
},
"utm_term": {
"type": "string",
"title": "Tag Google Analitycs utm_term."
},
"utm_content": {
"type": "string",
"title": "Tag Google Analitycs utm_content."
},
"utm_campaign": {
"type": "string",
"title": "Tag Google Analitycs utm_campaign."
},
"session_referer": {
"type": "string",
"title": "Referer pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_type": {
"type": "string",
"title": "Typ referera pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_site": {
"type": "string",
"title": "Strona referera pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_keywords": {
"type": "string",
"title": "Słowa kluczowe pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_source": {
"type": "string",
"title": "Tag Google Analitycs utm_source pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_medium": {
"type": "string",
"title": "Tag Google Analitycs utm_medium pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_term": {
"type": "string",
"title": "Tag Google Analitycs utm_term pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_content": {
"type": "string",
"title": "Tag Google Analitycs utm_content pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_campaign": {
"type": "string",
"title": "Tag Google Analitycs utm_campaign pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"known": {
"type": "boolean",
"title": "Znany użytkownik.",
"description": "Informuje o tym czy w systemie SAREweb użytkownik posiada adres email."
}
},
"required": [
"url",
"url_norm",
"uri",
"domain",
"ref_type",
"seconds_on_domain",
"visited_sites",
"ip",
"tmp_cookie",
"extra",
"utm_source",
"utm_medium",
"utm_term",
"utm_content",
"utm_campaign",
"session_referer",
"session_ref_type",
"session_ref_site",
"session_ref_keywords",
"session_utm_source",
"session_utm_medium",
"session_utm_term",
"session_utm_content",
"session_utm_campaign",
"known"
]
}
Przykład:
{
"type": "online",
"user": {
"cookie": "22281308789088642"
},
"time": 1475756549,
"params": {
"url": "http://urlstrony.pl/samochod?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"url_norm": "http://urlstrony.pl/samochod?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"uri": "/?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"domain": "urlstrony.pl",
"ref_type": "direct",
"seconds_on_domain": 166,
"visited_sites": 1,
"ip": 1408141498,
"tmp_cookie": "66978568417584187",
"extra": "",
"utm_source": "facebook",
"utm_medium": "test",
"utm_term": "",
"utm_content": "",
"utm_campaign": "zabawki",
"session_referer": "",
"session_ref_type": "direct",
"session_ref_site": "",
"session_ref_keywords": "",
"session_utm_source": "facebook",
"session_utm_medium": "test",
"session_utm_term": "",
"session_utm_content": "",
"session_utm_campaign": "zabawki",
"known": false
}
}
- offline - Zdarzenie informuje, że użytkownik przeszedł w tryb offline.
{
"type": "object",
"title": "Atrybuty zdarzenia offline.",
"description": "Atrybuty zdarzenia offline wysyłanego przez system SAREweb.",
"properties": {
"url": {
"type": "string",
"title": "Url strony."
},
"url_norm": {
"type": "string",
"title": "Znormalizowany url strony."
},
"uri": {
"type": "string",
"title": "Uri strony."
},
"domain": {
"type": "string",
"title": "Domena strony."
},
"tmp_cookie": {
"type": "string",
"title": "Sesja użytkownika."
},
"seconds_on_url": {
"type": "integer",
"title": "Czas pobytu na danej stronie."
},
"seconds_on_domain": {
"type": "integer",
"title": "Czas pobyt na danej domenie."
},
"visited_sites": {
"type": "integer",
"title": "Liczba odwiedzonych stron."
},
"session_referer": {
"type": "string",
"title": "Referer pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_type": {
"type": "string",
"title": "Typ referera pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_site": {
"type": "string",
"title": "Strona referera pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_keywords": {
"type": "string",
"title": "Słowa kluczowe pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_source": {
"type": "string",
"title": "Tag Google Analitycs utm_source pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_medium": {
"type": "string",
"title": "Tag Google Analitycs utm_medium pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_term": {
"type": "string",
"title": "Tag Google Analitycs utm_term pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_content": {
"type": "string",
"title": "Tag Google Analitycs utm_content pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_campaign": {
"type": "string",
"title": "Tag Google Analitycs utm_campaign pierwszego wejścia na stronę, ustawiany dla całej sesji."
}
},
"required": [
"url",
"url_norm",
"tmp_cookie",
"domain",
"seconds_on_url",
"seconds_on_domain",
"visited_sites",
"session_referer",
"session_ref_type",
"session_ref_site",
"session_ref_keywords",
"session_utm_source",
"session_utm_medium",
"session_utm_term",
"session_utm_content",
"session_utm_campaign"
]
}
Przykład:
{
"type": "offline",
"user": {
"cookie": "63608288842324163"
},
"time": 1475756549,
"params": {
"url": "http://urlstrony.pl/samochod?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"url_norm": "http://urlstrony.pl/samochod?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"uri": "/?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"domain": "urlstrony.pl",
"tmp_cookie": "96372242750554029",
"seconds_on_url": 23,
"seconds_on_domain": 169,
"visited_sites": 1,
"session_referer": "",
"session_ref_type": "direct",
"session_ref_site": "",
"session_ref_keywords": "",
"session_utm_source": "facebook",
"session_utm_medium": "test",
"session_utm_term": "",
"session_utm_content": "",
"session_utm_campaign": "zabawki"
}
}
- ping - Zdarzenie informuje o pobycie użytkownika na stronie.
{
"type": "object",
"title": "Atrybuty zdarzenia ping.",
"description": "Atrybuty zdarzenia ping wysyłanego przez system SAREweb",
"properties": {
"url": {
"type": "string",
"title": "Url strony."
},
"url_norm": {
"type": "string",
"title": "Znormalizowany url strony."
},
"uri": {
"type": "string",
"title": "Uri strony."
},
"domain": {
"type": "string",
"title": "Domena strony."
},
"tmp_cookie": {
"type": "string",
"title": "Sesja użytkownika"
},
"seconds_on_url": {
"type": "integer",
"title": "Czas pobytu na danej stronie."
},
"seconds_on_domain": {
"type": "integer",
"title": "Czas pobyt na danej domenie."
},
"visited_sites": {
"type": "integer",
"title": "Liczba odwiedzonych stron."
},
"session_referer": {
"type": "string",
"title": "Referer pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_type": {
"type": "string",
"title": "Typ referera pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_site": {
"type": "string",
"title": "Strona referera pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_ref_keywords": {
"type": "string",
"title": "Słowa kluczowe pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_source": {
"type": "string",
"title": "Tag Google Analitycs utm_source pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_medium": {
"type": "string",
"title": "Tag Google Analitycs utm_medium pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_term": {
"type": "string",
"title": "Tag Google Analitycs utm_term pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_content": {
"type": "string",
"title": "Tag Google Analitycs utm_content pierwszego wejścia na stronę, ustawiany dla całej sesji."
},
"session_utm_campaign": {
"type": "string",
"title": "Tag Google Analitycs utm_campaign pierwszego wejścia na stronę, ustawiany dla całej sesji."
}
},
"required": [
"url",
"url_norm",
"uri",
"domain",
"tmp_cookie",
"seconds_on_url",
"seconds_on_domain",
"visited_sites",
"session_referer",
"session_ref_type",
"session_ref_site",
"session_ref_keywords",
"session_utm_source",
"session_utm_medium",
"session_utm_term",
"session_utm_content",
"session_utm_campaign"
]
}
Przykład:
{
"type": "ping",
"user": {
"cookie": "46002764640577325"
},
"time": 1475756549,
"params": {
"url": "http://urlproduktu.pl/samochod?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"url_norm": "http://urlproduktu.pl/samochod?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"uri": "/?utm_source=facebook&utm_medium=test&utm_campaign=zabawki",
"domain": "urlproduktu.pl",
"tmp_cookie": "96372242750554029",
"seconds_on_url": 14,
"seconds_on_domain": 98,
"visited_sites": 1,
"session_referer": "",
"session_ref_type": "direct",
"session_ref_site": "",
"session_ref_keywords": "",
"session_utm_source": "facebook",
"session_utm_medium": "medium",
"session_utm_term": "",
"session_utm_content": "",
"session_utm_campaign": "zabawki"
}
}
Zdarzenia koszykowe¶
Zdarzenia koszykowe wysyłane podczas procesu zakupowego.
Format zdarzenia koszykowego¶
Każde zdarzenie koszykowe ma następujący format:
{
"type": "object",
"description": "Zdarzenie użytkownika",
"required": [
"type",
"user",
"time",
"params"
],
"properties": {
"type": {
"type": "string",
"title": "Typ zdarzenia"
},
"user": {
"type": "object",
"title": "Klucze identyfikujące użytkownika.",
"properties": {}
},
"time": {
"type": "integer",
"title": "Czas wystąpienia zdarzenia."
},
"params": {
"type": "object",
"title": "Atrybuty opisujące konkretne zdarzenie.",
"properties": {}
}
}
}
Lista zdarzeń oraz atrybutów je opisujących¶
- category_seen - zdarzenie wysyłane w momencie wejścia w daną kategorię
{
"type": "object",
"title": "Atrybuty zdarzenia category_seen",
"properties": {
"id": {
"type": "string",
"title": "Id kategrii."
},
"country": {
"type": "string",
"title": "Kraj docelowy.",
"description": "Kraj docelowy product feeda w formacie ISO 3166-1 alfa-2."
},
"language": {
"type": "string",
"title": "Język product feeda.",
"description": "Język w jakim przygotowany jest product feed w formacie ISO 639-1."
}
},
"required": [
"id",
"country",
"language"
]
}
Przykład:
{
"type": "category_seen",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"id": "nazwa kategorii",
"country": "PL",
"language": "pl"
}
}
- product_seen - zdarzenie wysyłane w momencie wejścia na dany produkt
{
"type": "object",
"title": "Atrybuty zdarzenia product_seen",
"properties": {
"id": {
"type": "string",
"title": "Id Produktu."
},
"name": {
"type": "string",
"title": "Nazwa produktu."
},
"price": {
"type": "integer",
"title": "Cena produktu",
"description": "Cena produktu podana w najniższym nominale"
},
"currency": {
"type": "string",
"title": "Kod waluty"
},
"url": {
"type": "string",
"title": "URL produktu."
},
"category": {
"type": "array",
"title": "Kategorie produktu.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "Id kategorii."
}
},
"required": [
"id"
]
}
},
"country": {
"type": "string",
"title": "Kraj docelowy.",
"description": "Kraj docelowy product feeda w formacie ISO 3166-1 alfa-2."
},
"language": {
"type": "string",
"title": "Język product feeda.",
"description": "Język w jakim przygotowany jest product feed w formacie ISO 639-1."
}
},
"required": [
"id",
"name",
"price",
"currency",
"url",
"category",
"country",
"language"
]
}
Przykład:
{
"type": "product_seen",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"country": "PL",
"language": "pl",
"id": "1",
"name": "Samochód zabawka",
"price": 15900,
"currency": "pln",
"url": "http://urlproduktu.pl/samochod",
"category": [
{
"id": "zabawki"
},
{
"id": "samochody"
}
]
}
}
- cart_added_product - zdarzenie wysyłane w momencie dodania produktu do koszyka
{
"type": "object",
"title": "Atrybuty zdarzenia cart_added_product",
"properties": {
"cart_id": {
"type": "string",
"title": "Id koszyka"
},
"product_id": {
"type": "string",
"title": "Id Produktu."
},
"name": {
"type": "string",
"title": "Nazwa produktu."
},
"url": {
"type": "string",
"title": "URL produktu."
},
"price": {
"type": "integer",
"title": "Cena produktu",
"description": "Cena produktu podana w najniższym nominale"
},
"currency": {
"type": "string",
"title": "Kod waluty"
},
"quantity": {
"type": "integer",
"title": "Ilość produktu",
"description": "Ilość produktu dodanego do koszyka"
},
"extra": {
"type": "object",
"title": "Dodatkowe parametry",
"description": "Dodatkowe parametry produktu np. rozmiar, kolor itd",
"properties": {}
},
"category": {
"type": "array",
"title": "Kategorie produktu.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "Id kategorii."
}
},
"required": [
"id"
]
}
},
"country": {
"type": "string",
"title": "Kraj docelowy.",
"description": "Kraj docelowy product feeda w formacie ISO 3166-1 alfa-2."
},
"language": {
"type": "string",
"title": "Język product feeda.",
"description": "Język w jakim przygotowany jest product feed w formacie ISO 639-1."
}
},
"required": [
"cart_id",
"product_id",
"price",
"currency",
"quantity",
"url",
"category",
"country",
"language"
]
}
Przykład:
{
"type": "cart_added_product",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"cart_id": "1",
"product_id": "5578",
"price": 9900,
"currency": "pln",
"quantity": 1,
"name": "Nazwa produktu",
"url": "http://urlproduktu.pl/samochod",
"extra": {
"size": "L",
"color": "czerwony"
},
"category": [
{
"id": "zabawki"
},
{
"id": "samochody"
}
],
"country": "PL",
"language": "pl"
}
}
- cart_removed_product - zdarzenie wysyłane w momencie usunięcia produktu do koszyka
{
"type": "object",
"title": "Atrybuty zdarzenia cart_removed_product",
"properties": {
"cart_id": {
"type": "string",
"title": "Id koszyka"
},
"product_id": {
"type": "string",
"title": "Id Produktu."
},
"price": {
"type": "integer",
"title": "Cena produktu",
"description": "Cena produktu podana w najniższym nominale"
},
"currency": {
"type": "string",
"title": "Kod waluty"
},
"quantity": {
"type": "integer",
"title": "Ilość produktu",
"description": "Parametr ten przyjmuje wartość aktualnego stanu ilości produktu w koszyku."
},
"country": {
"type": "string",
"title": "Kraj docelowy.",
"description": "Kraj docelowy product feeda w formacie ISO 3166-1 alfa-2."
},
"language": {
"type": "string",
"title": "Język product feeda.",
"description": "Język w jakim przygotowany jest product feed w formacie ISO 639-1."
}
},
"required": [
"cart_id",
"product_id",
"price",
"currency",
"quantity",
"country",
"language"
]
}
Przykład:
{
"type": "cart_removed_product",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"cart_id": "1",
"product_id": "5578",
"price": 9900,
"currency": "pln",
"quantity": 1,
"country": "PL",
"language": "pl"
}
}
- cart_changed_product_quantity - zdarzenie wysyłane w momencie zmiany ilości produktu w koszyku
{
"type": "object",
"title": "Atrybuty zdarzenia cart_changed_product_quantity",
"properties": {
"cart_id": {
"type": "string",
"title": "Id koszyka"
},
"product_id": {
"type": "string",
"title": "Id Produktu."
},
"quantity": {
"type": "integer",
"title": "Ilość produktu",
"description": "Parametr ten przyjmuje wartość aktualnego stanu ilości produktu w koszyku."
},
"country": {
"type": "string",
"title": "Kraj docelowy.",
"description": "Kraj docelowy product feeda w formacie ISO 3166-1 alfa-2."
},
"language": {
"type": "string",
"title": "Język product feeda.",
"description": "Język w jakim przygotowany jest product feed w formacie ISO 639-1."
}
},
"required": [
"cart_id",
"product_id",
"quantity",
"country",
"language"
]
}
Przykład:
{
"type": "cart_changed_product_quantity",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"cart_id": "1",
"product_id": "5578",
"quantity": 1,
"country": "PL",
"language": "pl"
}
}
- cart_checkout_started - zdarzenie wysyłane w momencie rozpoczęcia procesu zamówienia
{
"type": "object",
"title": "Atrybuty zdarzenia cart_checkout_started",
"properties": {
"cart_id": {
"type": "string",
"title": "Id koszyka."
}
},
"required": [
"cart_id"
]
}
Przykład:
{
"type": "cart_checkout_started",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"cart_id": "1"
}
}
- cart_checkout_step - zdarzenie wysyłane w momencie kolejnego kroku procesu zamówienia
{
"type": "object",
"title": "Atrybuty zdarzenia cart_checkout_step",
"properties": {
"cart_id": {
"type": "string",
"title": "Id koszyka."
},
"step_id": {
"type": "string",
"title": "Krok procesu zamówienia."
}
},
"required": [
"cart_id",
"step_id"
]
}
Przykład:
Krok wypełnienia danych do wysyłki:
{
"type": "cart_checkout_step",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"step_id": "registration",
"cart_id": "1"
}
}
Krok zapłaty za zamówienie:
{
"type": "cart_checkout_step",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"step_id": "payment",
"cart_id": "1"
}
}
- cart_checkout_completed - zdarzenie wysyłane w momencie zakończenia procesu zamówienia
{
"type": "object",
"title": "Atrybuty zdarzenia cart_checkout_completed",
"properties": {
"cart_id": {
"type": "string",
"title": "Id koszyka."
}
},
"required": [
"cart_id"
]
}
Przykład:
{
"type": "cart_checkout_completed",
"user": {
"cookie": "22281308789088642"
},
"time": 1469988000,
"params": {
"cart_id": "1"
}
}
Sposoby integracji¶
REST API¶
REST API umożliwia prostą integrację w przypadku braku możliwości podłączenia poprzez AMQP. To rozwiązanie rekomendujemy w przypadku niskiej częstotliwości wymiany danych.
Protokół AMQP¶
W przypadku bezpośredniego podłączenia do systemu SAREhub za pomocą protokołu AMQP wymagane jest skonfigurowanie VPNa.
Połączenie będzie zrealizowanie z wykorzystaniem tunelu VPN IPsec. Na etapie integracji zostaną ustalone jego parametry.
REST API¶
Wstęp¶
Dokumentacja dla SAREhub REST API które umożliwia wysyłanie oraz pobieranie danych z danych do/z SAREhuba.
Ścieżka¶
Każde poniższe zapytanie zaczyna się od poniższego adresu URL: https://api.sarehub.com/v1
Format¶
Wszystkie zapytania zwracają dane w formacie JSON.
Kody statusów¶
- 200 Pomyślny GET.
- 201 Pomyślny POST i PUT.
- 401 Nieuwierzytelniony.
- 403 Zabroniony.
- 400 Będne zapytanie.
Zabezpieczenia¶
- REST API jest dozwolone tylko dla adresów IP dopisanych do whitelisty.
- Każda metoda jest zabezpieczona poprzez uwierzytelnienie Basic Auth.
Publish¶
POST /publish/routing/:routing
Metoda umożliwia wysłanie (opublikowanie) danych do szyny SAREhub. Parametr :routing powinien przyjąć ciąg routingu, np. hub1.message.email
Treść zapytania
W treści zapytania należy wysłać dane w formacie JSON zgodne z komunikatami SAREhub.
Nagłówki
Dodatkowo jest możliwość przesłania specjalnych nagłówków które dodają dodatkowe opcje do komunikatu:
- SAREhub-reply_to - Parametr, który powinien zawierać ciąg routingu gdzie ma zostać wysłana odpowiedź na wysłany komunikat,
- SAREhub-correlation_id - Parametr przyjmujący dowolną wartość, umożliwia powiązanie komunikatu odpowiedzi z zapytaniem,
- SAREhub-priority - Parametr określający priorytet komunikatu (int),
- SAREhub-delay - Opóźnienie po jakim czasie (w sekundach) komunikat ma trafić do szyny SAREhub.
Przykadowe zapytanie
$ curl -u module:secret https://api.sarehub.com/publish/routing/hub1.message.email
\
-H "Content-Type: application/json" \
-X POST \
-d
'{"type":"message","user":{"email":"hub@sarehub.com"},"params":{"to":"hub@sarehub.com",
"from":"test@sarehub.com","subject":"test","body":{"html":"test","txt":"test"}}}'
Odpowiedź
{
"state": "success"
}
Odpowiedź w przypadku błędu
{
"state": "error",
"message": "Treść błędu"
}
Consume¶
GET /consume
Metoda umożliwia pobieranie komunikatów z domyślnej kolejki. Obsługiwany moduł powinien być skonfigurowany sposób kolejkowania w trybie “single”.
GET /consume/hub/:id
Metoda umożliwia pobieranie komunikatów z kolejki huba o podanym identyfikatorze. Obsługiwany moduł powinien być skonfigurowany sposób kolejkowania w trybie “single”.
GET /consume/queue/:queue_name
Metoda umożliwia pobieranie komunikatów z dodatkowej kolejki o podanej nazwie. Obsługiwany moduł powinien być skonfigurowany sposób kolejkowania w trybie “single”.
GET /consume/hub/:id/queue/:queue_name
Obydwie powyższe metody jednocześnie.
Parametry
Do zapytania można dostać następujące parametry:
- limit - maksymalna liczba komunikautów jaka ma zostać pobrana (domyślnie 100).
Przykadowe zapytanie
$ curl -u module:secret https://api.sarehub.com/consume?limit=2 \
-H "Content-Type: application/json" \
-X POST
Odpowiedź
{
"state": "success",
"count": 2,
"statements": [
{
"type": "message",
"user": {
"email":"hub@sarehub.com"
},
"params": {
"to": "hub@sarehub.com",
"from": "test@sarehub.com",
"subject": "test",
"body": {
"html": "test",
"txt": "test"
}
}
},
{
"type": "message",
"user": {
"email":"hub+test@sarehub.com"
},
"params": {
"to": "hub+test@sarehub.com",
"from": "test+test@sarehub.com",
"subject": "test2",
"body": {
"html": "test2",
"txt": "test2"
}
}
}
]
}
Odpowiedź w przypadku błędu
{
"state": "error",
"message": "Treść błędu"
}
Czym jest SAREhub ?¶
To platforma, która umożliwia integrację wielu systemów oraz pozwala na ich wzajemne interakcje. Interakcje te są realizowane poprzez wysyłanie konkretnych zdarzeń do danego systemu, który je obsługuje. SAREhub jest systemem zorientowanym na użytkownika, tj. każdy komunikat wymieniany pomiędzy modułami dotyczy użytkownika. Dzięki integracji kolejnych systemów, możliwa jest wymiana danych pomiędzy zintegrowanymi systemami różnych producentów i budowa jednego wspólnego profilu użytkownika.
Czym jest system ?¶
W SAREhubie mianem systemu określamy element, który potrafi generować własne zdarzenia i odpowiednio reagować na wybrane zdarzenia generowane przez inne systemy które zostały do niego skierowane.