Client Network List (CNL)

The Unified SDK allows you to automatically start or stop VPN sessions based on network changes, such as when a user switches between Wi-Fi, mobile data, or other networks.

Setting Up Client Networks

To set up this feature, follow these steps:

1. Sign in at pango-cloud.com.

2. Navigate to Settings -> VPN -> Client Networks, click on the Add button.

3. Edit the client network settings: Type (Wi-Fi, WWAN, LAN) and Action (start/stop). Example configuration:

Type	Network Conditions	Action
Wifi	SSID: "MyHomeWifi" BSSID: "00:11:22:33:44:55"	Start
Wifi	SSID: "PublicWifi" BSSID: "00:14:22:01:23:45"	Stop

When the SDK starts the VPN for the first time, it downloads the necessary network configuration from the server. If there is no active VPN session, the SDK displays a notification based on the CNL settings.

Custom Notification for CNL State

You can customize the notification message shown to the user when the VPN is waiting for a secure network:

SdkNotificationConfig.Builder builder = SdkNotificationConfig.newBuilder();
builder.inCnl("Waiting for secure network","SDK will start VPN when a secure network is detected");

If you don't customize the notification, it will display the default title and message:

• title - CNL

• message - Waiting

Rules for Network Matching

When a device changes its network connection, the SDK will look through the configured networks in CNL and match the current configuration with server.

For WiFi networks

• If the SSID and BSSID are empty, it will match any Wifi network.

• If the authentication is set to Does not matter , it will match both open and protected networks.

Android Permissions

• For Android 8.1+ (API 27) and Android 10+ (API 29), you need to set up and request runtime permission for location to match networks by SSID and/or BSSID.

• If the required permission is missing, the SDK will not be able to access the network SSID and BSSID.

VPN Behavior

When a user changes the network while a VPN session is active and the new network matches the CNL rules with the Disabled action, the SDK will not reconnect to this network. Instead, it will throw a CnlBlockedException in the VpnStateListener#vpnError callback. Below is an example message:

"VPN stopped. Connected to a network not allowed by CNL rules."

Client-side CNL Configuration

The CNL configuration can also be managed on the client side.

Loading the list of saved network configurations

UnifiedSdk sdk = UnifiedSdk.getInstance();
Cnl cnl = sdk.getCnl();

cnl.loadList(new Callback<List<CnlConfig>>() {
    @Override
    public void success(@NonNull List<CnlConfig> configs) {
        // Handle the loaded list of CnlConfig objects
        for (CnlConfig config : configs) {
            System.out.println(config.toString());
            // Perform operations with the CnlConfig objects
        }
    }

    @Override
    public void failure(@NonNull VpnException e) {
        // Handle the failure case
        String errorMessage = e.getMessage();
    }
});

Updating the network configurations

UnifiedSdk sdk = UnifiedSdk.getInstance();
Cnl cnl = sdk.getCnl();

List<CnlConfig> updatedConfigs = new ArrayList<>();
newConfigs.add(new CnlConfig(
    CnlConfig.Type.WIFI,
    Arrays.asList("HomeWiFi", "OfficeWiFi"),
    Arrays.asList("00:11:22:33:44:55", "AA:BB:CC:DD:EE:FF"),
    CnlConfig.Action.ENABLE,
    CnlConfig.Authorized.YES
));
newConfigs.add(new CnlConfig(
    CnlConfig.Type.MOBILE,
    Collections.singletonList(""),
    Collections.singletonList(""),
    CnlConfig.Action.DISABLE,
    CnlConfig.Authorized.NO
));

cnl.updateList(updatedConfigs, new CompletableCallback() {    
    @Override
    public void complete() {
        // Handle the successful completion of the update operation
        System.out.println("CNL configurations updated successfully");
    }

    @Override
    public void error(@NonNull VpnException e) {
        // Handle the failure case
        System.out.println("Failed to update CNL configurations: " + e.getMessage());
    }
});

Resetting the network configurations

UnifiedSdk sdk = UnifiedSdk.getInstance();
Cnl cnl = sdk.getCnl();

cnl.clear(new CompletableCallback() {
    @Override
    public void complete() {
        System.out.println("CNL configurations cleared successfully");
        // Handle the successful completion of the clear operation
    }

    @Override
    public void error(@NonNull VpnException e) {
        // Handle the failure case
        System.out.println("Failed to clear CNL configurations: " + e.getMessage());
    }
});