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/v2.1/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_url parameters.

• aspsp_callback_uri represents the page on your application where you want to load widgets.
• redirect_url 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/v2.1/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_url 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"
}

Events list

Some events are "Global", they can spread from any Widget. They are the first of the list below and have the value "Global" in the column "Widget name".

For example, the event that warns that the widget has been resized spreads regardless of the widget currently displayed.

Widget name	Event name	Description	Triggering	Properties
Global	resize	Returns the new widget size after a resize	on widget resize	{"innerWidth": int, "innerHeight": int, "outerWidth": int, "outerHeight": int}
Global	leave	This event is triggered when the user clicks on the cross to close the widget or when the window is closed	on click exit button	{"client_id": "uuidv4", "redirect_uri": "url", "closing_type": "Button
Global	redirect_to	This event is triggered when the browser will redirect on the redirect_uri	When user is redirected (change from a widget to another)	{"client_id": "uuidv4", "redirect_uri": "url"} + list of redirection parameters that depends of the parameters available (status, queue_id, connection_id ...)
Login	login_enter	When the login widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Login	login_submit_success	A visitor submits his information. He is successfully logged and will be redirected on redirect uri	on click "Next Step" button	{"client_id": "uuidv4", "user_id": "int", "email": "String"}
Login	login_submit_error	A visitor leaves the webview on login step. He will be redirected on partner redirect_uri or close container	on response error	{"client_id": "uuidv4", "error": "String", "email": "String"}
Signup	signup_enter	When the signup widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Signup	signup_submit_step_1	A visitor submits a valid email address. He goes on password + terms page	on click "Next Step" button	{"client_id": "uuidv4", "email": "String"}
Signup	signup_open_terms	A visitor opens the terms popin	on click terms and conditions link	{"client_id": "uuidv4"}
Signup	signup_submit_step_2_success	A visitor submits his password. Terms is necessarily checked to submit. The redirect_uri is necessarily the widget add_connection	on click "Next Step" button	{"client_id": "uuidv4", "terms": boolean}
Signup	signup_submit_step_2_error	A visitor submits his information. The server displays an error. It can be a connectivity error with server or an existing email	on response error	{"client_id": "uuidv4", "error": "String", "email": "String"}
Recover Password	recover_password_enter	When the recover password widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Recover password	recover_password_submit	A visitor submits his email to receive a recory password mail.	on click button	{"client_id": "uuidv4", "email": "String"}
Recover password	recover_password_error	An error occured when the user submits the recovery email.	on response error	{"client_id": "uuidv4", "error": "String", "email": "String"}
Choose bank	choose_bank_enter	When the choose bank widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Choose bank	choose_bank_loading_error	This event is triggered when the list of bank can not be loaded	on response error	{"client_id": "uuidv4", "error": "String", "user_id": int}
Choose bank	choose_bank_selected	This event is triggered when the user select a bank and click on next step button	on click "Next Step" button	{"client_id": "uuidv4", "user_id": int, "bank_id": int, "bank_name": "String", "bank_branch_name": "String"}
PSD2 Consent	psd2_consent_authorize_url_success	This event is triggered after authorized url is requested	on response success	{"client_id": "uuidv4", "user_id": "int", "bank_id": "int", "bank_name": "String", "bank_branch_name": "String", channel_definition_id: "int"}
PSD2 Consent	psd2_consent_authorize_url_failure	This event is triggered after authorized url is requested	on response error	{"client_id": "uuidv4", "user_id": "int", "bank_id": "int", "bank_name": "String", "bank_branch_name": "String", channel_definition_id: "int"}
Bank login	bank_login_credential_enter	When the bank login widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Bank login	bank_login_credential	We send this event for each credentials when the user click on next step button	on click "Next Step" button	{"client_id": "uuidv4", "user_id": int, "credential_id": int, "credential_type": "String (PWD, DOB**)", "credential_label": "String"} PWD = Password, **DOB = Date of birth
Synchronization	synchronization_enter	When the synchronization widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Synchronization	synchronization_start	This event is triggered at the start of the synchronization when the users enter.	when the synchronization loads	{"client_id": "uuidv4", "user_id": int, "started_at": timestamp, "captive": boolean}
Synchronization	challenge_enter	When the user encounter a challenge, he is sent on a page that asks him to act (confirm send challenge, challenge value). We want to track all challenges	when the challenge loads	{"client_id": "uuidv4", "user_id": int, "credential_id": int, "credential_type": "String (PWD*, DOB**)", "credential_label": "String"}
Synchronization	synchronization_success	When synchronization finish with success	when the success container loads	{"client_id": "uuidv4", "user_id": int, "ended_at": timestamp, "duration_time": float, "status": "String", "queue_id": "String"}
Synchronization	synchronization_error	When synchronization finish with failure	when the error container loads	{"client_id": "uuidv4", "user_id": int, "ended_at": timestamp, "duration_time": float, "event_status": "String", "error": "String"}
Consent	consent_enter	When the consent widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Consent	consent_submit_success	The user accept consent (or close the window) and we send this event with the list of asked scopes	on click "Next Step" button	{"client_id": "uuidv4", "user_id": "int", "scopes": "String", "authorization": boolean}
Consent	consent_submit_error	An error occurend when the user authorizes issuer to send data to partners	on response error	{"client_id": "uuidv4", "user_id": "int", "scopes": "String", "error": "String"}
Consent	consent_for_accounts_success	The user gives consent for selected accounts	on submit button click	{"client_id": "uuidv4", "user_id": "int", "queue_id": "String", "connection_id": "String", "channel_definition_id": "int"}
Consent	consent_for_accounts_failure	The user gives consent for selected accounts and an error occures	on submit button click	{"client_id": "uuidv4", "user_id": "int", "queue_id": "String", "connection_id": "String", "channel_definition_id": "int"}
Terms and conditions	terms_conditions_enter	When the terms and conditions widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Terms and conditions	terms_conditions_submit_success	The user accepts terms and authorize data sharing	on click "Next Step" button	{"client_id": "uuidv4", "user_id": "int", "accept_terms": boolean, "authorize": boolean}
Terms and conditions	terms_conditions_submit_error	An error occurend when the user accepts terms and conditions and it fails	on response error	{"client_id": "uuidv4", "user_id": "int", "accept_terms": boolean, "authorize": boolean, "error": "String"}
Terms and conditions	terms_conditions_open_terms	A visitor opens the terms popin.	on click terms and conditions link	{"client_id": "uuidv4"}
Professional account	professional_account_enter	When the professional account widget is opened	on load	{"client_id": "uuidv4", "user_id": "int, optional"}
Professional account	professional-account-list-loaded	When the professional accounts list is loaded	on load	{"client_id": "uuidv4", "user_id": "int", "list": array or accounts}
Professional account	professional-account-current-item	When rendering an account item form	on load	{"client_id": "uuidv4", "user_id": "int", "account_id": "String"}
Professional account	professional-account-submit-success	Whenever post information about an account succeeds	on click	"Next Step" button
Professional account	professional-account-submit-error	Whenever post information about an account fails	on click "Next Step" button	{"client_id": "uuidv4", "user_id": "int", "account_id": "String", "firstname": "String", "lastname": "String", "identification_number": "String", "type": "String", "optin": boolean, "error": "String"}
Professional account	professional-account-process-end	When process is over	on load	{"client_id": "uuidv4", "user_id": "int"}
Professional account	professional-account-handle-user-info	When first name and last name screen is displayed	on load	{"client_id": "uuidv4", "user_id": "int", "firstname": "String", "lastname": "String"}
Professional account	professional-account-handle-user-info-submit-success	When user changes profile info firstname and/or lastname	on click "Next Step" button	{"client_id": "uuidv4", "user_id": "int", "firstname": "String", "lastname": "String"}