Widget - frontend

Wtyczka InPost Pay umożliwia parowania koszyków zakupowych w sklepach internetowych Merchantów z aplikacją InPost. Warstwa frontend dostarczona jest w formie wtyczki JavaScript do osadzenia na stronie oraz niniejszej dokumentacji. Warstwa backend dostarcza dane z dwóch źródeł:

dane dotyczące sklepu
dane dotyczące InPost Pay serwowane przez zapytania do API InPost.

Warstwa frontend zakłada użycie warstwy backend tylko po stronie Merchanta i żadne z zapytań nie będzie odpytywać bezpośrednio API InPost.

Do poprawnej integracji wymagane jest dostarczenie warstwy Merchant Backend API zgodnie z powyższym, osadzenie html wtyczki, oraz implementacja wszystkich poniższych metod na warstwie frontend.

Lista metod do zaimplementowania przez backend merchanta w celu używania wtyczki:

● iziGetIsBound
● iziGetOrderComplete
● iziBindingDelete
● iziCanBeBound
● iziAddToCart
● iziGetPayData
● iziMobileLink
● iziGetBrowserData

Lista eventów które należy zaimplementować w celu używania wtyczki:

● inpost-update-count

Na tej stronie

1 Pobranie skryptu
2 Osadzenie html
- 2.1 Wyświetlanie w zależności od parametrów bindowania
3 iziGetPayData
4 iziGetBrowserData
5 iziGetIsBound
6 iziGetOrderComplete
7 iziBindingDelete
8 iziCanBeBound
9 iziAddToCart
10 inpost-update-count
11 iziMobileLink
12 SPA

Pobranie skryptu

Skrypt wtyczki znajduje się pod adresem:

Środowisko	Link

Środowisko	Link
Sandbox	https://izi-sandbox.inpost.pl/inpostizi.js
Produkcja	https://izi.inpost.pl/inpostizi.js

Osadź go na swojej stronie przez:

<script src="https://izi.inpost.pl/inpostizi.js"></script>

Osadzenie html

W celu wyświetlenia widgetu należy osadzić w html poniższy kod:

<inpost-izi-button name="" masked_phone_number=""
data-product-id="" language="pl" variant="primary" basket="true"
dark_mode="true" count="5"
binding_place="PRODUCT_CARD"></inpost-izi-button>

Parametr	Opis

Parametr	Opis
`name`	Imię kupującego, wypełnij jeśli koszyki są sparowane.
`data-product-id`	ID produktu, wymagane jeśli przy parowaniu chcesz dodać produkt o podanym id do koszyka.
`masked_phone_number`	Zamaskowany numer telefonu, wymagane jeśli koszyki są sparowane.
`variant`	Wariant wyglądu przycisku. Zależnie od wyboru, przycisk może przyjąć różne style. Dostępne opcje: "`primary`" , "`secondary`" Przykłady: Dla "`primary`": Dla "`secondary`":
`basket`	Określa czy przycisk znajduje się na stronie koszyka. Dopuszczalna wartość “`true`".
`dark_mode`	Określa tryb wyświetlania. Dopuszczalna wartość “`true`". Przykłady: Dla:”`true`"
`count`	Określa inicjalną liczbę produktów do wyświetlenia na przycisku po sparowaniu, (ilość produktów obecnie w koszyku).
`binding_place`	Określa miejsce, gdzie następuje bindowanie. Informacja ta trafia do `iziGetBindingData` jako parametr. `PRODUCT_CARD` - karta produktu `BASKET_SUMMARY` - podsumowanie koszyka `ORDER_CREATE` - etap tworzenia zamówienia `BASKET_POPUP` - panel boczny koszyka `LOGIN_PAGE` - strona logowania. `CHECKOUT_PAGE` - strona checkout `REGISTERFORM_PAGE` - strona rejestracji `MINICART_PAGE` - minikarta. Dodatkowo na podstawie tego parametru kod rozpoznaje, którą wersję copy (tekstów i wyglądu) powinien zastosować. Przykłady: Dla: “`PRODUCT_CARD`": Dla: “`BASKET_SUMMARY`" `THANK_YOU_PAGE`* - nie jest to miejsce bindowania, ale osadzenia widgetu, który powinien przyjąć dedykowaną formę Thank You Page po złożeniu zamówienia.
`max_width`	Określa maksymalną szerokość jaką ma zajmować widget. Uwaga: widget dostosowuje szerokość do kontenera, w którym się znajduje. Jeśli kontener nadrzędny będzie miał szerokość mniejszą niż max_width wtedy widget osiągnie wymiary kontenera nadrzędnego. Dobrym pomysłem jest stosowanie dodatkowego stylu css min-width bezpośrednio na `inpost-izi-button` co pozwoli uzyskać najlepsze efekty dopasowania. Przyjmuje wartości od 220 do 600.
`min_height`	Określa minimalną wysokość jaką ma zajmować widget. Powinien przyjmować wartości od 48 do 64.
`frame_style`	Opcjonalny parametr określający styl rogów ramki widgetu. Domyślnie widget jest prostokątny i jeśli chcemy aby nadal taki był należy nie podawać tego parametru. Dostępne wartości: rounded - małe zaokrąglenie round - duże zaokrąglenie.

