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"/>
</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, w celu jej uzyskania należy wysłać zgłoszenie na adres integracjapay@inpost.pl.

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

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 widżetu 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.
   * 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://api.inpost.pl will be used as a fallback.
   */
  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

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

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.