Widget 2.0

Widget

Widget InPost Pay, to wtyczka JavaScript, która zostaje osadzona na stronie poprzez dodanie skryptu jak w poniższym przykładzie:

<html>
<head>
  <script src="https://inpostpay-widget-v2.inpost.pl/inpostpay.widget.v2.js"></script>
</head>
<body>
<script type="application/javascript">
  const widgetOptions = {
    merchantClientId: 'b73ca9fc-0123-4567-8912-5ac02c6af6e9',
    basketBindingApiKey: 'QdMW9xtB9POfNG7GiGIO4EFPEKSvzOuW',
    unboundWidgetClicked: (productId) => new Promise()
  };
  const widget = InPostPayWidget.init(widgetOptions);
</script>
...
<inpost-izi-button data-product-id="123" binding_place="PRODUCT_CARD" variation="..." ></inpost-izi-button>
...
</body>

Środowisko:

Merchant Client Id jest wartością nadawaną przez InPost.

Prod - wartość Merchant Client Id dla środowiska produkcyjnego można uzyskać w panelu merchanta korzystając z instrukcji Konfiguracja konta Merchanta - środowisko produkcyjne.
Sandbox - w celu otrzymania wartości dla środowiska Sandbox należy wysłać zgłoszenie na integracjapay@inpost.pl.

Domyślnie wywołanie Widgetu 2.0 możliwe jest z domeny, która jest zdefiniowana na koncie merchanta jako home page. W przypadku, gdy merchant wykonuje wywołanie widgetu z innej domeny konieczne jest dodanie odpowiedniego adresu url jako custom origin. W tym celu należy wysłać zgłoszenie na integracjapay@inpost.pl w treści wskazując odpowiedni adres url.

Na tej stronie:

1 Widget
2 Informacje dotyczące użytkowania
3 Specyfikacja
4 Widget placeholder
5 Diagramy sekwencji dla InPost Pay oraz Widget 2.0

Chcesz testować na środowisku lokalnym?

W celu zapewnienia zdalnego dostępu do środowiska lokalnego, konieczne jest zastosowanie dodatkowego rozwiązania w postaci tunelowania ruchu z publicznej domeny na lokalny adres. Bez takiego obejścia nie ma możliwości bezpośredniego połączenia się z lokalnym środowiskiem.
Rekomendowane rozwiązanie
Aktualnie zalecanym narzędziem jest ngrok, który umożliwia szybkie skonfigurowanie tunelu między publicznym adresem URL a lokalnym środowiskiem. Wystarczy darmowe konto, które zapewnia jedną stałą domenę publiczną. Ta domena może przekierowywać ruch do lokalnej aplikacji lub zamkniętego środowiska testowego.
Wymagania
Po utworzeniu darmowej domeny publicznej należy przekazać jej adres w formularzu Kontakt -> Sandbox, aby otrzymać credentiale i cały ruch testowy mógł być kierowany na ten adres.

Informacje dotyczące użytkowania

Może istnieć tylko jedna instancja widgetu na stronę, ponieważ oferujemy tylko jeden rodzaj placeholderu, a widget nie może rozróżniać i stosować różnych konfiguracji.
Od merchanta zależy, kiedy zainicjować widget, w zależności od tego, kiedy placeholder widgetu zostanie dodany do DOM lub konfiguracja stanie się dostępna, więc można to zrobić na poziomie głównym (jak powyżej) lub można odłożyć i wywołać po niektórych akcjach asynchronicznych.
Opis działania widgetu:
1. Bezpośrednio po inicjalizacji widget pobierze swoją konfigurację z WidgetAPI dla danego merchantId.
2. Jeżeli basketBindingApiKey jest podany jako string lub niezdefiniowany, to widget wykona wywołanie do Widget API w celu uzyskania statusu powiązania koszyka.
3. Jeżeli basketBindingApiKey jest dostarczony jako promise, to widget najpierw będzie oczekiwać na rozwiązanie promise, aby następnie wykonać połączenie do Widget API w celu uzyskania statusu powiązania koszyka.
4. Gdy strona zostanie w pełni załadowana i zostanie wykonane wywołanie Widget API, wówczas widget sprawdzi, czy w DOM znajduje się jakikolwiek placeholder i wyrenderuje widget w odpowiednim stanie.

Specyfikacja

export type BasketBindingApiKey = undefined | string | Promise<string>