Wyświetlanie w zależności od parametrów bindowania

O stanie bindowania informuje nas parametr basket_linked dostępny w API InPost. Jest to jedyny parametr wpływający na to w jaki sposób należy wyświetlić HTML widgetu. Jeśli basket_linked=true to w HTML umieszczamy parametr masked_phone_number.

iziGetPayData

Pobiera dane potrzebne do parowania koszyków. Parametry prefix oraz phoneNumber są nieobowiązkowe. Wywołania z 1 parametrem służą do pozyskania kodu qr. Wywołania z wszystkimi 3 parametrami służą do parowania przy pomocy numeru telefonu.
Uwaga!
Dla sytuacji, w której backend ma następujące dane:
browser_trusted = true
basket_linked = false
Backend powinien wykryć dostępny w Cookie klucz BrowserId i wykonać Basket PUT z obecnym BrowserId zamiast Binding POST.

W tej sytuacji nie wystąpi request zwrotny confirmation a poprawnymi danymi dla iziGetPayData będzie pusty array.

Backend:

Backend Merchanta może otrzymać wymagane dane poprzez odpytanie InPost zapytaniem: GET/v1/izi/basket/{basketId}/binding

API

Parametry	`prefix`- prefiks numeru telefonu `phoneNumber`- numer telefonu `bindingPlace`- miejsce bindowania
Zwraca	Promise
Wartość	dane z zapytania backend `GET/v1/izi/basket/{basketId}/binding`

async function iziGetPayData(prefix, phoneNumber, bindingPlace) {
return Promise.resolve({
qr_code: 'string',
deep_link: 'string',
deep_link_hms: 'string',
} || []);
}

Przykład implementacji:

Przykład odpowiedzi:

Dla zapytania bez numeru i prefixu:
{ "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABvUlEQVR4Xu2XsY3DMAxFaaRwmRG0ib2YAQvQYskmGsGlCyO8\/ynHuQRI+3MHRIVA66kgyE9SNn+37PXgWF\/yR0g2s7PXdcBmsZmdpKS4386lui9zheWweKYk4ZHDN3xfbK6r0VKTbKvZZLDKh8iWnJnqGSI9YX5yssFmXztnpn5nTkBCo4Ua3bdn9QpIrC0CEwrZT4QEvg1mqb8+LN5RkmSdt07hPESx3uMmI\/0NWWmBubBXdYdvGoLUXL11Chx6VGzzTUWiQU+2dgu2cTEEaxETVCdNhMj7G+4gREVKSu0v563JE20qJyhklhLUxhgyQVZAthQDREt6yhOboV3sRSMlyM8Y4oDFOxUT\/FCIhtRWFvAtNZlE3xSSjfnZEhxkfmxKrFgpKdQFHYzhzTrlHSUJjca0Rs8YWKfXx9yWkHi7wOLLAYdw8D6zdCTMnsrkG2K\/oyQxqVqdMj8RLCmJlVmnUCt94yNOSnL75p8Eq+RU12Oii0jhuNpsHdAuEKIo1pOWUKP8f+DMGlvR+AcIP5zzE2cfInyx1PCtveSUJJ4tNerU4w1h+9xWkUwzs0tPfLZgPalXQN6sL\/mv5AdSN8lx5hJUCgAAAABJRU5ErkJggg==", "deep_link": "inpost:\/\/izilinkuat?binding_id=7953a3fd-698a-477e-ae44-5f8f1d75fdab", "deep_link_hms": "inpost:\/\/izilinkuat?binding_id=7953a3fd-698a-477e-ae44-5f8f1d75fdab", "basketId": "c01d1182-e445-4846-7336-538ea71f8588" }
Dla zapytania z numerem telefonu i prefixem:
{"basketId":"c01d1182-e445-4846-7336-538ea71f8588"}

