HomeGuidesAPI ReferenceChangelog
Log In
Guides

Integrating Utility Cloud Connect

Connect iframe can be easily embedded into any website. Once embedded, there are tools available to make the integration as seamless as possible.

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 (set by your customer support representative) needs to be set to the origin of the page that will contain the . If set correctly, Connect will emit events.

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

To set this URL, reach out to your customer support representative or email [email protected]

Event NameWhen RaisedEvent
PROVIDER_SELECTEDThe user selected a provider.{
“state”: “PROVIDER_SELECTED”,
“providerId”: “1e5e0ffa-a557-de58-bb7f-22000b109b8b”
}
PROVIDER_DESELECTEDThe user clicked the back button to pick a different provider.{
“state”: “PROVIDER_DESELECTED”,
}
CREDENTIALS_ENTEREDThe user entered credentials and is either seeing a progress spinner or a success or failure page.{
“state”: “CREDENTIALS_ENTERED”,
}
CHALLENGE_RESPONSE_REQUESTEDThe provider sent the user a challenge request. This could be to pick a contact method to receive an MFA code, or it could be the MFA code itself.{
“state”: “CHALLENGE_RESPONSE_REQUESTED”,
}
CHALLENGE_RESPONSE_ENTEREDThe user entered a response to the challenge.{
“state”: “CHALLENGE_RESPONSE_ENTERED”,
}
CREDENTIALS_VALIDThe user’s credentials were confirmed to be valid.{
“state”: “CREDENTIALS_VALID”,
}
CREDENTIALS_INVALIDThe user’s credentials were confirmed to be invalid. The user is taken back to try entering credentials again.{
“state”: “CREDENTIALS_INVALID”,
}
CHALLENGE_RESPONSE_INVALIDThe user’s challenge response was invalid. The user is taken back to try entering credentials again.{
“state”: “CHALLENGE_RESPONSE_INVALID”,
}
SUCCESSThe user successfully linked a credential and is on the Success page.{
“state”: “SUCCESS”,
}
FAILUREThe user failed to link a credential and is on a page with an error message. Includes reason field that indicates why it failed:
CAPTCHA
TIMEOUT
USER_ACTION_REQUIRED
UNKNOWN
{
“state”: “FAILURE”,
“reason”: “USER_ACTION_REQUIRED”
}

Supporting Multiple Origins

If you'd like to support multiple origins, first you will need to provide a whitelist of domains to your customer support representative or email [email protected].

After the domains have been whitelisted, you will then need to pass in a URL encoded origin as a URL parameter. See below for an example of what this would look like:

<iframe src="https://connect.urjanet.com/<Organization ID>?parentWindowAddress=https%3A//youraddresshere.com" width="1000" height="800"></iframe>

Error Messages for Iframe events

If the parentWindowAddress is set incorrectly, the browser console will display a message like this: Failed to execute 'postMessage' on 'DOMWindow': The target origin provided ('https://example.com') does not match the recipient window's origin ('https://example.net)))').
Verify that the parentWindowAddress contains the correct origin including the protocol. One way to find this is by opening the browser console on the page hosting the iframe, and then get the value of window.origin.

If there are multiple origins whitelisted but the parent window address was not passed in as a URL parameter, the browser console will display the following error message:
Connect: Multiple parentWindowAddresses are configured, so parentWindowAddress must be specified as a query param in the iframe src attribute.

If there are multiple origins whitelisted but the parent window address parameter that was passed in does not match any of the whitelisted domains, the browser console will display the following error message:
Connect: Multiple parentWindowAddresses are configured, but the specified parentWindowAddress query param "http://localhost:8002" does not match any of them.