Skip to main content

​
Context

Flatpeak may redirect customers to your application using the universal_link_url configured in the Flatpeak Dashboard. This typically occurs when a customer uses their energy provider’s app to grant access to device telemetry and control in exchange for a device specific tariff, or to enrol in a VPP programme. The universal link contains a connect_session parameter that identifies the Connect Session. Your application should use this value to retrieve and validate the Connect Session, verify the customer’s authentication state, and ensure the customer is authorised before displaying protected information. Example universal link When universal_link_url is configured as: 
https://app.nova.com/flatpeak
Flatpeak redirects the customer to: 
https://app.nova.com/flatpeak?connect_session=cos_6587fa4362341be5b524
When a customer opens the universal link:
  1. If your mobile application is installed and configured for Universal Links (iOS) or App Links (Android), open the application.
  2. Otherwise, open the link in the customer’s web browser.
  3. Extract the connect_session parameter from the URL.
  4. Retrieve the Connect Session.
  5. Verify session is valid and not expired.

​
iOS Configuration

To support Universal Links on iOS:
  1. Add the Associated Domains capability to your application.
  2. Configure the domain used by universal_link_url.
  3. Host an apple-app-site-association file on the domain.
  4. Configure your application to handle incoming Universal Links.

​
Android Configuration

To support App Links on Android:
  1. Configure an intent filter for the domain used by universal_link_url.
  2. Host an assetlinks.json file on the domain.
  3. Verify domain ownership.
  4. Configure your application to handle incoming App Links.

​
Best Practices

  • Use HTTPS for all universal links.
  • Allow customers to continue in a browser if the application is not installed.
  • Always validate the Connect Session before displaying protected information.
  • Treat connect_session as a temporary identifier and avoid persisting it unnecessarily.
  • Handle expired or invalid sessions gracefully and provide clear guidance to the customer.

​
Security

Universal Links are a navigation mechanism only. They must never be used as proof of authentication or authorisation. When a customer accesses protected content:
  1. Receive the universal link.
  2. Retrieve and validate the Connect Session.
  3. Verify the customer is authenticated.
  4. Prompt the customer to sign in if required.
  5. Display the appropriate content.

​
Device Selection and Connect Flow

After validating the Connect Session, determine which device the customer intends to connect. If the Connect Session already contains a device_id:
  1. Retrieve the device.
  2. Start the Connect Session.
If the Connect Session does not contain a device_id:
  1. Prompt the customer to select a device.
Once a device has been selected:
  1. Check whether the device is already registered with Flatpeak.
  2. If not, create the device and store the returned device_id in your database. If your implementation supports multiple locations per device, you may also need to create a Location.
  3. Update the Connect Session with the selected device_id and location_id.
  4. Start the Connect Session with flow set to AUTO.

​
Connect Session Completion

When the customer completes the Connect flow, your application receives a connect_session.complete webhook event. Use this event to update your records and enable the services authorised by the customer.
  1. Retrieve the associated device and location.
  2. Review the consent information returned by Flatpeak.
  3. Determine whether the customer granted consent for telemetry sharing and operating schedule delivery.
  4. Update your records to reflect the customer’s consent choices.
  5. Start sending telemetry if consent was granted.
  6. Start retrieving and applying operating schedules if consent was granted.