iziGetBrowserData

Funkcja zwraca informacje o przeglądarce w postaci obiektu lub zakodowanego Base64 stringu.

* możemy np. wykorzystać tą funkcję w iziGetPayData by przekazać dane przeglądarki jako dodatkowy parametr do backend

API

Parametry

base64 (boolean, opcjonalny): Określa, czy zwrócić dane jako zakodowany Base64 string. Domyślnie ustawione na false.

{ base64: true }

Zwraca

Obiekt zawierający dane przeglądarki lub zakodowany Base64 string z danymi przeglądarki.

Wartość

user_agent (string): Zawiera ciąg znaków reprezentujący agenta użytkownika przeglądarki.
description (string): Zawiera opis kodu aplikacji przeglądarki.
platform (string): Zawiera informacje o platformie przeglądarki.
architecture (string): Zawiera informacje o wersji aplikacji przeglądarki.

iziGetIsBound

Wywoływana po kliknięciu w niesparowany przycisk w celu sprawdzenia i nasłuchiwania czy parowanie przebiegło pomyślnie. Po stronie developera należy obsłużyć komunikację tak, żeby nie obciążać zbytnio serwera przez wykorzystanie websocket bądź long pooling.
Backend:
Backend Merchanta może otrzymać wymagane dane poprzez zapis danych otrzymanych od InPost w POST/v1/izi/basket/{backetId}/confirmation.

API

Parametry	brak
Zwraca	Promise
Wartość	Dane otrzymane od InPost Pay na zapytanie `POST/v1/izi/basket/{basketId}/confirmation`

Przykład implementacji z zastosowaniem long pooling:

iziGetOrderComplete

Metoda wywołana po sparowaniu koszyka i na każdej stronie z koszykiem już sparowanym. Nasłuchuje na zakończenie zamówienia w aplikacji bądź odświeżenia strony. W odpowiedzi dostajemy url strony typu thank you page z podziękowaniem za zakupy bądź informację o odświeżeniu strony. Backend powinien reagować na eventy z aplikacji i wysyłając tylko akcje jak refresh czy redirect.

Uwaga!
W celu wyświetlenia podziękowania InPost na stronie docelowej musi zostać osadzony <inpost-thank-you />

Backend:
Backend Merchanta po utworzeniu zamówienia na żądanie InPost POST/v1/izi/order i odesłaniu szczegółów zamówienia do InPost zwraca Promise.

API

Parametry	brak
Zwraca	Promise
Wartość	{ action: ‘redirect’ \| ‘refresh’ redirect?: ‘url’ }

iziBindingDelete

Metoda jest wywoływana podczas procesu odparowywania i służy do komunikacji z backendem systemu Merchanta w celu usunięcia informacji o poprzednio sparowanym numerze. Dzięki temu, użytkownik ma możliwość przeprowadzenia procesu parowania numeru od nowa. Jest to kluczowe dla zarządzania tożsamościami i zapewnia, że powiązania są aktualne i pozwalają na ponowną konfigurację w razie potrzeby.

Uwaga dla developera:

