VPN Interface
The VPN Interface allows you to configure and control VPN sessions using the UnifiedSDK
class. This document provides an overview of the available methods and classes for managing VPN sessions.
SessionConfig
The SessionConfig
class is used to configure VPN sessions. It provides the following Builder
methods:
withTransport(transportName)
- Set the transport name to start the session with. Useful when multiple transports are available.withPolicy(appPolicy)
- Define the app policy to use. Available options:AppPolicy.forAll()
- VPN will be available for all apps.AppPolicy.newBuilder().policy(AppPolicy.POLICY_FOR_LIST)
- Specify a list of apps allowed to use VPN.AppPolicy.newBuilder().policy(AppPolicy.POLICY_EXCEPT_LIST)
- Specify a list of apps not allowed to use VPN.
withReason(reason)
- Define the reason for starting the session usingunified.vpn.sdk.TrackingConstants.GprReasons
. Used for analytics.withLocation(location)
- Define the virtual location for the session.withCountry(country)
- Define the virtual country for the session.withPrivateGroup(group)
- Define a private server for the session.withVpnParams(params)
- Define VPN tunnel parameters, such as DNS servers and additional routes.addDnsRule(rule)
- Add a DNS rule for the session. More on Traffic rules page. For Hydra transport only.addProxyRule(rule)
- Add a proxy rule for the session. More on Traffic rules page. For Hydra transport only.withFireshieldConfig(config)
- Define categorization service rules. More on Fireshield resource page. For Hydra transport onlywithTransportFallback(fallbackOrder)
- Define the order of transports to fallback when an error occurs.keepVpnOnReconnect()
- Enable the kill switch to prevent traffic while the SDK is in the connection process or handling connection errors.
Examples
Start VPN with an optimal server
final SessionConfig session = new SessionConfig.Builder()
.withLocation(UnifiedSDK.COUNTRY_OPTIMAL)
.withReason(TrackingConstants.GprReasons.M_UI)
.build();
Start VPN for chrome only
final List<String> apps = new ArrayList<String();
apps.add("com.google.chrome");
final SessionConfig session = new SessionConfig.Builder()
.withLocation(UnifiedSDK.COUNTRY_OPTIMAL)
.withReason(TrackingConstants.GprReasons.M_UI)
.appPolicy(AppPolicy.newBuilder().policy(AppPolicy.POLICY_FOR_LIST).appList(apps).build())
.build();
Analytics Reasons
The following constants are used to specify the reason for starting the VPN session:
M_UI
- Manually started from the user interfaceM_SYSTEM
- Manually started from the systemM_OTHER
- Manually started from another placeA_APP_RUN
- Automatically started on app runA_RECONNECT
- Automatically started on reconnectA_ERROR
- Automatically started after an errorA_SLEEP
- Automatically started after sleepA_NETWORK
- Automatically started on a network eventA_OTHER
- Automatically started for other reasons
These constants are defined in the TrackingConstants.GprReasons
enum and can be used with the withReason
method when building the SessionConfig
.
Starting a VPN session
To start a VPN session:
final SessionConfig sessionConfig = new SessionConfig.Builder()
.build()
sdk.getVpn().start(sessionConfig, new CompletableCallback() {
@Override
public void complete() {
// Handle successful completion of VPN start
}
@Override
public void error(@NonNull VpnException e) {
// Handle error during VPN start
}
});
Obtain an instance of the
UnifiedSdk
class by calling thegetInstance()
method.Create a
SessionConfig
object using theSessionConfig.Builder
class. You can customize the session configuration by setting various options in the builder.Start the VPN session by calling the
start()
method on thegetVpn()
instance of theUnifiedSdk
.
The
complete()
method will be called when the VPN session starts successfully. You can add your logic to handle the successful start of the VPN here.The
error()
method will be called if an error occurs during the VPN start process. You can handle the error case and take appropriate actions based on theVpnException
received.
Stopping a VPN Session
To stop a VPN session:
sdk.getVpn().stop(TrackingConstants.GprReasons.M_UI, new CompletableCallback() {
@Override
public void complete() {
// VPN session stopped successfully
}
@Override
public void error(@NonNull VpnException e) {
// Failed to stop VPN session
}
});
Restarting a VPN Session
To restart a VPN session with a new configuration without entering the IDLE state:
final SessionConfig session = //create session config
sdk.getVpn().restart(session, new CompletableCallback() {
@Override
public void complete() {
// VPN session restarted successfully
}
@Override
public void error(@NonNull VpnException e) {
// Failed to restart VPN session
}
});
Updating Session Configuration
You can update certain VPN session configurations without restarting the VPN session. Currently, the SDK supports updating the following for the Hydra transport:
Fireshield rules
DNS Rules
Proxy Rules
Example:
final SessionConfig session = //create session config
sdk.getVpn().updateConfig(session, new CompletableCallback() {
@Override
public void complete() {
// Session configuration updated successfully
}
@Override
public void error(@NonNull VpnException e) {
// Failed to update session configuration
}
});
Listening for VPN Status and Traffic Updates
To listen for VPN status and traffic updates:
UnifiedSDK.addVpnStateListener(new VpnStateListener() {
@Override
public void vpnStateChanged(@NonNull VpnState vpnState) {
// Handle VPN state change
}
@Override
public void vpnError(@NonNull VpnException e) {
// Handle VPN error
}
});
UnifiedSDK.addTrafficListener(new TrafficListener() {
@Override
public void onTrafficUpdate(long rx, long tx) {
// Handle traffic update
}
});
// To stop listening for updates
UnifiedSDK.removeTrafficListener(...);
UnifiedSDK.removeVpnStateListener(...);
Getting Current VPN State
To get the current VPN state:
UnifiedSDK.getVpnState(new Callback<VpnState>() {
@Override
public void success(@NonNull VpnState vpnState) {
// Handle VPN state
}
@Override
public void failure(@NonNull VpnException e) {
// Handle failure to get VPN state
}
});
VPN States
IDLE - No active VPN session.
CONNECTING_PERMISSIONS - Requesting system VPN permission.
CONNECTING_CREDENTIALS - Loading backend information to establish a connection.
CONNECTING_VPN - Transport connection in progress.
DISCONNECTING - Disconnection started.
CONNECTED - VPN session is active and connected.
PAUSED - VPN session paused due to an error, network change, or waiting to restore the VPN session.
UNKNOWN - Not used, reserved.
ERROR - Not used, reserved.
Checking VPN Permissions
To check if the app has system VPN permissions granted:
final boolean granted = VpnPermissions.granted();
To request VPN permissions without connecting to the VPN:
VpnPermissions.request(new CompletableCallback() {
@Override
public void complete() {
// Permission granted
}
@Override
public void error(@NonNull VpnException e) {
// Failed to get permission
}
});
Getting Current VPN Session Information
To get the current VPN session information:
UnifiedSdk.getStatus(new Callback<SessionInfo>() {
@Override
public void success(@NonNull SessionInfo sessionInfo) {
// Handle session information (e.g., get sessionInfo.getConnectionStatus().getSuccessInfo())
}
@Override
public void failure(@NonNull VpnException e) {
// Handle failure to get session information
}
});
Last updated
Was this helpful?