Integrate Connect
Developer guidance on how to embed Connect into a website or email using HTML
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).
Sandbox
If you would like to embed the iframe on a webpage in the sandbox environment for the purposes of testing automation, the iframe src would simply include the?apiMode=sandbox
parameter:
<iframe src="https://platform-connect.arcadia.com/{org.uniqueId}?apiMode=sandbox" width="800" height="800">
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 Name | When Raised |
---|---|
onStart | The user opened Connect. |
onCredentialsSubmitted | The user entered credentials and is either seeing a progress spinner or a success or failure page. |
onEnd | The user reached the terminal state of Connect after submitting credentials. |
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:
- User opens Connect
- Connect emits the
onStart
event:
{
"type": "onStart"
}
- User selects their provider and submits their username and password
- Connect emits the
onCredentialsSubmitted
event, which includes the created credential's ID:
{
"type": "onCredentialsSubmitted",
"payload": {
"utilityCredentialId": "1f016f9c-9185-dce1-bae8-327551dedbe2"
}
}
- The Arcadia platform validates the credential successfully, and the user sees the Connect end screen.
- 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);
}
});
Updated 3 days ago