Funkcja iziBindingDelete zwraca Promise, ponieważ wykonuje asynchroniczną operację komunikacji z serwerem, aby zapewnić, że pewne operacje (takie jak czyszczenie ciasteczek i inne działania w głównym kodzie) są wykonywane dopiero po pomyślnym zakończeniu tej asynchronicznej operacji. Korzystam z metody .then(), dzięki temu mam pewność, że wszystkie działania zostaną wykonane w odpowiedniej kolejności, a cały proces jest bardziej przewidywalny i stabilny. Przy poprawnym wykonaniu iziBindingDelete ma jedynie sygnalizować pozytywne wykonanie zadania i w razie błędów przekazać error.

Backend:

Backend Merchanta może usunąć powiązanie w koszyku poprzez odpytanie InPost zapytaniem:

DELETE/v1/izi/basket/{basketId}/binding

API

Parametry	brak
Zwraca	Promise
Wartość	void

iziCanBeBound

Metoda określa czy produkt może zostać dodany do koszyka i sparowany. Wykorzystywane przy produktach wariacyjnych w celu określenia czy parametry produktu zostały już określone.

API

Parametry	`productId` - identyfikator produktu
Zwraca	Bool
Wartość	true \|\| false

iziAddToCart

Metoda iziAddToCart inicjuje proces dodawania produktu do koszyka. Jest wywoływana przed etapem parowania w celu zapewnienia, że koszyk nie jest pusty, umożliwia tym samym proces parowania. Należy zauważyć, że funkcja ta jest niezależna od widgetu i procesu parowania, jak również od interfejsu API. Jej głównym celem jest umożliwienie parowania poprzez zapewnienie, że koszyk nie jest pusty.

API

Parametry	`id` - identyfikator produktu
Zwraca	void
Wartość

inpost-update-count

Event, który pozwala nam na zaktualizowanie liczby produktów na przycisku. Event powinien być wywoływany w momencie dynamicznego dodawania produktów do koszyka (bez odświeżania strony).

API

Parametry	{ detail: count } // int
Zwraca
Wartość	{ detail: 1 }

Poniżej przykład implementacji:

iziMobileLink

Metoda wykorzystywana do pobierania deeplinku (dla już sparowanego koszyka) wykorzystywana do przechodzenia do aplikacji mobilnej.

Link powinien zostać wygenerowany po stronie backendu Merchanta.

InPost_basket_id otrzymujemy po sparowaniu z BA, więc powinniśmy zachować to id na czas sparowanego koszyka.

Backend:
Backend Merchanta może otrzymać wymagane dane poprzez zapis identyfikatora koszyka z API InPost (nie identyfikator koszyka Merchanta) z zapytania:
GET/v1/izi/basket/{basketId}/binding
oraz spreparowaniu linku zgodnie z pseudokodem:
switch (self::$environment) {
case self::ENVIRONMENT_PRODUCTION:
return 'inpost://izilink?basket_id=' + basketId;
case self::ENVIRONMENT_SANDBOX:
return 'inpost://izilinksandbox?basket_id=' + basketId;
default:
return 'inpost://izilinkuat?basket_id=' + basketId;
}

API

Parametry	brak
Zwraca	Promise
Wartość	{ link: ‘url’ }

Przykład implementacji:

Przykład odpowiedzi:

{ "link": "inpost:\/\/izilinkuat?basket_id=70db89ca-ad58-4863-8d95-0bdc9f75a3dc", }

SPA

Wtyczka przygotowana została z myślą o użyciu z aplikacjami SPA. W celu integracji sklepu z InPost Pay należy obsłużyć inicjowanie przycisku Pay w cyklu życia aplikacji.
Skrypt po pierwszym załadowaniu automatycznie inicjuje wszystkie znalezione w kodzie instancje <inpost-izi-button />. W celu inicjowania widgetu po aktualizacji DOM należy użyć metody:

Poniżej przykład dla komponentu ReactJs:

Istnieje tag wyświetlający podziękowanie za zakupy <inpost-thank-you /> . W celu inicjowania podziękowania po aktualizacji DOM należy użyć metody: window.handleThankYouNode();