End-user app design

There are three ways you can enable end-users to manage their participation in VPPs:

1. [Recommended] Embed our frameless whitelabel portal into your monitoring app;
2. Build the UX directly into your existing monitoring app by leveraging our API;
3. Use your pre-built whitelabel portal.

In all cases, the site and device need to be commissioned before we can start working with them. Read on about the commissioning process.

Commissioning

Commissioning is how you create the site and device in our systems.

As part of your existing equipment commissioning process, you should add a call to our API to commission the equipment on our servers as well.

To do so, from your cloud, call POST /v1/commission with the site and device info. The response will contain information about which programs the device is eligible to participate in, and, if the device can be automatically enrolled, information about the newly created enrollment.

You do not need to add steps to the installer-facing commissioning flow. You simply need to add a backend process that forward the information you already have to Flip. In addition, note that all site fields are optional for this phase, and any missing information will be collected later.

:::info
About auto enrolling

The ability to auto enroll homeowners in programs is limited to those programs that permit it. In addition, the homeowner should have previously agreed to be enrolled, for instance by agreeing to Terms & Conditions that describe that this may happen.
:::

Option 1: Embed our whitelabel portal

A great compromise between option 1 and 2, this approach lets you embed our pre-built whitelabel portal into your app. So you can control the branding while keeping integration work to a minimum.

How it works

We'll give you a unique URL to add as an iframe or WebView into your app. Add the following parameters to log in a specific user:

Name	Description
site_id	The site ID.
token	A site token obtained by calling POST /v1/auth/site/{siteId}
signature	An HMAC signature verifying that you're the originator of this request.

How to generate the signature

To generate the signature, use the following steps:

1. Create an HMAC using the SHA-256 algorithm and the secret key we'll provide you.
2. Update the HMAC with the request body.
3. Generate the HMAC digest in hexadecimal format.
4. Convert the hexadecimal digest to a hexadecimal-encoded buffer.
5. The resulting buffer is the generated signature.

The body is a JSON object of the following shape, converted to a string:

{
    "site_id": "<SITE ID>",
    "token": "<TOKEN>"
}

Here is a sample implementation for NodeJS in TypeScript:

import { Buffer } from 'node:buffer'
import { createHmac } from 'node:crypto'

function createSignature({
  secret,
  siteId,
  siteToken,
}: { secret: string, siteId: string, siteToken: string }): string {
  const hmac = createHmac('sha256', secret)
  const body = JSON.stringify({
    site_id: siteId,
    token: siteToken,
  })
  const digest = hmac.update(body).digest('hex')
  return Buffer.from(digest, 'hex').toString('hex')
}

Option 2: Build it yourself

You can use our Mobile App API in order to build a custom VPP management flow within your monitoring app. We recommend the following design.

:::tip
Our API was designed for you to use it as a backend. In this respect, you don't need to copy any of the data we return in your own database.
:::

VPP tab

:::tip
From then on, and for all the API endpoints mentioned below, you can use site tokens.
:::

The VPP experience should be self-contained in a dedicated tab. Optionally you may decide to hide the tab if the homeowner does not actively participate in any VPPs and their utility does not offer any.

In order to check if the homeowner is currently enrolled in a VPP, call GET /v1/site/{siteId}/enrollments with the site ID. If the response contains enrollment info, the user is enrolled and you should display the Manage enrollment flow.

If there are no enrollments, you can check for programs. In order to do so, call GET /v1/site/{siteId}/programs with the homeowner's zip code and device type. If the response contains program info, programs are available and you should display the Program enrollment flow.

:::tip
During testing, you can use zip codes 88801 and 88802 to fetch test programs. 88803 is an example of no results.
:::

Program enrollment

In this flow, you will want to display a list of the available programs and their descriptions. Allow users to tap on each program to display all their info. At the bottom of the info page, add an Enroll button.

When they tap Enroll, you should call the POST /v1/site/{siteId}/enrollments endpoint with the site, program and appropriate device IDs. The enrollment will be set as PENDING, which could take a few days depending on the program. In the meantime, users should be given an option to cancel their enrollment via DEL /v1/site/{siteId}/enrollments/{id}.

:::warning
Prior to being able to enroll a homeowner, the site info needs to be provided to our system. Ideally, this would be done by the installer in the commissioning phase. If this wasn't done, you will need to give homeowners a way to enter the info manually and then submit it to PATCH /v1/sites/{id}.
:::

Manage enrollment

Once a homeowner has an enrollment in the ACTIVE state, they are officially enrolled in a program. They should be able to do the following:

• see past and upcoming events
• update their participation in current and upcoming events
• unenroll entirely from the program

See past and upcoming events

All events can be found using the GET /v1/site/{siteId}/events endpoint.

Update participation in current and upcoming events

When an event is in the IN_PROGRESS or UPCOMING state, users have the option to change their participation. They can either opt-out of the event, or update their reserve level, just for this event. To do so, use the PATCH /v1/site/{siteId}/event/{id} endpoint. If the event-specific reserve level in unset, it will default to that set by the program first, or otherwise the one set by the user.

Unenroll entirely from the program

If the homeowner decides to, they should be able to unenroll from the program using DEL /v1/site/{siteId}/enrollments/{id}. Note that some programs have minimum time commitments, and therefore unenrollment might fail. Conversedly, they might be able to unenroll, but might be charged a penalty by the utility.

Option 3: Use our standalone whitelabel portal

We've pre-built the entire experience in such a way that you can customize it with your own branding and domain. Logging in users works via oAuth 2.0. Please reach out if you'd like to use this option.