Skip to main content

Integrate widget using iFrame and events

Working with iframe#

You can load widgets in an iframe, by giving the widgets' url as src.

<iframe src="https://sandbox-embed.oxlin.io/widget/add_connection"></iframe>

Some banks have prohibited the integration of their authentication website in iframe.

Redirection to the bank's website is inevitable when using a REDIRECT channel. Thanks to the addition of a query string parameter aspsp_callback_uri, the widgets resume the flow on a page of your choice. This paramater is Mandatory if widgets are loaded in an iframe, it must contain the URL which load the widgets.

Therefore, if user try to add a connection with a REDIRECT channel throw an iframe, you must provide to widgets both callback uri, with the aspsp_callback_uri and redirect_uri parameters.

  • aspsp_callback_uri represents the page on your application where you want to load widgets.
  • redirect_uri represents the page on your application where you want to be redirected when the widgets finish the process.
<iframe src="https://sandbox-embed.oxlin.io/widget/add_connection?aspsp_callback_uri=https://www.yourwebsite.com/display_iframe_page&redirect_uri=https://www.yourwebsite.com/your_redirect_uri"></iframe>

In the case we need a authentication in the bank website (REDIRECT channel definition), your main browser page will be redirected to the bank login page.

After the redirect flow, you'll be redirected to the aspsp_callback_uri you provided. This page have to recreate an iframe with widgets, exactly setted as above (with aspsp_callback_uri, again). The widgets will automatically rebuild the session.

Bank websites can't always be loaded in an iframe some because they have prohibited the integration of their authentication website in iframe.

An alternative to redirect URI to get events#

Working with redirect_uri parameter cannot be a solution to retrieve results and statuses if the service is meant to be used through iframes or popups.

As a consequence widget service provides a way to retrieve these information by dispatching events via the use of postMessage which enables cross-origin communication between window objects. See https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage for more info about the technology.

Whenever the service is supposed to redirect to a client url with a given set of results and statuses, it also dispatches events providing these information (even when no redirect_uri parameter is provided).

For example, when performing an 'Add Connection' flow within an Html iframe element, we make it possible for the parent window to be aware of the flow's result by adding an event listener on "message" events.

For a successful Add connection flow you can expect to get the following event data:

{
result: "created",
status: "success",
connection_id: "123456"
}

In the parent web application, subscribe to message events:

window.addEventListener("message", (e) => {
// e.data will contain the useful data
console.log(e.data)
})

When the flow ends the above will catch the event and output:

{
result: "created",
status: "success",
connection_id: "123456"
}