Integrate Connect

iframe HTML

To embed the iframe onto a webpage or email, populate your organization's unique ID-based Connect URL from the Dashboard's Connect settings page into an iframe HTML element:

<iframe src="https://platform-connect.arcadia.com/{org.uniqueId}" width="800" height="800">

You can also use an encoded Connect URL as the src to create credentials with a provided Correlation ID and createdBy username (https://docs.arcadia.com/reference/generate-encoded-arcadia-connect-url).

iframe events

The Connect iframe now supports cross-window communication, which means the iframe emits events indicating where the user is in the process of linking a credential. To enable iframe events, the iframe origin field must be set as a query parameter on the iframe src URL.

iframe origin

For example, if the page hosting the iframe is https://subdomain.example.com/campaign/1, the origin would be "https://subdomain.example.com" and the iframe src URL would be

<iframe src="https://platform-connect.arcadia.com/{org.uniqueId}?origin=https://subdomain.example.com" width="800" height="800">

iframe event descriptions

Event schemas

The events' data field is a JavaScript object in the following formats:

{
  "type": "onStart"
}

{
  "type": "onCredentialsSubmitted",
  "payload": {
    "utilityCredentialId": string
  }
}

{
  "type": "onEnd",
  "payload": {
    "status": "LOGIN_SUCCESS"
  }
}

{
  "type": "onEnd",
  "payload": {
    "status": "PENDING"
  }
}

The status in the onEnd event will only be LOGIN_SUCCESS if the provider supports real-time credential validation and Arcadia successfully validates the credentials within 1 minute. It will be PENDING if the provider does not support real-time credential validation or Arcadia could not determine the credentials' validity within 1 minute.

If you do not receive the onEnd event, then the user did not make it to the end screen of Connect. This can happen if they input invalid credentials that Arcadia verifies as invalid within 1 minute. The reason this does not emit an onEnd event is because the user is prompted to input their credentials again when this happens.

Example scenario

Here is a simple example scenario for a user successfully submitting a credential:

1. User opens Connect
2. Connect emits the onStart event:

{
  "type": "onStart"
}

3. User selects their provider and submits their username and password
4. Connect emits the onCredentialsSubmitted event, which includes the created credential's ID:

{
  "type": "onCredentialsSubmitted",
  "payload": {
    "utilityCredentialId": "1f016f9c-9185-dce1-bae8-327551dedbe2"
  }
}

5. The Arcadia platform validates the credential successfully, and the user sees the Connect end screen.
6. Connect emits the onEnd event, which includes the credential status:

{
  "type": "onEnd",
  "payload": {
    "status": "LOGIN_SUCCESS"
  }
}

Receiving events

This is a basic example of how to listen to events emitted by the Connect iframe.

window.addEventListener('message', function(event) {
  if (event.origin === 'https://platform-connect.arcadia.com') {
    console.log('Message received from Connect iframe:', event.data);
  }
});