Widget 2.0 [ENG]

Widget

InPost Pay widget is a JavaScript plugin that is embedded into a webpage by adding the following exemplary script:

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

Environments:

On this page:

1 Widget
2 Lifecycle notes
3 Specification
4 Widget placeholder
5 Sequence diagrams for InPost Pay and Widget 2.0

Lifecycle notes

There could be only one widget instance per page, since we offer only one kind of placeholder and widget can't distinguish and apply different configuration
It's up to merchant when to initialise the widget, depending when widget placeholder is added to DOM or configuration becomes available, so can be done at root level (as above) or can be deferred and called after some async actions
Widget's lifecycle:
1. right after initialisation, it'll retrieve its configuration from WidgetAPI for given merchantId
2. if basketBindingApiKey is provided as string or undefined - it'll make a call to Widget API to get basket binding status
3. if basketBindingApiKey is provided as promise - it'll first await for promise to resolve and only then make a call to Widget API to get basket binding status
4. once page is fully loaded and call to Widget API is made, it will check if any placeholder is present on the DOM and render the widget in appropriate state

Specification

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

To correctly position widget button(s), the following placeholder tag should be added to the webpage in the appropriate place(s) (near "Add to cart" button or "Checkout").

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

The placeholder supports the following attributes:

Parametrer	Required	Description	Additional remarks

Parametrer

Required

Description

Additional remarks

binding_place

yes

possible values are:

PRODUCT_CARD
BASKET_SUMMARY
ORDER_CREATE
BASKET_POPUP
THANK_YOU_PAGE
CHECKOUT_PAGE
MINICART_PAGE
REGISTERFORM_PAGE
LOGIN_PAGE

data-product-id

if binding_place=PRODUCT_CARD

variation

no

a list of styles, ie

"dark primary size-m rounded"

default:

"secondary size-l"

supported styles:

round - max border radius
rounded - border radius 8px, if together with 'round' - 'round' is used
dark - footer text is white
primary - widget background is yellow
forced size variations, if multiple is set, the lower size is consider with higher importance
- size-xs
- size-sm
- size-md
- size-lg
- size-xl

Widget 2.0 [ENG]

Widget

Lifecycle notes

Specification

Widget placeholder

Sequence diagrams for InPost Pay and Widget 2.0