Migrating from Link UI v3 to v4

Upgrading to our latest version of Link UI unlocks significant new features.

• A revamped scopes API and accompanying permissions flow in Link UI
• Support for Bluetooth verification, which will be required for some brands and capabilities in the future (including the capability to control Tesla vehicles)
• Improved linking steps, new help screens and revamped text and translations
• Support for native OAuth handling, further increasing the vendors we can support in the future while improving linking reliability, speed and security
• Improved accessibility, look and feel: including better readability, light and dark modes, and setting the foundations for further customizability in the future

For more information about Link UI v4 or if you don’t have an existing Link UI integration, read the dedicated guide.

Copy linkStep 1: Upgrade your API version

Link UI v4 is available on API version 2024-01-01. You can read the full changelog here.

Copy linkUpgrading from 2023-08-01

If you are upgrading from 2023-08-01, the amount of breaking changes is very small and limited to the link userAPI endpoint.

Copy linkUpgrading from an earlier API version

• Consider passing in the Enode-Version: 2024-01-01 header (see below) for just the link userAPI endpoint for an initial release. This allows you to avoid making changes to account for the 2023-08-01 version while gaining the benefits of Link UI v4. However, please be aware that the scopes you pass in when creating linking a user will be reflected across all API versions.
• When updating your entire client, remember to account for additional breaking changes across the API when updating to 2024-01-01.

As you are testing Link UI v4 and initially rolling it out, you may consider passing in per-request API headers:

curl https://enode-api.{ENVIRONMENT}.enode.io/users/{USER_ID}/link \
	-X POST \
	-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
	-H "Enode-Version: 2024-01-01"

See our docs for more information about API versionsAPI and ways to upgrade.

Copy linkStep 2: Update your API calls

In your server code, update your calls to the link userAPI to be compatible with the new version, which now requires new parameters.

For a complete example of a link userAPI request, see below.

curl https://enode-api.{ENVIRONMENT}.enode.io/users/{USER_ID}/link \
  -X POST \
  -H "Enode-Version: 2024-01-01"
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "vendorType": "vehicle",
        "language": "en-US",
        "scopes": [
          "vehicle:read:data",
          "vehicle:read:location",
          "vehicle:control:charging"
        ],
        "colorScheme": "system",
        "redirectUri": "yourapp://integrations/enode"
      }'

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

More information about these parameters is available in our API referenceAPI.

Copy linkScopes and API versions

• The devices that you linked using an older API versions will be unaffected by our scopes release. You will continue to be able to read all data and control those devices, even using 2024-01-01.
• New devices you link using 2024-01-01 will have their scopes reflected in previous versions.
  • For instance, if you don’t request the vehicle:read:location scope, API calls using the 2023-08-01 version will see  longitude: null and latitude: null on vehicle API responses.

Copy linkPlatform-specific linking requests

If you support multiple app platforms (web, iOS, Android), you may now need to create platform-specific Link UI sessions on your server to account for different redirectUri schemes across platforms. This is especially true if you plan to integrate with our Link SDKs.

Copy linkStep 3: Integrate the new Link SDKs (iOS and Android only)

If you have native iOS and Android apps, remove any client-side code that manages showing/hiding Link UI URLs (e.g., showing WebViews).

Instead, replace them with calls to our new native SDKs, which will handle best practices for you and supports Bluetooth verification. Please refer to our SDK guide with step-by-step instructions on how to implement this (you’ll need linkToken from Step 2).

Copy linkiOS

private var handler: Handler?

self.handler = Handler(linkToken: linkToken) { result in
    switch result {
    case .success():
        // Handle success
    case .failure(let error):
        // Handle error
    }
}

handler.present(from: self)

Copy linkAndroid

val linkToken = "DxwPa..."
val intent = Intent(this, LinkKit.class)
intent.putExtra("LinkToken", linkToken);
startActivityForResult(intent, resultCode);