# Migrating from Link UI v3 to v4

Follow this guide to update your existing Link UI integration to Link UI 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](https://developers.enode.com/docs/link-ui/introduction).

## Step 1: Upgrade your API version

Link UI v4 is available on API version `2024-01-01`. [Read the full changelog](https://developers.enode.com/api/changelog).

### Upgrading 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 user](https://developers.enode.com/api/reference#postUsersUseridLink) endpoint.

### Upgrading from an earlier API version

- Consider passing in the `Enode-Version: 2024-01-01` header (see below) for just the [link user](https://developers.enode.com/api/reference#postUsersUseridLink) 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:

```bash
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 versions](https://developers.enode.com/api/reference#versioning) and ways to upgrade.

## Step 2: Update your API calls

In your server code, update your calls to the [link user](https://developers.enode.com/api/reference#postUsersUseridLink) to be compatible with the new version, which now requires new parameters.

| New required parameters | Description | Example |
| --- | --- | --- |
| `scopes` | The desired [scopes](https://developers.enode.com/api/reference#scopes) you wish to request from your user's asset | `["vehicle:read:data", "vehicle:read:location", "vehicle:control:charging"]` |
| `language` | The language of Link UI, replacing the previous `forceLanguage` parameter | `"en-US"` |
| `redirectUri` | This field is now required, and tells Link UI where to redirect your user after they have completed their linking session | `"myapp://integrations/enode"` |

For a complete example of a [link user](https://developers.enode.com/api/reference#postUsersUseridLink) request, see below.

```bash {% title="Request sample" %}
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"
      }'
```

```json {% title="Response sample" %}
{
  "linkUrl": "https://link.enode.com/YzIwZThhYjYtMjMzMi00ZTAyLTg0OTYtYzdjOTlhZTY3Zjc3QDI2YzI1MDExLTdhYTctNGE2NS1iNjBmLTZmMzc5NmRhODUyMDowNDViYjFiYmE0M2Y5NDU5YTc5OTgxZmEyYTg1NmI4YzhkOGU4YjgyNmNmMzQzZmFmMGNhZTlmNDBjMmZmOTgy",
  "linkToken": "U2FtcGxlIFNESyB0b2tlbgpTYW1wbGUgU0RLIHRva2VuClNhbXBsZSBTREsgdG9rZW4KU2FtcGxlIFNESyB0b2tlbg=="
}
```

More information about these parameters is available in our [API reference](https://developers.enode.com/api/reference#postUsersUseridLink).

### Scopes 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.

### Platform-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.

## Step 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](https://developers.enode.com/docs/link-sdks/introduction) with step-by-step instructions on how to implement this (you’ll need `linkToken` from Step 2).

### iOS

```swift
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)
```

### Android

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