Skip to main content

Prebuilt UI

Light offers optional prebuilt UI modules that allow you to easily integrate the Light platform into your website or mobile app using a webview or iframe, simplifying your integration and saving development time.

The prebuilt UI can be launched from your application with various scopes to fulfill flows like Enrollment or Billing, and is built entirely on the same APIs you can use directly.

Launching a prebuilt UI flow​

You can launch the prebuilt UI by opening a URL in a webview or iframe. To get a URL, call the POST /app/accounts/{account_id}/flow-login API endpoint. This returns a payload like the following:

{
  "login_link": "https://flow.light.dev/login?token=6277d9fb7b76832d1fc7545d4ed649d7",
  "scope": "enrollment",
  "expires_at": "2024-04-29T13:59:18.650Z"
}

You can then open the login_link in a webview or iframe to launch the flow.

<iframe
  src="https://flow.light.dev/login?token=1234"
  width="100%"
  height="100%"
  style="position: fixed; top: 0; left: 0;"
></iframe>

Scopes​

Each prebuilt UI flow has a specific scope that determines the flow that will be launched. Currently the only supported scope is enrollment, but more scopes will be added in the future. Reach out to us if you have a specific use case that you would like to see supported.

Scopes:

  • enrollment - Launches the prebuilt UI with the enrollment flow.
  • update-payment-method - Launches the prebuilt UI with the flow for having a user update their payment method.
  • documents - Launches the prebuilt UI with the user's documents.
  • billing - Launches the prebuilt UI with the user's invoices.

Listening for events​

The iframe or webview will emit events to the parent window when certain actions are taken. You can listen for these events to update your application state or take other actions. The events are emitted using the postMessage API.

Here is an example of how you can listen for events in your parent window with JavaScript:

window.addEventListener("message", function (event) {
  const eventType = event.data?.type;
  if (!eventType) {
    return;
  }
  if (eventType === "light-flow-close") {
    // TODO: remove the Light iframe or webview
  }
});

Event format​

  • type - The type of event, for example light-flow-close.
  • payload - The payload of the event, for example {}.

Event types​

light-flow-close - Emitted when the app is closed.

When you capture a close event, you can then close the iframe or webview in your application. We would recommend that you also refetch the account status to make sure that you have the latest information if needed.

Configuration​

The prebuilt UI has a default look and feel that is designed to be easy to use and integrate into your application. It can be minimally configured with things like logos, colors, and company name to match your brand. However, if you want a more customized flow or design you can use the APIs directly. Since the prebuilt UI uses the same APIs available to you, you can always start with parts of the prebuilt UI and then replace it with a custom UI as needed.