Interventions

There are some situations where a specific device’s capability depends on an action taken by the end user. For instance, some Volkswagen ID vehicles will only be smart charging capable after a specific software update.

In cases like this, we will return an intervention ID as part of the capabilities object in one of the asset endpoints, like Get vehicleAPI. You can use the intervention ID to fetch additional information about how to resolve the intervention using our Get InterventionAPI endpoints.

You can display this information directly in your app to help the end-user resolve the intervention and unblock the device's capability.

Copy linkCapabilities and interventions

DownloadFullscreen

Capabilities represent Enode’s ability to fetch information, perform actions, or utilize features such as smart charging for a given device. Depending on the device model or version, specific capabilities may not be accessible. These cases can be split into two categories:

• Missing capabilities are permanently missing from a device, e.g. a specific vehicle model missing an onboard GPS will never be able to transmit a location
• Blocked capabilities are inherently supported by a device model but require user action to be unblocked for a user’s specific device, e.g. a vehicle that has an onboard GPS and can start transmitting a location if the user enables the setting in their vehicle’s infotainment system

Interventions represent the user actions required to unblock a blocked capability. For each connected device, every blocked capability contains one or more interventions that must be resolved to unblock the capability (surfaced e.g. via our Get vehicleAPI endpoint).

Copy linkAdditional information

• A specific device can have multiple blocked capabilities and, therefore, multiple interventions tied to it
• Two unique devices of the same model can have different combinations of blocked capabilities based on factors such as user settings, software versions and more
• Multiple capabilities can be unblocked by a single intervention
  • Example: Some vendors require a service subscription to transmit any data from the device, and once the user signs up for the subscription, multiple capabilities will be unblocked
• Interventions may appear on blocked capabilities throughout the connection lifecycle
  • Example: Some interventions will appear directly after the user links their device through Link UI, while others may appear later
• A capability can become blocked based on an event and, therefore, be assigned an intervention at any given time
  • Example: By a user disabling a setting in the vendor app or on the device itself
• If a device lacks a certain capability but does not have an assigned intervention, the capability is categorized as missing. However, it can be re-categorized as a blocked capability and be assigned an intervention in the future if Enode detects a new resolution
• Intermittently impaired capabilities that require no user action are not considered blocked and won't include interventions
  • Example: Some vehicle models may temporarily disable location data transmission while in motion
• An intervention may be brand-specific, or may apply to all brands. In the latter case, the fields vendor, vendorType and brand will all be null.

Copy linkAccessing interventions via our API

Interventions are surfaced via the capabilities object returned by fetching a specific device. In most cases, this means there is a two-step process to receive and react to interventions:

1. Fetch a device, e.g. via Get vehicleAPI. Detect a blocked capability with an intervention ID attached to it.
2. Query the Get interventionAPI endpoint to fetch detailed information about this intervention.

Copy link1. Detect a blocked capability

We recommend checking for blocked capabilities every time you fetch a device, as a change in status can be unpredictable at times.

Sample response from Get vehicleAPI.

{
  "id": "8d90101b-3f2f-462a-bbb4-1ed320d33bbe",
  "vendor": "AUDI",
  "capabilities": {
    "location": {
      "isCapable": false,
      "interventionIds": [
        "394939c1-70bd-42d9-881f-24d15e3610e2"
      ]
    },
    { ... }
  },
  { ... }
}

Copy link2. Fetch intervention information

This contains general information as well as more detailed information about the resolution of the intervention.

Sample response from Get interventionAPI.

{
    "id": "394939c1-70bd-42d9-881f-24d15e3610e2",
    "vendor": "AUDI",
    "vendorType": "vehicle",
    "introducedAt": "2022-11-18T00:00:00",
    "brand": "Audi",
    "domain": "Device",
    "resolution": {
        "title": "Enable the \"Car finder\" connect service",
        "description": "For remote access to your vehicle's location, it's necessary to enable the *Car finder Connect Service*. Follow these steps to activate it:\n\n1. From your car's infotainment system, navigate to Settings.\n2. Select Privacy.\n3. Choose *Car finder*.",
        "access": "Physical",
        "agent": "User"
    }
},

