Widget Integration

Internationalization

The Customizable Widget supports internationalization. Localization defaults to German de when a locale isn't specified or supported. It does not attempt to read user's machine language preference i.e. Accept-Language header. You as a partner have to explicitly instruct it which language to display when initiating the flow by setting the language key in the request.

Browser Support

The Customizable Widget supports Internet Explorer 11, Edge, Chrome, Firefox and Safari.

🚧

Due to Internet Explorer's technical restrictions, iframe Integration is not supported. If your application requires Internet Explorer 11 support, you must integrate it by opening the link you get from ShieldToken service on top-level.

iframe Integration

The iframe integration works the same way as if you opened the link on top-level. The noticeable difference being that instead of a URL callback, a message will be posted to the iframe parent.

  <iframe src="{WidgetLink.location}"></iframe>

  window.addEventListener('message', receiveMessage, false);

  /**
   * postMessage listner
   *
   * @param  {event}  event
   * @param  {Object} event.data            payload of the `postMessage` event
   * @param  {String} event.data.location   callback url AS-IS. `https://example.com/callback?state=state&code=code`
   * @param  {Object} event.data.query      query parameters. `{ state: "state", code: "code" }`
   * @param  {String} event.data.url        callback url without the query parameters. `https://example.com/callback`
   *
   */
  function receiveMessage(event) {
    ...
  }

For development purposes, the following domains are whitelisted for iframe integration:

• http://127.0.0.1
• https://127.0.0.1
• http://localhost
• https://localhost

All ports are allowed on the whitelisted domains.

📘

The Customizable Widget does not listen to any post messages from any source even if the receiver of the message uses event.source.postMessage to post back a message.

iframe integration and URL callback are mutually exclusive. On iframe integration a, callback will be made via postMessage API. On redirect integration, a specified URL callback endpoint will be called.

Details on postMessage can be found on MDN.

Native / Mobile App Integration

When integrating the Customizable Widget inside a native app, it's highly recommended to integrate it by opening the link location you get on flow initiation service on top-level (browser or WebView) instead of in an iframe.

If the Customizable Widget is integrated in an iframe in an environment where programmatically opening new tab isn't possible i.e. WebView, it won't be able to complete redirect challenges.

Error handling

In the case where an error has occurred, redirect_uri provided in Widget link will be called with a query parameter success=false.

Customizable Widget users can cancel the process at any time and return to partner's application. If a user has canceled a process, it is considered an erroneous state as no authorization code will be included in the callback.

Successful flow callback structure: <WidgetLink.redirect_uri>?state=<state>&code=<code>&success=true

Successful flow iframe post message structure

{
  location: "<WidgetLink.redirect_uri>?state=<state>&code=<code>&success=true",
  query: {
    code: "<code>",
    state: "<state>",
    success: "true"
  },
  url: "<WidgetLink.redirect_uri>"
}

Erroneous flow callback structure: <WidgetLink.redirect_uri>?state=<state>&success=false

Erroneous flow iframe post message structure:

{
  location: "<WidgetLink.redirect_uri>?state=<state>&success=false",
  query: {
    state: "<state>",
    success: "false"
  },
  url: "<WidgetLink.redirect_uri>"
}