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 Name	When Raised	Event
PROVIDER_SELECTED	The user selected a provider.	{ “state”: “PROVIDER_SELECTED”, “providerId”: “1e5e0ffa-a557-de58-bb7f-22000b109b8b” }
PROVIDER_DESELECTED	The user clicked the back button to pick a different provider.	{ “state”: “PROVIDER_DESELECTED”, }
CREDENTIALS_ENTERED	The user entered credentials and is either seeing a progress spinner or a success or failure page.	{ “state”: “CREDENTIALS_ENTERED”, }
CHALLENGE_RESPONSE_REQUESTED	The 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_ENTERED	The user entered a response to the challenge.	{ “state”: “CHALLENGE_RESPONSE_ENTERED”, }
CREDENTIALS_VALID	The user’s credentials were confirmed to be valid.	{ “state”: “CREDENTIALS_VALID”, }
CREDENTIALS_INVALID	The user’s credentials were confirmed to be invalid. The user is taken back to try entering credentials again.	{ “state”: “CREDENTIALS_INVALID”, }
CHALLENGE_RESPONSE_INVALID	The user’s challenge response was invalid. The user is taken back to try entering credentials again.	{ “state”: “CHALLENGE_RESPONSE_INVALID”, }
SUCCESS	The user successfully linked a credential and is on the Success page.	{ “state”: “SUCCESS”, }
FAILURE	The 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.