You can embed Bayou’s customer onboarding form on your website using the Bayou JS library, which embeds the contents within an iframe. Here's an example of how the form appears when embedded on a page with a light gray background. "Electric City Solar" is our example company, so their logo is shown at the top left.

Customize the appearance of the embedded component

The company name, logo, button color, and background color of the customer experience can be customized within the settings page of Bayou's dashboard.

• Company name: If you haven't already, modify the Company name to what you would want the customer to see when connecting their utility account
• Company color: The company color allows you to customize the button color within the form. Input your color's hex number or pick from the available options.
• Company logo: This will replace the Bayou logo at the top of the form with your own logo. JPG and PNG file types are supported.
• Form background color: this controls the background color of the iframe in which the bayou embedded component is hosted. Set it to match the color of the hosting page for a more seamless look.

Implementing the embedded component

To include and initialize the library, add the following line to your pages:

<script src="https://js.bayou.energy/v1"></script>

📘

This is version 1 of the embedded component, reflected by v1 in the above code. Do not confuse this with v2.0 and v1.0 of Bayou's API.

Next, in your JavaScript code, add the following lines of code:

Bayou.loadOnboardingForm(  
 document.getElementById("\<your_element>"),  
"\<your_company_id>", // Found in your company settings: https://bayou.energy/dashboard/settings 
"\<onboarding_token>", // Generated using this API call: https://docs.bayou.energy/v2.0/reference/get_customers-id 
 (event) => { 
   if (event.type === "customerHasAuthenticated") {
      alert("Customer has authenticated")
  }
   else if(event.type === "customerEnteredInvalidCredentials") { 
     alert("Customer entered invalid credentials") 
   }
   else if(event.type === "customerEnteredInvalidMFAChallenge") {
     alert("Customer entered invalid MFA challenge") 
   }
 }  
 )

📘

In the above JavaScript code snipped, replace

<your_element> with the identifier of the HTML element which will contain the onboarding form

<your_company_id> with the ID of your company, which you can find on the Settings page of your Bayou Dashboard

<onboarding_token> with the onboarding token for the current customer, which is generated by creating a customer. See the customer creation API for more info -- the token is returned in the onboarding_token field.

The last parameter of the function is a callback function which will be called once your customer has reached the end of the onboarding form, with one of the following objects passed as its first parameter:

{ type: "customerHasAuthenticated" },
{ type: "customerEnteredInvalidCredentials"},
{ type: "customerEnteredInvalidMFAChallenge"},
{ type: "bayouCustomerFinishedOnboarding" }

🚧

Note on bayouCustomerFinishedOnboarding

Bayou still supports a now deprecated event type "bayouCustomerFinishedOnboarding", but it is not recommended to use this type. It functionally works the same as "customerHasAuthenticated"

We advise you to check the type of the event as we might add more types in the future. The event is functionally identical to the customer_has_filled_credentials webhook.

By default the form is laid out as if it were the whole page, so make the element you pass toloadOnboardingForm fill the browser window, for example with width: 100%; height: 100dvh;. If you want the form in a smaller box on your page instead, see the fitToFrame option below.

Fit the form to its frame (optional)

By default, the form leaves space around itself as if it was hosted on its own web page: 96px above and below on desktop, and centered vertically on phones. If you have sized the hosting element yourself and want the form to use that space, pass an options object with fitToFrame: true as the fifth argument:

Bayou.loadOnboardingForm(
  document.getElementById("<your_element>"),
  "<your_company_id>",
  "<onboarding_token>",
  (event) => { /* your callback, as described above */ },
  { fitToFrame: true } // <== optional parameter to fit to frame
)

With fitToFrame turned on:

• The form sits 16px from the top and bottom of the iframe, on desktop and on phones.
• The form switches to its desktop layout once the iframe is at least 470px wide. Without the option it switches at 768px, which means a 500px-wide iframe normally gets the phone layout.

The option only changes what happens inside the iframe. Nothing on your page moves. Leaving it out, or setting it to false, keeps the form exactly as it is today.

Error Handling

The embedded component now throws detailed errors when invalid parameters are provided:

• InvalidElementError: The provided element is not a valid HTML element.
• CompanyIdMissingError: The companyId is missing.
• CompanyIdNotAnInteger: The companyId is not a number.
• OnboardingTokenMissingError: The onboardingToken is missing.
• InvalidOnboardingTokenError: The onboardingToken is not a valid string or appears to be an onboarding link.
• InvalidOnboardingTokenFormatError: The onboardingToken does not match the expected format.

Ensure your implementation correctly handles these errors to prevent unexpected failures.

🚧

If you are testing the embedded component in your local environment, remember that not all browsers will simply open a local file rendering the component.

Firefox should open and render the component locally without any issues but Safari and Chrome may require a local url: (for example: http://localhost:XXXX or http://localhost:8000