export type WidgetBasketEvent =
  | 'basketDeleted'
  | 'basketProductChanged'
  | 'orderCreated'

export type WidgetBasketEventHandler = (
  event: WidgetBasketEvent,
) => boolean | Promise<boolean>

export interface WidgetInitOptions {
  /**
   * Merchant Client Id.
   */
  merchantClientId: string
  /**
   * Unique basket binding API key - it's obtained from InpostPay API.
   * If it's known at the page render: can be provided as string.
   * If it can be resolved during page load: can be a promise.
   * Otherwise: 'undefined', widget will assume that basket is not bound, because it can't check basket binding status without knowing api key.
   * And in such case, it's mandatory for 'unboundWidgetClicked' to return a 'apiKey', otherwise baskets can't be bound.
   */
  basketBindingApiKey: BasketBindingApiKey
  /**
   * This callback function is mandatory for unbound basket and for binding_place=PRODUCT_CARD.
   * When the promise is rejected with Error('UNDELIVERABLE_PRODUCT') widget won't show error popup or binding popup.
   * It'll be called to add the product to merchant's basket when user clicks on the widget.
   * @return promise with 'basketBindingApiKey'
   */
  unboundWidgetClicked?: (productId?: string) => Promise<string>
  /**
   * Callback function to reflect basket updates on merchant's page.
   * If not provided or returning false - widget will refresh the entire page.
   * @return 'true' if widget should not refresh the page.
   */
  handleBasketEvent?: WidgetBasketEventHandler
  /**
   * Widget-API base url used for frontend to API communication.
   * By default, https://inpostpay-widget-api.inpost.pl is used.
   */
  apiBaseUrl?: string
  /**
   * If set to true BrowserId will be persisted and read from localStorage.
   * If set to true the app will always try to open a https deep link, if false the deep link url
   * will be deducted based on the UserAgent.
   * Default: false
   */
  webView?: boolean
  /**
   * Custom language. By default, widget will use browser's language and 'pl' as fallback
   */
  language?: string
}

export interface InPostPayWidget {
  refresh: (options?: Partial<WidgetInitOptions>) => void
}

export interface InPostPayWidgetNamespace {
  init: (options: WidgetInitOptions) => InPostPayWidget
}

declare global {
  export interface Window {
    InPostPayWidget: InPostPayWidgetNamespace
    __INPOST_PAY_WIDGET__?: InPostPayWidget
  }
}

declare function initialiseInpostPayWidget(
  options: WidgetInitOptions,
): InPostPayWidget

Widget placeholder

Aby prawidłowo osadzić przyciski widgetu, poniższy kod powinien zostać umieszczony na stronie w odpowiednim miejscu (pod przyciskiem “Dodaj do koszyka” lub przy przejściu do zamówienia)

<inpost-izi-button data-product-id="" binding_place="" variation="" ></inpost-izi-button>

Placeholder obsługuje następujące parametry:

Parametr

Wymagany

Opis

Dodatkowe informacje

binding_place

Tak

możliwe wartości:

PRODUCT_CARD
BASKET_SUMMARY
ORDER_CREATE
BASKET_POPUP
THANK_YOU_PAGE
CHECKOUT_PAGE
MINICART_PAGE
REGISTERFORM_PAGE
LOGIN_PAGE

data-product-id

Tak, jeżeli binding_place=PRODUCT_CARD

variation

Nie

Lista styli, tj.

"dark primary size-m rounded"

Domyślnie:

"secondary size-l"

Dostępne style:

round - maksymalne zaokrąglenie ramki widgetu
rounded - średnie zaokrąglenie ramki widgetu (border radius 8px). Jeżeli wskazano razem z “round”, wtedy “round” zostanie zastosowany.
dark - tekst pod przyciskiem w białym kolorze
primary - żółty kolor widgetu
predefiniowane rozmiary widgetu (jeżeli wskazano więcej niż jeden, wtedy mniejszy rozmiar ma większy priorytet):
- size-xs
- size-sm
- size-md
- size-lg
- size-xl

W celu wyświetlenia "InPost Thank You Page" na stronie z podziękowaniem za zamówienie w odpowiednim miejscu należy osadzić <inpost-thank-you></inpost-thank-you>.

Diagramy sekwencji dla InPost Pay oraz Widget 2.0

W poniższych artykułach zostały zawarte diagramy sekwencji dla InPost Pay oraz Widget 2.0.