API Reference

UnifiedSdk

The main entry point for the VPN SDK. Provides access to all SDK functionality including VPN connection management, authentication, and configuration.

Initialization

See Initialization.

Methods

init(Context context, ClientInfo clientInfo, UnifiedSdkConfig config)

Initializes the SDK with the provided configuration.

Parameters:

• context - Android application context

• clientInfo - Client configuration with carrier ID and server URLs

• config - SDK configuration options

getInstance()

Returns the singleton instance of UnifiedSdk.

Returns: UnifiedSdk instance

setLogging(Boolean enabled)

Enables or disables SDK logging.

Parameters:

• enabled - true to enable logging, false to disable

Vpn

Interface for managing VPN connections.

Methods

start(SessionConfig sessionConfig, CompletableCallback callback)

Starts a VPN connection with the specified configuration.

Parameters:

• sessionConfig - VPN session configuration

• callback - Completion callback

Example:

SessionConfig config = new SessionConfig.Builder()
    .withLocation("us")
    .withReason(TrackingConstants.GprReasons.M_UI)
    .build();

sdk.getVpn().start(config, new CompletableCallback() {
    @Override
    public void complete() {
        // VPN started successfully
    }

    @Override
    public void error(VpnException e) {
        // Handle error
    }
});

stop(String reason, CompletableCallback callback)

Stops the active VPN connection.

Parameters:

• reason - Reason for stopping (for analytics)

• callback - Completion callback

restart(SessionConfig sessionConfig, CompletableCallback callback)

Restarts the VPN connection with new configuration.

Parameters:

• sessionConfig - New session configuration

• callback - Completion callback

updateConfig(SessionConfig sessionConfig, CompletableCallback callback)

Updates the configuration of an active VPN session without disconnecting.

Parameters:

• sessionConfig - Updated session configuration

• callback - Completion callback

getStartTimestamp(Callback<Long> callback)

Gets the timestamp when the current VPN session started.

Parameters:

• callback - Callback with timestamp in milliseconds

Backend

Interface for authentication and user management.

See Backend interface.

Methods

login(AuthMethod auth, Callback<User> callback)

Authenticates a user with the backend.

Parameters:

• auth - Authentication method (e.g., AuthMethod.anonymous(), AuthMethod.firebase(token))

• callback - Callback with User object on success

Example:

sdk.getBackend().login(AuthMethod.anonymous(), new Callback<User>() {
    @Override
    public void success(User user) {
        // Login successful
    }

    @Override
    public void failure(VpnException e) {
        // Handle login failure
    }
});

logout(CompletableCallback callback)

Logs out the current user.

Parameters:

• callback - Completion callback

currentUser(Callback<User> callback)

Gets the currently authenticated user.

Parameters:

• callback - Callback with current User or null

isLoggedIn(Callback<Boolean> callback)

Checks if a user is currently logged in.

Parameters:

• callback - Callback with login status

locations(ConnectionType connectionType, Callback<AvailableLocations> callback)

Gets available VPN server locations.

Parameters:

• connectionType - Type of connection (e.g., ConnectionType.HYDRA_TCP)

• callback - Callback with available locations

remainingTraffic(Callback<RemainingTraffic> callback)

Gets remaining traffic allowance for the current user.

Parameters:

• callback - Callback with remaining traffic information

getAccessToken(Callback<String> callback)

Gets the current access token.

Parameters:

• callback - Callback with access token

purchase(String rawJson, CompletableCallback callback)

Processes a purchase transaction.

Parameters:

• rawJson - Purchase data in JSON format

• callback - Completion callback

Data Models

ClientInfo

Configuration for SDK initialization.

See Backend URL Configuration.

Builder Methods

ClientInfo clientInfo = new ClientInfo.Builder()
    .carrierId("your_carrier_id")
    .addUrl("https://api.example.com")
    .build();

Method	Description
carrierId(String)	Sets the carrier identifier
addUrl(String)	Adds a backend server URL
build()	Creates the ClientInfo instance

SessionConfig

Configuration for VPN sessions.

See VPN Interface.

Builder Methods

SessionConfig config = new SessionConfig.Builder()
    .withLocation("us")
    .withReason(TrackingConstants.GprReasons.M_UI)
    .withTransport(TransportMode.HYDRA_TCP)
    .withPolicy(SessionConfig.Policy.OPTIMAL_LOCATION)
    .withPrivateGroup("group_id")
    .withFireshieldConfig(fireshieldConfig)
    .build();

Method	Description
withLocation(String)	Sets the VPN server location
withReason(String)	Sets connection reason for analytics
withTransport(TransportMode)	Sets VPN transport protocol
withPolicy(Policy)	Sets connection policy
withPrivateGroup(String)	Sets private server group
withFireshieldConfig(FireshieldConfig)	Sets content filtering configuration
withDnsRules(List<DnsRule>)	Sets custom DNS rules
withBypassDomains(List<String>)	Sets domains to bypass VPN
build()	Creates the SessionConfig instance

Policy Enum

Value	Description
OPTIMAL_LOCATION	Automatically select best location
PRIORITY_LOCATION	Use specified location with fallback
STRICT_LOCATION	Use only specified location

VpnState

Enum representing VPN connection states.

State	Description
IDLE	VPN is not connected
CONNECTING_CREDENTIALS	Fetching connection credentials
CONNECTING_PERMISSIONS	Requesting VPN permissions
CONNECTING_VPN	Establishing VPN connection
CONNECTED	VPN is connected
PAUSED	VPN is paused
DISCONNECTING	VPN is disconnecting
ERROR	VPN encountered an error
UNKNOWN	Unknown state

