Widget Integration

Internationalization

The 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 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.link          callback url AS-IS. `https://example.com/callback?state=...e&code=...&success=true`
   * @param  {Object} event.data.query         query parameters
   * @param  {Object} event.data.query.state   customer provided state
   * @param  {Object} event.data.query.code    auth code to be exchanged for an access/refresh token
   * @param  {Object} event.data.query.success indicates if the flow was finished successfully
   * @param  {Object} event.data.query.abort   indicates if the flow was aborted by the user
   * @param  {Object} event.data.query.flow_id unique flow identifier as provided on flow initiation
   *
   */
  function receiveMessage(event) {
    ...
  }

The flow_id provided in the callback is identical to the id given in the response when the WidgetLink was originally created. It can be used in addition to or instead of the state parameter to identify a user flow on the client side.

The code parameter is only present on successful flows and provides an authorization code, that can be exchanged for an access token .

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 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 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 Widget is integrated in an iframe in an environment where programmatically opening a 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.

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

{
  link: "<WidgetLink.redirect_uri>?state=<state>&code=<code>&success=true&abort=false&flow_id=<widget-link-id>",
  query: {
    code: "<code>",
    state: "<state>",
    success: true,
    abort: false,
    flow_id: "<widget-link-id>"
  }
}

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

Erroneous flow iframe post message structure:

{
  link: "<WidgetLink.redirect_uri>?state=<state>&success=false&abort=false&flow_id=<widget-link-id>",
  query: {
    state: "<state>",
    success: false,
    abort: false,
    flow_id: "<widget-link-id>"
  }
}

If the flow is aborted by the user, the abort-flag will be set to true.