​
Understanding Connect-web

Connect-web is an open-sourced single-page web application developed by FlatPeak that is free to use and modify under the MIT license.

In this article, Connect-web is referred to simply as Connect.

To start, clone Connect source code from GitHub and run on your computer or host on your server that can access the Internet:

  1. Your app initiates a Session: Your application begins new session with Connect by submitting a request containing a connect_token to a Connect’s URL.
  2. Connect presents a web page: Connect responds with a web page that provides information and choices so your customer can start identifying their tariff.
  3. Customer makes a Selection: Your customer reviews the page and selects an action.
  4. Iterative Exchange: Connect returns the next page in response. This cycle repeats until the customer’s tariff is successfully identified and/or connected.

​
Planning your implementation

  1. Style Connect to your brand: Review the application source code, style the UI according to your brand’s guidelines, and host it on your servers.
  2. Enable Connect to your app: To integrate Connect to your application so your customers can access it when they want to connect their tariff, refer to the Displaying Tariff Settings guide.

​
Setting up

1

Clone our repo and install the required dependencies

git clone https://github.com/flat-peak/flatpeak-connect-web.git
cd flatpeak-connect-web
npm install
2

Set the environment variables

export FLATPEAK_CONNECT_URL=https://connect.flatpeak.com
If you are on Windows, ensure you appropriately set env variables for your shell.
3

Run Connect-web locally

npm run dev

A local preview of Connect-Web will be available at http://localhost:7070.

Your browser will redirect to an error page. This is because you have not provided a Connect token. Ignore this error and continue following this guide.

​
Creating a Connect token

This step shall be implemented in your back-end.

Connect Token is a single-use object that identifies and secures your customer’s session with Connect service, for the duration of that session. To create it, make a request to create-connect-token API endpoint.

  1. Set connect_web_uri to http://localhost:7070 if you are using the default port.
  2. Set callback_uri to any page that can accept callbacks.
Our team likes https://webhook.site for callback tests but you can use something else.

​
Starting a new session with Connect

This step shall be implemented in your front-end.

Now that you have the connect_token you can use it to launch a new session with Connect:

1

Open Connect-web in your browser

On your computer, where you already have Connect-web running locally, open to the following URI: http://localhost:7070?fp_cot=cot_***. Replace cot*** with the connect_token. The resulting URI may look similar to this example:

2

Follow the Connect flow

Connect will present you with a set of pages that will let you share your tariff information. It automatically chooses the best route to discover your tariff based on the availability of provider APIs, data-sharing regulations and frequency of provider use within the FlatPeak base.

3

Receive callback

Once click Save button on the Tariff Summary screen, Connect-web will send the following to your callback_uri:

Example callback
https://webhook.site/4623e56fc5c1?fp_cot=cot_6587fa4362341be5b524de3b&fp_status=success

​
Exchanging Connect Token for a Location ID

Using connect_token as a reference, call exchange-connect-token API endpoint to get permanent identifiers that you will use to obtain your customer’s tariff.

location_idIdentifies of the physical location where energy is supplied under an agreement between your customer and their provider.
customer_idIdentifies your customer in FlatPeak systems.

Store both IDs in your application’s database in reference to your customer and the physical location of their property.

​
Implementing on-page validation for address capture

If your application already collects your customers’ postal address, include it when you create the connect_token (postal_address section) - and skip reading this section.

If you are unable to provide the full postal address, Connect will return to the Postal Address Capture page, where your customer will enter their address. Connect uses this information to determine the selection of energy providers that your customer may be using, their market tariff rates, and grid carbon intensity.

The source code of Connect that you cloned from FlatPeak GitHub does not include a client-side postal address lookup. We highly recommend you add an address lookup and/or validation service (such as Google Place Autocomplete) for better customer experience and to avoid server-side errors when submitting an incorrect or incomplete address.

The Postal Address Capture page is located in flatpeak-connect-web project is /src/screens/DynamicViews/PostalAddressCapture.tsx.

​
Handling errors

In the unlikely event that Connect experiences an issue that it cannot automatically resolve, it will return the error page similar to the illustration below.

The “Try Again” button does not have an action implemented by default.

The error page location in the flatpeak-connect-web project is /src/screens/CommonViews/Exception.tsx.

We recommend you implement the “Try Again” button with an action to go back to the previous page (i.e., onclick=“history.back()”) if your method of integration allows it.

If you cannot implement the go-back method, launch a new session with Connect using the new connect_token, or close Connect and let the customer restart it manually.

​
Removing demo warning message

Connect-web codebase includes a warning message that reminds you not to use FlatPeak-hosted Connect-web in production as it is not appropriately hosted for high load.

To remove this warning, open the flatpeak-connect-web project you cloned earlier and go to src/shared/ui/DemoDisclaimer/DemoDisclaimer.tsx, find cost DISPLAY_DEMO_DISCLAIMER and set it to false. Click the Code tab below to review the file that you need to edit.

Shall you find it challenging to implement Connect using this guide, get in touch with our support team. We’d be glad to help!

Was this page helpful?

Exploring ConnectNative app or Server-side