SessionInfo

Information about the current VPN session.

Property	Type	Description
vpnState	VpnState	Current connection state
sessionConfig	SessionConfig	Active session configuration
credentials	VpnCredentials	Connection credentials
transport	TransportInfo	Transport protocol information
connectionStatus	ConnectionStatus	Detailed connection status

TrafficStats

Network traffic statistics.

Property	Type	Description
bytesTx	long	Bytes transmitted
bytesRx	long	Bytes received

User

User account information.

Property	Type	Description
id	String	User identifier
accessToken	String	Authentication token
subscriber	Subscriber	Subscription information

AvailableLocations

Container for available VPN locations.

Method	Description
getLocations()	Returns list of Location objects
getOptimal()	Returns optimal location for user

Location

VPN server location.

Property	Type	Description
country	String	Country code (ISO 3166-1 alpha-2)
city	String	City name
hub	String	Server hub identifier

Callbacks and Listeners

CompletableCallback

Callback for operations without return values.

public interface CompletableCallback {
    void complete();
    void error(VpnException e);
}

Callback

Generic callback for operations with return values.

public interface Callback<T> {
    void success(T data);
    void failure(VpnException e);
}

VpnStateListener

Listener for VPN state changes.

public interface VpnStateListener {
    void vpnStateChanged(VpnState state);
    void vpnError(VpnException e);
}

Registration:

sdk.getVpn().addVpnStateListener(new VpnStateListener() {
    @Override
    public void vpnStateChanged(VpnState state) {
        // Handle state change
    }

    @Override
    public void vpnError(VpnException e) {
        // Handle error
    }
});

TrafficListener

Listener for traffic statistics updates.

See Listening for VPN Status and Traffic Updates.

public interface TrafficListener {
    void onTrafficUpdate(TrafficStats stats);
}

Authentication Methods

See Authentication.

AuthMethod

Factory class for creating authentication methods.

Static Methods

Method	Description	Example
anonymous()	Anonymous authentication	AuthMethod.anonymous()
firebase(String token)	Firebase authentication	AuthMethod.firebase(firebaseToken)
custom(String method, String token)	Custom authentication	AuthMethod.custom("oauth", oauthToken)
github(String token)	GitHub authentication	AuthMethod.github(githubToken)

Exceptions

VpnException

Base exception class for SDK errors.

Property	Type	Description
message	String	Error message
code	int	Error code
cause	Throwable	Underlying cause

Common Error Codes

Code	Description
TRAFFIC_EXCEED	Traffic limit exceeded
UNAUTHORIZED	Authentication failed
NETWORK_ERROR	Network connection error
VPN_PERMISSION_DENIED	VPN permission not granted
CONNECTION_CANCELLED	Connection cancelled by user
INTERNAL_ERROR	Internal SDK error

NetworkRelatedException

Exception for network-related errors.

public class NetworkRelatedException extends VpnException {
    // Indicates network connectivity issues
}

ConnectionCancelledException

Exception when connection is cancelled.

public class ConnectionCancelledException extends VpnException {
    // Thrown when user cancels connection
}

Transport Modes

TransportMode

Enum for available VPN protocols.

Mode	Description
HYDRA_TCP	Hydra protocol over TCP
HYDRA_UDP	Hydra protocol over UDP
OPENVPN_TCP	OpenVPN over TCP
OPENVPN_UDP	OpenVPN over UDP
WIREGUARD	WireGuard protocol

Content Filtering (CNL)

Cnl

Interface for content filtering and blocking lists.

Methods

enableCnl(CnlConfig config, CompletableCallback callback)

Enables content filtering.

Parameters:

• config - CNL configuration

• callback - Completion callback

disableCnl(CompletableCallback callback)

Disables content filtering.

Parameters:

• callback - Completion callback

getCnlState(Callback<CnlState> callback)

Gets current CNL state.

Parameters:

• callback - Callback with CNL state

CnlConfig

Configuration for content filtering.

CnlConfig config = new CnlConfig.Builder()
    .addBlockedCategory(CnlCategory.ADULT)
    .addBlockedCategory(CnlCategory.MALWARE)
    .addCustomBlockedDomain("example.com")
    .build();

Method	Description
addBlockedCategory(CnlCategory)	Adds category to block
addCustomBlockedDomain(String)	Adds custom domain to block
addCustomAllowedDomain(String)	Adds custom domain to allow

CnlCategory

Enum for content categories.

Category	Description
ADULT	Adult content
MALWARE	Malicious websites
PHISHING	Phishing sites
ADS	Advertisement servers
TRACKING	Tracking servers
GAMBLING	Gambling sites
SOCIAL_MEDIA	Social media platforms

Fireshield Configuration

FireshieldConfig

Advanced firewall and security configuration.

FireshieldConfig config = new FireshieldConfig.Builder()
    .mode(FireshieldMode.ENABLED)
    .addService(FireshieldService.builder()
        .protocol(Protocol.TCP)
        .port(80)
        .build())
    .build();

Method	Description
mode(FireshieldMode)	Sets Fireshield mode
addService(FireshieldService)	Adds service configuration
userCategories(List<Integer>)	Sets user-defined categories

FireshieldMode

Mode	Description
DISABLED	Fireshield disabled
ENABLED	Fireshield enabled
SILENT	Silent mode (logging only)

Migration and Compatibility

SDK Version

String version = UnifiedSdk.getVersion();

Minimum Requirements

• Android API Level: 21 (Android 5.0)

• Compile SDK Version: 33

• Target SDK Version: 33

Permissions Required

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

ProGuard Rules

See Proguard Rules