Copy linkList all interventions

If you wish to query a list of all interventions, you can use the List interventionsAPI endpoint. It returns all interventions the system currently supports broken down by vendor, including all brand-agnostic interventions.

Copy linkLocalization

Both intervention endpoints accept a language query parameter to request a translated resolution title and description. For a full list of supported languages, please refer to the API referenceAPI.

Copy linkIntervention types

Interventions typically relate to the vendor user account, device settings, or software versions. While most of them can be resolved by the user remotely or on the device itself, some need third-party involvement. These possible combinations are described through three pieces of structured data.

Copy linkDomain

DownloadFullscreen

The domain key describes whether the intervention relates to the device itself or the vendor user account used to access the device.

Copy linkAccess

DownloadFullscreen

The access key describes where the intervention can be resolved.

Copy linkAgent

DownloadFullscreen

The agent key describes who can resolve the intervention.

Copy linkPresenting interventions to users

The Interventions API is universally designed to fit many presentation and delivery methods, with the goal of making it as easy as possible to integrate it into your current app structure and design. Below are some considerations that could be worth taking into account when implementing interventions into your product.

Copy linkShowing relevant interventions only

The capabilities object returned for any given device does not regard the use case you are building for. We recommend filtering out any interventions that might be irrelevant to using your product. For example, discarding interventions relating to the smart charging capability if your product only reads vehicle information.

Copy linkDisplaying resolutions

DownloadFullscreen

Because of the nature of blocked capabilities, and that interventions can appear at any given time, we recommend finding a fixed place to present these to your users. For example, this could be contextually presented in the device detail view if any relevant interventions are present. Alternatively, interventions could be presented in close proximity to the related functionality in your app (e.g. smart charging settings).

Interventions that make it to your UI are inherently important, and to catch the user’s attention, you could consider explicitly mentioning the functionality that is blocked by the missing capability (e.g. “Additional steps are required to enable smart charging”) and using prominent visual aids such as strong colors to highlight their importance. To extend this, you could consider utilizing push messages if interventions are not resolved within a certain time span.

DownloadFullscreen

Intervention descriptions are formatted as Markdown, allowing you to render them with rich formatting matching your design language. Since the resolution descriptions vary in length and can have links, we recommend using the intervention title in minified contexts and allowing the user to tap to open the intervention resolution in a fullscreen or modal view.

Copy linkHandling multiple interventions

DownloadFullscreen

After discarding irrelevant interventions through filtering, there could still be cases where multiple interventions need to be resolved to unlock the wanted functionality. To handle this case gracefully and to avoid overwhelming the user, we recommend focusing on one intervention at a time and utilizing it as an entry to all interventions (e.g. as a list view of all interventions). We would also consider allowing the user to solve one intervention at a time, allowing them to navigate your app freely between each intervention is resolved (as opposed to locking them into a longer flow for solving all interventions).

To present the most important interventions first, you can consider sorting interventions by the following parameters.

1. Occurrence — If e.g. one intervention unlocks multiple capabilities, you could consider presenting this first
2. Friction — Focusing on lower friction interventions first, e.g. interventions that can be solved by the user before interventions that need third-party involvement or remotely before physically

Copy linkEnriching with metadata

DownloadFullscreen

To extend the title and description of the resolution, you can utilize the structured data to build more context for your user. This could be done by mapping the domain or access keys to supporting icons or category tags, mentioning that the steps can be resolved easily by the user themselves via the agent key, or highlighting if the intervention requires the user to make an appointment with a third-party (for vehicles, this is typically their dealership).

You can also utilize the blocked capability to enrich the intervention, such as mapping a blocked location capability to a pin icon.