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.

Do poprawnej integracji wymagane jest dostarczenie warstwy https://dokumentacja-inpost.atlassian.net/wiki/spaces/PL/pages/158728206, osadzenie html wtyczki, oraz sterowanie stanem warstwy frontend poprzez dostarczenie opisanych poniżej metod.

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

● iziGetBindingData
● 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 iziGetBindingData (deprecated)
4 iziGetPayData
5 iziGetBrowserData
6 iziGetIsBound
7 iziGetOrderComplete
8 iziBindingDelete
9 iziCanBeBound
10 iziAddToCart
11 inpost-update-count
12 iziMobileLink
13 SPA

Pobranie skryptu

Skrypt wtyczki znajduje się pod adresem:

Środowisko	Link

Środowisko	Link
Sandbox	https://izi-sandbox.inpost.pl/inpostizi.js
Prod	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. Do wyboru “`secondary`" bądź "`primary`".
`basket`	Określa czy przycisk znajduje się na stronie koszyka. Dopuszczalna wartość “`true`".
`dark_mode`	Określa tryb wyświetlania. Dopuszczalna wartość “`true`".
`count`	Określa inicjalną liczbę produktów do wyświetlenia 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 `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.

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

O stanie bindowania informuje nas parametr basket_lnked 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.

iziGetBindingData (deprecated)

Metoda zostanie wkrótce usunięta. Prosimy o implementację 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.

Parametry

id - identyfikator produktu
prefix - prefiks numeru telefonu
phoneNumber - numer telefonu

bindingPlace - miejsce bindowania

Zwraca

Promise

Wartość

Dane z zapytania backend basket-app/api/v1/izi/basket/{basketId}/binding

function iziGetBindingData(id, prefix, phoneNumber, bindingPlace)
{
return Promise.resolve({
qr_code: 'string',
deep_link: 'string',
deep_link_hms: 'string',
});
}

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 GET.

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

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

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

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

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.

const browserData = window.iziGetBrowserData({ base64: true });

iziGetIsBound

Wywoływana po wyświetleniu qr code bądź deep link w celu sprawdzenia, 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.

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

function iziGetIsBound() {
return Promise.resolve({
"phone_number": {
"country_prefix": "string",
"phone": "string"

},
"browser": {
"browser_trusted": boolean,
"browser_id": "string",
},

"name": "string",
"surname": "string"
"masked_phone_number": "string"
});
}

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

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

function iziGetOrderComplete() {
return Promise.resolve({
action: 'string'
redirect: 'string'
})
}

iziBindingDelete

Metoda wywoływana przy usuwaniu parowania.

Parametry	brak
Zwraca	Promise
Wartość	void

function iziBindingDelete() {
return Promise.resolve();
}

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.

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

function iziCanBeBound(productId) {
return true || false;
}

iziAddToCart

Metoda wykorzystywana do dodania produktu po kliknięciu w widget. Produkt zostanie dodany tylko wtedy, kiedy parametr data-product-id" jest wypełniony.

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

async function iziAddToCart(id) {
return void;
}

inpost-update-count

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

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

Poniżej przykład implementacji:

jQuery(document.body).on(eventName, () => {
const countContainer = document.getElementById(elementID);
if (!countContainer) return;
const count = parseInt(countContainer.textContent.trim(), 10);
if (isNaN(count)) return;
const event = new CustomEvent("inpost-update-count", { detail: count
});
const iziButtonsCollection =
Array.from(document.getElementsByTagName("inpost-izi-button"));
iziButtonsCollection.forEach(el => el.dispatchEvent(event));
});

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;
}

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

function iziMobileLink() {
return Promise.resolve({
link: 'string'
})
}

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:

window.handleInpostIziButtons();

Poniżej przykład dla komponentu ReactJs:

import React, { useEffect } from "react";
import { useLocation } from "react-router-dom";

export...= ({ children }) => {
const location = useLocation();
useEffect(() => {
window.handleInpostIziButtons();
}, [location]);
return <>{children}</>;
};

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();