VPN Unlimited SDK v1.2 for Android
Getting startedOverview
VPN Unlimited SDK for Android is shipped as a distribution of an Android Library Project. It is written in Java and C++ and is available for Android 4.0 and later.
Setup
Drag and drop VpnUnlimitedSDK.aar into your project libs folder.
In order to use it you have to add following lines of code to yours build.gradle
dependencies {
compile(name:'VpnUnlimitedSDK', ext:'aar')
}
After setup is done you should be able to use all the classes from SDK by including it with import keepsolid.com.androidvpnunlimitedsdk.*; directive.
Note:
Current version of VPN Unlimited SDK uses the following libraries under the hood:
- libcurl
- libopenssl
- libcares
- libcrypto
- xopenssl
If your project uses one of these libraries and you get conflicts please contact VPN Unlimited team for further investigation.
Using App ID and App secret
Use the following setup code in your Application class onCreate() method:
VPNUFacade.getInstance().prepare(getApplicationContext(),
Constants.APPLICATION_ID, Constants.APPLICATION_SECRET);
Classes
This SDK is designed in classical OOP style. We don't provide one single interface, but rather a handful of interfaces which you can use in any desired combination. All network calls are synchronous, so you should never call them from main thread. This limitation is highlighted by the fact, that you actually can perform several steps in a row serially on secondary thread and come back to main thread with a desired result.
Here is the complete list of classes:
- LocalizedResponseProvider
- OpenVpnStatus
- OpenVpnStatusChangedListener
- VPNUAccountDevice
- VPNUAccountDeviceStatistic
- VPNUAccountManager
- VPNUAccountStatus
- VPNUAccountUserInfo
- VPNUAuthDelegate
- VPNUAuthDelegate.Response
- VPNUAuthorizer
- VPNUConfigurator
- VPNUDefaultLocalizedResponseProvider
- VPNUException
- VPNUFacade
- VPNUImageLoader
- VPNUImageRequest
- VPNUImageResponse
- VPNULocationCoordinate2D
- VPNUProxyConfiguration
- VPNUProxyManager
- VPNUPurchaseItem
- VPNUPurchaseManager
- VPNURequest
- VPNURequestBuilder
- VPNUResponse
- VPNUServer
- VPNUServersManager
- VPNUTransport
You can see the complete documentation for each class at Reference page.
Here we just briefly describe the standard workflow.
VPNUFacade
The VPNUFacade is to some degree the main class in SDK. It provides interfaces to all SDK APIs, namely:
- VPNUAuthorizer
- VPNUAccountManager
- VPNUPurchaseManager
- VPNUServersManager
- VPNUTransport
- VPNUProxyManager
- LocalizedResponseProvider
- VPNUImageLoader
- VPNUConfigurator
- VPNURequestBuilder
Multithreading
As stated previously, all network calls in this SDK are performed synchronously. That means that you should perform them all on a non-main thread, otherwise it would block it and never come back. Every method which falls into this category is explicitly documented.
FAQ
In every example in the FAQ section it is implicitly considered that SDK is set up properly before any calls:
VPNUFacade.getInstance().prepare(getApplicationContext(),
Constants.APPLICATION_ID, Constants.APPLICATION_SECRET);
It is also considered that the code is executing on a secondary thread, for example:
new Thread(new Runnable() {
@Override
public void run() {
//SDK calls
}
}).start();
How to login with existing user?
First, setup VPNUAuthorizer instance.
VPNUAuthorizer vpnuAuthorizer = VPNUFacade.getInstance().getVpnuAuthorizer();
Then, you can log in using user's credentials:
String login = "login@some.domain";
String password = "password";
try {
VPNUAccountUserInfo userInfo = vpnuAuthorizer.authorizeWithLogin(login, password);
} catch (VPNUException exception) {
Log.v(LOG_TAG, "authorization failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}
If authorization is successful, the VPNUTransport instance is managing the newly created session and reconnects automatically when this session is expired. Retrieved authorization info is saved into VPNUAccountUserInfo
How to register a new user?
First, setup VPNUAuthorizer instance.
VPNUAuthorizer vpnuAuthorizer = VPNUFacade.getInstance().getVpnuAuthorizer();
Then, you can register new user using user's credentials. VPNUAuthorizer#registerWithLogin will automatically log in a newly created user.
String login = "login@some.domain";
String password = "password";
try {
VPNUAccountUserInfo userInfo = vpnuAuthorizer.registerWithLogin(login, password);
} catch (VPNUException exception) {
Log.v(LOG_TAG, "registration failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}
How to log out logged in user?
You have to be logged in in order to perform this operation successfully. See two previous answers.
boolean signOutSuccessful = false;
try {
signOutSuccessful = vpnuAuthorizer.signOut();
} catch (VPNUException exception) {
Log.v(LOG_TAG, "Log out failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}
How to retrieve account status of logged in user?
Assuming you are logged in:
try {
VPNUAccountManager vpnuAccountManager = VPNUFacade.getInstance().getVpnuAccountManager();
VPNUAccountStatus accountStatus = vpnuAccountManager.getStatus();
} catch (VPNUException exception) {
Log.v(LOG_TAG, "Status loading failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}
How to retrieve the list of available VPN servers?
try {
VPNUServersManager vpnuServersManager = VPNUFacade.getInstance().getVpnuServersManager();
List<VPNUServer> servers = vpnuServersManager.getServers();
} catch (VPNUException exception) {
Log.v(LOG_TAG, "Servers list loading failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}
How to connect to selected VPN server?
First, setup VPNUConfigurator instance.
VPNUConfigurator vpnuConfigurator = VPNUFacade.getInstance().getVpnuConfigurator();
Then you can setup the selected server item (see previous question on how to retrieve it). You can choose to set obfuscate mode on or off by passing boolean parameter to the VPNUConfigurator#setup method.
try {
VPNUConfigurator vpnuConfigurator = VPNUFacade.getInstance().getVpnuConfigurator();
vpnuConfigurator.prepare();
vpnuConfigurator.setup(server, false);
} catch (VPNUException exception) {
Log.v(LOG_TAG, "set up of Vpn failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}
You then can try to connect to a selected server. In order to obtain the connection status, use the OpenVpnStatusChangedListener by passing an instance to the VPNUConfigurator#addOnStatusChangedListener method of VPNUConfigurator. This method blocks a calling thread.
try {
VPNUConfigurator vpnuConfigurator = VPNUFacade.getInstance().getVpnuConfigurator();
vpnuConfigurator.startVpn();
} catch (VPNUException exception) {
Log.v(LOG_TAG, "start Vpn failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}
How to stop VPN connection?
try {
VPNUConfigurator vpnuConfigurator = VPNUFacade.getInstance().getVpnuConfigurator();
vpnuConfigurator.stopVpn();
} catch (VPNUException exception) {
Log.v(LOG_TAG, "Stop Vpn failed with error code: " + exception.getResponse().getResponseCode()
+ ", and error msg " + exception.getResponse().getResponseMessage());
exception.printStackTrace();
}