Skip to main content

Get started with the quickstart

In the quickstart, we'll show you how to:

  • Set up a sandbox app and get app credentials in the Light dashboard
  • Use the API and an embedded flow (prebuilt UI) to let customers enroll in your power plan
  • Verify customers are able to enroll

Prerequisites​

1. Set up a sandbox app and get app credentials in the Light dashboard​

  1. Log in to the Light dashboard
  2. On the Apps page, create a new app that uses the sandbox environment
  3. Select the app you just created and go to API Keys from the sidebar
  4. Create a new API key and store the AppToken somewhere for later

We now have an AppToken that can be used on all requests for authentication. An additional customer AccountToken is needed to complete actions on behalf of the customer, but that's not needed in this quickstart.

warning

Make sure you keep your AppToken a secret and only use it on the server side of your project to hide it from users. See how we use Next.js serverside app requests to protect our AppToken in our our example app. If you want to make requets directly from your client, look into the AccountToken. Learn more

2. Create user's Light Account​

Before showing the embedded enrollment flow, we need a customer's Light account. Create an account by sending a POST to /v1/app/accounts:

tip

In a real situation, you should save the customer's account_uuid to your own database and avoid creating duplicate accounts on Light.

3. Launch embedded flow​

Then, we need to get a URL that includes the enrollment flow's prebuilt UI. We can use the uuid in the last request's response to get a URL specific to your current customer. We place that uuid as the account_uuid in a POST to /v1/app/accounts/{account_uuid}/flow-login:

4. Surface enrollment flow at the right moment​

The enrollment flow is usually displayed after a user clicks a button or navigates to another page within an iframe or webview. Display the flow in an iframe or webview:

import React from "react";

interface FlowIframeProps {
  url: string;
}

const FlowIframe: React.FC<FlowIframeProps> = ({ url }) => {
  return (
    <div
      style={{
        position: "fixed",
        top: 0,
        left: 0,
        right: 0,
        bottom: 0,
        zIndex: 9999,
      }}
    >
      <iframe
        src={url}
        style={{ width: "100%", height: "100%", border: "none" }}
        title="Flow"
      />
    </div>
  );
};

export default FlowIframe;

5. Close the enrollment flow​

We need to close the embedded flow once a user completes or chooses to exit the flow early. Close the embedded flow by listening for the light-flow-close event.

Update the component from step 4 to handle the event:

import React, { useEffect } from "react";

interface FlowIframeProps {
  url: string;
  onClose: () => void;
}

const FlowIframe: React.FC<FlowIframeProps> = ({ url, onClose }) => {
  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      const eventType = event.data?.type;
      if (!eventType) {
        return;
      }
      if (eventType === "light-flow-close") {
        onClose();
      }
    };

    window.addEventListener("message", handleMessage);

    return () => {
      window.removeEventListener("message", handleMessage);
    };
  }, [onClose]);

  return (
    <div
      style={{
        position: "fixed",
        top: 0,
        left: 0,
        right: 0,
        bottom: 0,
        zIndex: 9999,
      }}
    >
      <iframe
        src={url}
        style={{ width: "100%", height: "100%", border: "none" }}
        title="Flow"
      />
    </div>
  );
};

export default FlowIframe;

6. Verify customers are able to enroll​

Test the enrollment flow​

You can use your email, a credit card number of 4242 4242 4242 4242, and any other fake data to test the enrollment flow in your app.

Check enrollment​

Now we can check to see if the customer is enrolled in the dashboard:

  1. Log in to the Light dashboard
  2. On the Apps page, go to the app you previously created
  3. Go to the Accounts page and select Enrolled

You should see an enrolled customer's details.

Next steps​

Congratulations on completing the Light quickstart! You've completed all of the steps necessary to enroll new customers in a power plan. To launch the experience, just repeat the first step to make a live app and use that AppToken.

There are other experiences that are important to your customer's journey. Explore our guides to learn about billing, documents, renewal, service, and usage tracking.

FAQs​

What's the difference with a sandbox and live app?​

Sandbox apps are safe to use in development and testing. No power plans will actually take affect. So you are free to enroll, change details, and cancel service with sandbox credentials.

What if I don't have an account on the Light dashboard?​

The Light dashboard currently requires that a teammate or Light invites you to join. Reach out to us if you're interested in partnering with Light.