Widget 1.0 (old version)
- Michał Machowski
- Joanna Wołosz
- Paweł Milewski
Nieaktualna wersja widgetu. Wersja zostanie wygaszona w Q1 2025. Prosimy nie instalować jej w nowych integracjach. Najnowsza wersja Widgetu znajduję się tu: Widget 2.0.
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
Pobranie skryptu
Skrypt wtyczki znajduje się pod adresem:
Środowisko | Link |
|---|---|
Sandbox | |
Produkcja |
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 |
|---|---|
| Imię kupującego, wypełnij jeśli koszyki są sparowane. |
| ID produktu, wymagane jeśli przy parowaniu chcesz dodać produkt o podanym id do koszyka. |
| Zamaskowany numer telefonu, wymagane jeśli koszyki są sparowane. |
| Wariant wyglądu przycisku. Zależnie od wyboru, przycisk może przyjąć różne style. Dostępne opcje: " Przykłady:
|
| Określa czy przycisk znajduje się na stronie koszyka. Dopuszczalna wartość “ |
| Określa tryb wyświetlania. Dopuszczalna wartość “   |
| Określa inicjalną liczbę produktów do wyświetlenia na przycisku po sparowaniu, (ilość produktów obecnie w koszyku).  |
| Określa miejsce, gdzie następuje bindowanie. Informacja ta trafia do
Dodatkowo na podstawie tego parametru kod rozpoznaje, którą wersję copy (tekstów i wyglądu) powinien zastosować.  Dla: “ 
|
| 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 |
| Określa minimalną wysokość jaką ma zajmować widget. Powinien przyjmować wartości od 48 do 64. |
| 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:
|
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 |
|
Zwraca | Promise |
Wartość | dane z zapytania backend |
async function iziGetPayData(prefix, phoneNumber, bindingPlace) {
return Promise.resolve({
qr_code: 'string',
deep_link: 'string',
deep_link_hms: 'string',
} || []);
}Przykład implementacji:
async function iziGetPayData(prefix, phoneNumber, bindingPlace) {
const url = 'http://example.com/endpoint';
const browserData = window.iziGetBrowserData({ base64: true });
const data = {
prefix: prefix || "",
number: phoneNumber || "",
browser: browserData,
binding_place: bindingPlace
};
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
});
if (!response.ok) {
throw new Error('Network response was not ok');
}
return response.json();
} catch (error) {
return {};
}
}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 |
|
Zwraca | Obiekt zawierający dane przeglądarki lub zakodowany Base64 string z danymi przeglądarki. |
Wartość |
|
const browserData = window.iziGetBrowserData({ base64: true });
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 |
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"
});
}Przykład implementacji z zastosowaniem long pooling:
let timeoutId; // Zmienna do przechowywania identyfikatora timeout
/**
* Obsługuje różne akcje serwera.
* @param {string} action - Typ akcji do wykonania.
* @param {Function} resolve - Funkcja rozwiązania obietnicy.
* @param {Function} reject - Funkcja odrzutu obietnicy.
*/
function handleServerAction(action, resolve, reject) {
if (timeoutId) {
clearTimeout(timeoutId); // Jeśli istnieje aktywny timeout, czyści
go.
}
switch (action) {
case 'close':
// Odrzuca obietnicę z błędem, jeśli serwer zwróci akcję "close"
reject(new Error("Połączenie zostało przerwane, spróbuj
ponownie."));
break;
case 'retry':
// Ustawia nowy timeout do ponownego ustawienia długiego
odpytywania, jeśli serwer zwróci akcję "retry"
timeoutId = setTimeout(() => setupLongPolling(resolve, reject),
1000);
break;
default:
break; // Dla innych akcji nie robi nic
}
}
/**
* Ustawia długie odpytywanie do serwera.
* @param {Function} resolve - Funkcja rozwiązania obietnicy.
* @param {Function} reject - Funkcja odrzutu obietnicy.
*/
async function setupLongPolling(resolve, reject) {
try {
// Wysyła zapytanie do serwera
const response = await
fetch(/wp-json/inpost/v1/izi/merchant/basket/confirmation);
const data = await response.json(); // Przetwarza odpowiedź na
format JSON
// Sprawdza odpowiedź od serwera i podejmuje odpowiednie działania
if (data?.phone_number) {
resolve(data); // Rozwiązuje obietnicę, jeśli otrzyma numer
telefonu
} else if (data?.action) {
handleServerAction(data.action, resolve, reject); // Obsługuje
akcje serwera, jeśli otrzyma akcję
} else if (data?.error_code) {
reject(new Error(data.error_code)); // Odrzuca obietnicę z
błędem, jeśli otrzyma kod błędu
} else {
// Jeśli nie otrzyma ani numeru telefonu, ani akcji, ani kodu
błędu, ustawia nowy timeout do długiego odpytywania
timeoutId = setTimeout(() => setupLongPolling(resolve, reject),
10000);
}
} catch (error) {
reject(error); // Odrzuca obietnicę z błędem w przypadku błędu
}
}
/**
* Funkcja, która korzysta z długiego odpytywania, aby dowiedzieć się,
czy jest związana z numerem telefonu.
* @returns {Promise} - Obietnica związana z odpowiedzią od serwera.
*/
async function iziGetIsBound() {
return new Promise((resolve, reject) => {
setupLongPolling(resolve, reject); // Uruchamia długie odpytywanie
});
}
export default iziGetIsBound; // Eksportuje funkcję jako domyślny
eksport
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’ } |
function iziGetOrderComplete() {
return Promise.resolve({
action: 'string'
redirect: 'string'
})
}
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 |
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.
API
Parametry |
|
|---|---|
Zwraca | Bool |
Wartość | true || false |
function iziCanBeBound(productId) {
return 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 |
|
|---|---|
Zwraca | void |
Wartość |
|
async function iziAddToCart(id) {
return void;
}
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:
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;}
API
Parametry | brak |
|---|---|
Zwraca | Promise |
Wartość | { |
function iziMobileLink() {
return Promise.resolve({
link: 'string'
})
}Przykład implementacji:
export default async function iziMobileLink() {
const url = "http://example.com/endpoint";
try {
const response = await fetch(url);
if (!response.ok) {
throw new Error('Network response was not ok');
}
const data = await response.json();
return data;
} catch (error) {
throw error;
}
}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:
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();