Multi-type linking

Sometimes linking a single asset type is not enough. When your customer owns multiple asset types from the same vendor, Link UI can be configured to link all of them at once. This can significantly reduce friction for users by helping to consolidate linking flows and get data flowing to your app faster.

Especially when building home energy apps, connecting multiple assets often is needed to manage the household’s energy. Solar installations often come with home batteries and grid-side meters being installed together and connected to the same vendor app.

For example, a typical home energy account might look like this:

DownloadFullscreen

Leveraging multi-type linking will combine three individual linking sessions (the three screens on the left) into a single, combined flow (right screen).

DownloadFullscreen

Copy linkHow to use multi-type linking

For Enode to determine which types of assets to link from a vendor account, your app needs to request their respective scopes.

[
  "vehicle:read:data",
  "vehicle:read:location"
  "vehicle:control:charging",
  "charger:read:data",
  "charger:read:location",
  "charger:control:charging",
]

For home energy management use cases you would typically link a battery, inverter and a meter. Depending on the data access needed, scopes are configured for each asset type individually.

The example below shows a request to initiate a common “home energy” linking session using Link userAPI endpoint.

curl https://enode-api.{ENVIRONMENT}.enode.io/users/{USER_ID}/link \
  -X POST \
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "language": "en-US",
        "scopes": [
          "battery:read:data",
          "battery:read:location",
          "battery:control:operation_mode",
          "meter:read:data",
          "meter:read:location",
          "inverter:read:data",
         "inverter:read:location"
        ],
        "redirectUri": "yourapp://integrations/enode"
      }'

The corresponding response is the same as for a single-asset linking session:

{
  "linkUrl": "https://link.enode.com/YzIwZThhYjYtMjMzMi00ZTAyLTg0OTYtYzdjOTlhZTY3Zjc3QDI2YzI1MDExLTdhYTctNGE2NS1iNjBmLTZmMzc5NmRhODUyMDowNDViYjFiYmE0M2Y5NDU5YTc5OTgxZmEyYTg1NmI4YzhkOGU4YjgyNmNmMzQzZmFmMGNhZTlmNDBjMmZmOTgy",
  "linkToken": "U2FtcGxlIFNESyB0b2tlbgpTYW1wbGUgU0RLIHRva2VuClNhbXBsZSBTREsgdG9rZW4KU2FtcGxlIFNESyB0b2tlbg=="
}

Copy linkUser journey

The user journey for linking multiple types of assets is very similar to linking a single type of asset. Link UI ensures that users are well informed throughout the flow about the various devices and asset types your app needs access to. The following section highlights considerations for parts of the user journey that are different when linking multiple asset types.

Copy linkBrand and service selection in your app

To build a flow where vendor selection happens outside of Link UI, pass an additional vendor property to the linking session. To determine which vendors support which combinations of devices types, the /integrations (IntegrationsAPI) endpoint should be used.

Example query to get all vendors which support battery and meter: /integrations?assetTypes=battery,meter

[
  {
    "displayName": "Enphase",
    "vendor": "ENPHASE",
    "portalName": "Enphase",
    "status": "READY",
    "linkingStatus": "READY",
    "assetTypes": ["battery", "meter"],
    "scopes": [
      "battery:control:operation_mode",
      "battery:read:data",
      "battery:read:location",
      "meter:read:data",
      "meter:read:location"
    ]
  }
  // ...additional vendors
]

Copy linkBrand and service selection in Link UI

As an alternative, Link UI can be used to render a list of brands. The brands shown are determined by the scopes that have been requested for the linking session.

For example, if you have requested inverter:read:data and battery:read:data, LinkUI will only show the vendors that support at least one of the requested asset types.

DownloadFullscreen

Copy linkScopes

In the UI, the scopes screen summarizes which data and controls your app is asking for. For multi-type linking sessions, scopes are nested as groups to make the screen more user friendly.

Users can click on the scope groups for full detail. It also explicitly states what will not be accessed through the platform and your app.

DownloadFullscreen

Copy linkDevices found

After the sign-in and verification steps are completed, your user will be presented with a list of devices found within their account.

DownloadFullscreen

Once the user clicks on Connect, the user has successfully linked the devices to their account and data will begin flowing to your servers.

DownloadFullscreen

Copy linkHandling multi-type connections

The connected assets and their types depend entirely on the assets available in the user’s vendor account. This means requesting multiple asset types does not guarantee that all of them will actually be available.

Using our battery and meter example, the outcomes could be:

• Only battery/batteries are connected, or
• Only meter/meters are connected, or
• Both battery/batteries and meter/meters are connected.

Copy linkDiscovery of linked assets

Enode’s user:{assetType}:discovered webhooks will notify you about the resulting assets. Following the same example of linking session with battery and meter, this pseudo code shows how to handle the different asset types being discovered:

switch (request.event) {
  case "user:battery:discovered":
    console.log(`Battery discovered: ${request.battery?.id}`);
    break;

  case "user:meter:discovered":
    console.log(`Meter discovered: ${request.meter?.id}`);
    break;

  default:
    console.warn(`Unhandled event type: ${request.event}`);
}

Our webhook events sectionAPI can guide your futher on onboarding of the different devices into your app.