> For the complete documentation index, see [llms.txt](https://oneconnect-1.gitbook.io/oneconnect-sdk-for-android-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oneconnect-1.gitbook.io/oneconnect-sdk-for-android-doc/migration-guide-v1.1.75-or-1.1.76-to-v1.2.1.md).

# Migration Guide v1.1.75 Or 1.1.76 To v1.2.1

## OneConnect SDK Migration Guide

This guide explains the breaking changes introduced in **OneConnect SDK v1.2.1** and how to migrate your existing integration from **v1.1.75** or **v1.1.76**.

<mark style="color:$success;">All Developers need to migrate Oneconnect sdk To v1.2.1 before 7th November</mark>

***

## Overview

This migration guide is intended for developers upgrading from **OneConnect SDK v1.1.75** to **v1.2.1**.

The latest SDK simplifies the integration process by:

* Removing manual JSON parsing.
* Eliminating the need to manage VPN credentials.
* Handling VPN configuration internally.
* Providing a simplified API for fetching servers and starting VPN connections.

> **This release contains breaking changes.** Existing integrations built with **v1.1.75 or v1.1.76** must be updated before upgrading to **v1.2.1**.

***

## Breaking Changes

### 1. `fetchJson()` Has Been Removed

The `fetchJson()` method has been **removed** from the SDK and is no longer available.

Previously, this method returned the raw JSON response, allowing developers to manually parse and process the server list.

```java
OneConnect oneConnect = new OneConnect();
oneConnect.initialize(this, "YOUR_API_KEY");

oneConnect.fetchJson(new JsonResponseListener() {
    @Override
    public void onSuccess(String freeServersJson, String premiumServersJson) {
        Constants.FREE_SERVERS = oneConnect.fetch(true);
        Constants.PREMIUM_SERVERS = oneConnect.fetch(false);
    }

    @Override
    public void onFailure(Exception e) {
        Log.e("OneConnectServer", "Failed to fetch servers", e);
    }
});
```

This method is no longer supported and should be removed from your application.

***

### 2. `fetch()` Has Changed

The `fetch()` method is now the **only supported way** to retrieve the server list.

In previous SDK versions, developers had two options:

* `fetchJson()` – returned the raw JSON for manual processing.
* `fetch()` – returned a parsed list of server objects.

Since `fetchJson()` has been removed, `fetch()` is now the single API used to retrieve servers.

#### Previous `fetch()` Behavior

Previously, `fetch()` returned fully populated server objects, including the VPN credentials and OpenVPN configuration.

```java
oneConnect.fetch(new ServerResponseListener() {
    @Override
    public void onSuccess(ArrayList<Server> freeServersList,
                          ArrayList<Server> premiumServersList) {

        Log.d("OneConnectServer",
            "ID: " + freeServersList.get(0).getId() +
            ", Name: " + freeServersList.get(0).getServerName() +
            ", Country: " + freeServersList.get(0).getCountry() +
            ", Username: " + freeServersList.get(0).getVpnUserName() +
            ", Configuration: " + freeServersList.get(0).getOvpnConfiguration());
    }

    @Override
    public void onFailure(Exception e) {
        Log.e("OneConnectServer", "Failed to fetch servers", e);
    }
});
```

The server object previously included:

* Server ID
* Server Name
* Country
* VPN Username
* VPN Password
* OpenVPN Configuration

#### New `fetch()` Behavior

`fetch()` now returns **lightweight server objects** that contain only the information required to display a server list.

**Java**

```java
OneConnect oneConnect = new OneConnect();
oneConnect.initialize(this, "YOUR_API_KEY");

oneConnect.fetch(new ServerResponseListener() {
    @Override
    public void onSuccess(ArrayList<Server> freeServersList,
                          ArrayList<Server> premiumServersList) {

        Log.d("OneConnectServer",
            "ID: " + freeServersList.get(0).getId() +
            ", Name: " + freeServersList.get(0).getServerName() +
            ", Country: " + freeServersList.get(0).getCountry() +
            ", Flag URL: " + freeServersList.get(0).flagUrl());
    }

    @Override
    public void onFailure(Exception e) {
        Log.e("OneConnectServer", "Failed to fetch servers", e);
    }
});
```

**Kotlin**

```kotlin
val oneConnect = OneConnect()
oneConnect.initialize(this, "YOUR_API_KEY")

oneConnect.fetch(object : ServerResponseListener {
    override fun onSuccess(
        freeServersList: ArrayList<OneConnectServer>,
        premiumServersList: ArrayList<OneConnectServer>
    ) {

        Log.d(
            "OneConnectServer",
            "ID: ${freeServersList[0].id}, " +
            "Name: ${freeServersList[0].serverName}, " +
            "Country: ${freeServersList[0].country}, " +
            "Flag URL: ${freeServersList[0].flagUrl}"
        )
    }

    override fun onFailure(e: Exception) {
        Log.e("OneConnectServer", "Failed to fetch servers", e)
    }
})
```

The new server object **returns**:

* Server ID
* Server Name
* Country
* Flag URL

The new server object **no longer returns**:

* VPN Username
* VPN Password
* OpenVPN Configuration

The SDK now securely manages VPN credentials internally. This improves security by preventing applications from directly accessing sensitive connection information while also simplifying the integration process.

***

## Starting a VPN Connection

This is the largest breaking change in this release.

### Previous Implementation

Previously, the application was responsible for passing the VPN configuration and credentials into `OpenVpnApi`.

When migrating to **v1.2.1**, you should also remove the following import, as `OpenVpnApi` is no longer used by the SDK:

```java
import top.oneconnectapi.app.OpenVpnApi;
```

All VPN connections are now initiated directly through the `OneConnect` instance using `oneConnect.startVpn()`.

```kotlin
private fun startVpnConnection() {
    Toast.makeText(this, "Starting VPN connection...", Toast.LENGTH_SHORT).show()

    if (selectedServer == null)
        return

    OpenVpnApi.startVpn(
        this@MainActivity,
        selectedServer!!.ovpnConfiguration,
        selectedServer!!.country,
        selectedServer!!.vpnUserName,
        selectedServer!!.vpnPassword
    )
}
```

***

### New Implementation

VPN connections are now started directly from the existing `OneConnect` instance.

Only the server ID and a display name are required.

> **Note:** `selectedServer` refers to the `OneConnectServer` object selected by the user from the server lists returned by `oneConnect.fetch()`. Typically, you'll display the fetched servers in your UI, let the user choose one, then pass that selected server's ID to `startVpn()`.
>
> The second parameter is the **display name** shown to the user while connected. Although passing the server's country name is recommended (e.g., `selectedServer.country`), you may pass **any string** you want, such as `"United States #1"`, `"Fast Server"`, or any custom label that best fits your application.

**Kotlin**

```kotlin
private fun startVpnConnection() {
    Toast.makeText(this, "Starting VPN connection...", Toast.LENGTH_SHORT).show()

    if (selectedServer == null) return

    oneConnect.startVpn(
        selectedServer!!.id,
        selectedServer!!.country //The text that will show in the notification
    )
}
```

**Java**

```java
private void startVpnConnection() {
    Toast.makeText(this, "Starting VPN connection...", Toast.LENGTH_SHORT).show();

    if (selectedServer == null)
        return;

    oneConnect.startVpn(
        selectedServer.getId(),
        selectedServer.getCountry() //The text that will show in the notification
    );
}
```

The SDK automatically retrieves the required VPN credentials and configuration before establishing the connection.

***

## Important

You **must use the same `OneConnect` instance** that was used to initialize the SDK and fetch the server list.

Example:

```java
OneConnect oneConnect = new OneConnect();
oneConnect.initialize(this, "YOUR_API_KEY");

oneConnect.fetch(new ServerResponseListener() {
    ...
});
```

When the user selects a server, use **that same `oneConnect` object** to start the VPN.

```kotlin
oneConnect.startVpn(
    selectedServer.id,
    selectedServer.country
)
```

> **Do not create a new `OneConnect` instance before calling `startVpn()`.** The SDK relies on the existing initialized instance to securely establish the VPN connection.

***

## Migration Checklist

Update your project by completing the following steps:

* ✅ Remove all usages of `fetchJson()`.
* ✅ Replace `fetchJson()` with `fetch(ServerResponseListener)`.
* ✅ Stop manually parsing the server JSON.
* ✅ Remove all code that accesses:
  * `getVpnUserName()`
  * `getVpnPassword()`
  * `getOvpnConfiguration()`
* ✅ Update your UI to use the new lightweight server model.
* ✅ Remove the `OpenVpnApi` import:

```java
import top.oneconnectapi.app.OpenVpnApi;
```

* ✅ Remove all calls to `OpenVpnApi.startVpn()`.
* ✅ Replace them with:

```kotlin
oneConnect.startVpn(server.id, server.country)
```

* ✅ Use the **same initialized** `OneConnect` **instance** for both fetching servers and starting VPN connections.

***

## Benefits of the New SDK

The new architecture provides several improvements:

* Automatic server parsing
* Cleaner API
* No manual JSON handling
* Smaller server objects
* Improved security
* Simplified VPN startup
* Less code to maintain
* Better foundation for future SDK updates