Datami Android VPN SDK

Introduction
Assumptions
Compatibility
Integration Steps
Obfuscation
Social media or Streaming usage
When building an Android App Bundle
1 Getting started with 'initSponsoredData' API
1.1 Add required compile option and dependencies in app level build.gradle file
1.2 Call 'initSponsoredData' API for sponsoring data over App vpn connection
1.3 Call 'initSponsoredData' API for initialization without setting VPN
1.4 Call 'initSponsoredData' API for sponsoring data over App vpn connection with custom retry.
1.5 Call 'initSponsoredData' API for sponsoring data over App vpn connection with controlled VPN permission display to user.
1.6 Add below configuration to support latest android version
1.7 Call 'startSponsoredData' API
1.8 Call 'stopSponsoredData' API
1.9 Call 'vpnHealthCheck' API
1.10 Call 'isVpnPermissionAccepted' API
1.11 Setup a listener for Sponsored Data state changes in your Application class (Optional)
1.12 Call 'initSponsoredData' API for initialization with user-tags
1.13 Using 'updateUserTag' API
2. API Reference
2.1 API for sponsoring entire application traffic through VPN
2.2 VPN API initialization without setting VPN
2.3 VPN API initialization with customised retry count
2.4 VPN API initialization with controlled VPN permission
2.5 VPN API to get the VPN connection state
2.6 VPN API to get the VPN permission status
2.7 VPN API initialization with user-tags
2.8 Update User Tags API
3 Testing and Verification
3.1 Initial Integration Testing
3.2 Sponsored Data Testing
4 Performance
4.1 Initialization Overhead
4.2 Runtime Overhead

Introduction
Datami VPN SDK for Android provides class libraries, code samples and documentation to help developers building Sponsored Data enabled
applications using VPN.

Assumptions
1. An SDK API access key is provisioned in Datami and provided to the application for integration with Datami SDK.
2. A sponsored data campaign is configured in the Datami portal for testing the application with Datami SDK.
3. Application developer has a physical Android device with a SIM that works on the mobile network which is integrated with Datami.

Compatibility
The Datami Android SDK is compatible with Android 4.4 (API Level 19) or higher.
Integration Steps
Datami will provide an API key required for the integration. Use the API key to activate the SDK through the API.
To sponsor all the VPN traffic to/from the App
1. Include the Datami Android SDK library (vpnsdk-android.aar) in your project.
2. Configure proguard/dexguard properties (See 'Obfuscation' section below)
3. Set the compile options and dependencies in the app level build.gradle file (See Section 1.1).
4. If app is targeting API 28+ (Android 9 Pie), please include the changes as per Android 9 Pie Support (See below)

Obfuscation
Datami Android SDK library is obfuscated using ProGuard/DexGuard tool. If your app uses obfuscation, please add the following lines into your
proguard/dexguard configuration file.

proguard

-dontwarn com.datami.**
# Keep classes under smisdk
-keep class com.datami.** {
*;
}

Social media or Streaming usage

If application allow navigation to any social media or streaming links like Facebook, Instagram, Twitter, Youtube. These will get
sponsored as part of application and allow users to consume the social network sites with free data. This may lead to high sponsored data
usage for the applications.

Since it is part of the application – Datami will be considering this as sponsored data usage. If that is not the intention, please take steps to
block these links when the application is being sponsored. Please let us know if we can help.

When building an Android App Bundle

Disable UncompressedNativeLibs in gradle.properties file using following. Sync, Clean & Re-build the project.

gradle.properties

android.bundle.enableUncompressedNativeLibs=false

1 Getting started with 'initSponsoredData' API

1.1 Add required compile option and dependencies in app level build.gradle file

a. Java version 1.8 Compatibility

b. Multidex support
 build.gradle

android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}

defaultConfig {
...
multiDexEnabled true
...
}
}

dependencies {
...
compile 'com.android.support:multidex:+'
...
}

c. Multidex support for 4.4 android versions- Application class must be derived from MultiDexApplication

MyApplication.java

public class MyApplication extends MultiDexApplication{

public void onCreate(){

...
}

...
}

1.2 Call 'initSponsoredData' API for sponsoring data over App vpn connection
 initSponsoredData()

import com.datami.smi.SmiVpnSdk;
import com.datami.smi.internal.MessagingType;
..

String sdkKey = <SDK_KEY_PROVIDED_BY_DATAMI>;

SmiVpnSdk.initSponsoredData(sdkKey, this, R.drawable.
ic_launcher, MessagingType.BOTH);

1.3 Call 'initSponsoredData' API for initialization without setting VPN

This api is just for initialization without setting VPN. Later VPN can be set/reset using startSponsoredData()/stopSponsredData() apis.

initSponsoredData()

import com.datami.smi.SmiVpnSdk;
import com.datami.smi.internal.MessagingType;
..

String sdkKey = <SDK_KEY_PROVIDED_BY_DATAMI>;

SmiVpnSdk.initSponsoredData(sdkKey, this, R.drawable.
ic_launcher, MessagingType.BOTH, false);

1.4 Call 'initSponsoredData' API for sponsoring data over App vpn connection with custom retry.

This api is for initialization of app with customised retry count. The initialization can be done with or without setting of VPN.

NOTE: This API introduced in SDK version 3.6.0

initSponsoredData()

import com.datami.smi.SmiVpnSdk;
import com.datami.smi.internal.MessagingType;
..

String sdkKey = <SDK_KEY_PROVIDED_BY_DATAMI>;

int retryCount = <CUSTOME_RETRY_COUNT>;
SmiVpnSdk.initSponsoredData(sdkKey, this, R.drawable.
ic_launcher, MessagingType.BOTH, true, retryCount);
1.5 Call 'initSponsoredData' API for sponsoring data over App vpn connection with controlled VPN permission display to user.

This api is for initialization of app with controlled vpn permission. The initialization should be done without setting of VPN and the system
Permission popup will be accessible on startSponsoredData() API.

NOTE: This API introduced in SDK version 3.7.3

initSponsoredData()

import com.datami.smi.SmiVpnSdk;
import com.datami.smi.internal.MessagingType;
..

String sdkKey = <SDK_KEY_PROVIDED_BY_DATAMI>;

int retryCount = <CUSTOME_RETRY_COUNT>;
boolean controlledVpn = true;

SmiVpnSdk.initSponsoredData(sdkKey, this, R.drawable.

ic_launcher, MessagingType.BOTH, false, retryCount, controlledVpn);

1.6 Add below configuration to support latest android version

1. Allow Apache HTTP library in AndroidManifest.xml

2. Also add the FOREGROUND_SERVICE permission to AndroidManifest.xml

Apache HTTP for API 28+

<uses-library android:name="org.apache.http.legacy" android:

required="false"/>
<uses-permission android:name="android.permission.
FOREGROUND_SERVICE" />

3. Add the Network Security Configuration as below:

a. In the res/xml/network_security_config.xml add the rules to allow HTTP connections to cloudmi.datami.com and vpn.
status.internal.datami domain
 Network Security Config

<?xml version="1.0" encoding="utf-8"?>

<network-security-config>
<domain-config cleartextTrafficPermitted="true">
<domain includeSubdomains="true">cloudmi.datami.com<
/domain>
<domain includeSubdomains="true">vpn.status.
internal.datami</domain>
</domain-config>
</network-security-config>

b. If you are pinning the SSL certificates then in the res/xml/network_security_config.xml add the rules to allow HTTP
connections to cloudmi.datami.com and vpn.status.internal.datami domain.

Network Security Config

<?xml version="1.0" encoding="utf-8"?>

<network-security-config>
<base-config>
<trust-anchors>
<certificates src="system"/>
<domain-config cleartextTrafficPermitted="
true">
<domain includeSubdomains="true"
>cloudmi.datami.com</domain>
<domain includeSubdomains="
true">vpn.status.internal.datami</domain>
</domain-config>
</trust-anchors>
</base-config>
</network-security-config>

c. Add the network security config to AndroidManifest.xml

 AndroidManifest with network security config

<?xml version="1.0" encoding="utf-8"?>

<manifest ... >
<application android:networkSecurityConfig="@xml
/network_security_config"
... >
...
</application>
</manifest>

4. If you're migrating to AndroidX. Make your project use Jetifier and write below code in gradle.properties.

gradle.properties

android.enableJetifier=true
android.useAndroidX=true

1.7 Call 'startSponsoredData' API

This api can be used to start sponsor data by starting the VPN if it has not started by initSponsoredData() api as mentioned in section 1.3 or
previously stopped by calling stopSponsoredData() api as mentioned in section 1.5.

startSponsoredData()

import com.datami.smi.SmiVpnSdk;
..

try{
SmiVpnSdk.startSponsoredData();
}catch(Exception e){
...
}

1.8 Call 'stopSponsoredData' API

This api can be used to stop sponsor data by stopping the VPN if it has already started by calling initSponsoredData() api or startSponsoredData()
api.
 stopSponsoredData()

import com.datami.smi.SmiVpnSdk;
..

SmiVpnSdk.stopSponsoredData();

1.9 Call 'vpnHealthCheck' API

This api can be used to get the VPN connection state. This api is non-blocking api and can be called from any thread.

vpnHealthCheck()

import com.datami.smi.SmiVpnSdk;
..

int connectionState = SmiVpnSdk.vpnHealthCheck();

1.10 Call 'isVpnPermissionAccepted' API

This api can be used to get the VPN permission status

isVpnPermissionAccepted()

import com.datami.smi.SmiVpnSdk;
..

boolean permissionAccepted = SmiVpnSdk.

isVpnPermissionAccepted();
if(!permissionAccepted){
//make call to set up VPN once again.
SmiVpnSdk.startSponsoredData();
}

1.11 Setup a listener for Sponsored Data state changes in your Application class (Optional)

Datami Android SDK provides SdStateChangeListener interface to receive sponsored data state changes while application is running. The
application will use current sponsored data state to display appropriate custom message to its users.
 OnChange listener

public class MyApplication extends Application implements

SdStateChangeListener{
...
@Override
public void onChange(SmiResult currentSmiResult) {
SdState sdState = currentSmiResult.getSdState();
Log.d(TAG, "sponsored data state : "+sdState);
if(sdState == SdState.SD_AVAILABLE) {
// TODO: show a banner or message to user, indicating that
the data usage is sponsored and charges do not apply to user data plan
} else if(sdState == SdState.SD_NOT_AVAILABLE) {
// TODO: show a banner or message to user, indicating that
the data usage is NOT sponsored and charges apply to user data plan
Log.d(TAG, " - reason: " + currentSmiResult.getSdReason());
} else if(sdState == SdState.SD_WiFI) {
// device is in wifi
}
}
...
}

1.12 Call 'initSponsoredData' API for initialization with user-tags

This api is for initialization of app with user-tags. Using this API the sponsorship can be controlled to specific user base.

NOTE: This API introduced in SDK version 3.8.6

initSponsoredData()

import com.datami.smi.SmiVpnSdk;
import com.datami.smi.internal.MessagingType;
..

String sdkKey = <SDK_KEY_PROVIDED_BY_DATAMI>;

int retryCount = 0;
boolean controlledVpn = false;
List<String> tags = new ArrayList<>();
tags.add("tag1");
tags.add("tag2");

SmiVpnSdk.initSponsoredData(sdkKey, this, R.drawable.

ic_launcher, MessagingType.BOTH, true, retryCount, controlledVpn, tags);
1.13 Using 'updateUserTag' API

Apps can pass a list of tags to the SDK for segmentation. These can then be updated as per requirement.

SDK will always keep recent tags and will replace the old tag/tags if any.

NOTE:

1. This API introduced in SDK version 3.8.6

2. Max 32 characters are supported for a tag
3. The tags must be alphanumeric.
4. Max 6 Tags are supported

updateUserTag()

....

List<String> tags = new ArrayList<>();

tags.add("tag1");
tags.add("tag2");

SmiVpnSdk.updateUserTag(tags);
....

2. API Reference

2.1 API for sponsoring entire application traffic through VPN

This API is used for sponsoring all VPN traffic to/from an application on cellular networks. The API signature is as follows:

void initSponsoredData (String sdkKey, Context context, int iconId, MessagingType messagingType);

initSponsoredData API parameter details:

Name Type Description [M]andatory/[O]ption

al

sdkKey String The API Access Key provided by Datami M

context Context The application context M

iconId int The iconId for notification icon in notification bar and notification drawer. It can be -1. M

When it is provided, the SDK displays the icon in notification bar and drawer when data is
sponsored.

ex.R.drawable.ic_launcher. Or -1

messagingType MessagingType Following messaging type supported: M

NONE (No messages)
NOTIFICATION (Only notification)
POPUP (Only popup)
BOTH (both notification & popup)

2.2 VPN API initialization without setting VPN

This API is used for VPN api initialization and VPN can be set/reset using startSponsoredData()/stopSponsoredData() apis. The API signature is
as follows:
void initSponsoredData (String sdkKey, Context context, int iconId, MessagingType messagingType, boolean startVPN);

initSponsoredData API parameter details:

Name Type Description [M]andatory/[O]ption

al

sdkKey String The API Access Key provided by Datami M

context Context The application context M

iconId int The iconId for notification icon in notification bar and notification drawer. It can be -1. M

When it is provided, the SDK displays the icon in notification bar and drawer when data is
sponsored.

ex.R.drawable.ic_launcher. Or -1

messagingType MessagingType Following messaging type supported: M

NONE (No messages)
NOTIFICATION (Only notification)
POPUP (Only popup)
BOTH (both notification & popup)

startVPN Boolean TRUE - To set VPN with api initialization. M

FALSE - Initialize api without setting VPN.

2.3 VPN API initialization with customised retry count

This API is used for sponsoring all VPN traffic to/from an application on cellular networks with customised retry count. The initialization can be
done with or without setting of VPN. The API signature is as follows:

void initSponsoredData (String sdkKey, Context context, int iconId, MessagingType messagingType, boolean startVPN, int
vpnConnectRetry);

initSponsoredData API parameter details:

Name Type Description [M]andatory/[O]ption

al

sdkKey String The API Access Key provided by Datami M

context Context The application context M

iconId int The iconId for notification icon in notification bar and notification drawer. It can be -1. M

When it is provided, the SDK displays the icon in notification bar and drawer when data is
sponsored.

ex.R.drawable.ic_launcher. Or -1

messagingType MessagingType Following messaging type supported: M

NONE (No messages)
NOTIFICATION (Only notification)
POPUP (Only popup)
BOTH (both notification & popup)

startVPN Boolean TRUE - To set VPN with api initialization. M

FALSE - Initialize api without setting VPN.

vpnConnectRet int Customised retry count M

ry

2.4 VPN API initialization with controlled VPN permission

This API is used for sponsoring all VPN traffic to/from an application on cellular networks with controlled VPN permission. The initialization should
be done without setting of VPN. The API signature is as follows:

void initSponsoredData (String sdkKey, Context context, int iconId, MessagingType messagingType, boolean startVPN, int
vpnConnectRetry, boolean controlledVpnConnection);
initSponsoredData API parameter details:

Name Type Description [M]andatory/[O]ptio

nal

sdkKey String The API Access Key provided by Datami M

context Context The application context M

iconId int The iconId for notification icon in notification bar and notification drawer. It can be -1. M

When it is provided, the SDK displays the icon in notification bar and drawer when data is
sponsored.

ex.R.drawable.ic_launcher. Or -1

messagingType MessagingTy Following messaging type supported: M

pe NONE (No messages)
NOTIFICATION (Only notification)
POPUP (Only popup)
BOTH (both notification & popup)

startVPN Boolean FALSE - Initialize api without setting VPN. M

vpnConnectRetry int Customised retry count M

controlledVpnConnect Boolean TRUE - Show system vpn popup only on call of startSponsoredData() API. M
ion

2.5 VPN API to get the VPN connection state

This API is used for VPN to get the current connection state. The API signature is as follows:

int vpnHealthCheck ();

vpnHealthCheck API return values details:

Name Type Value Description [M]andatory/[O]ptional

Return values int 1 Robust Connection M

0 Poor Connection

-1 Failed

2.6 VPN API to get the VPN permission status

This API is used to get whether user has accepted the permission or not. If not then we can setup vpn once again on user acceptance.

The API signature is as follows:

boolean isVpnPermissionAccepted ();

isVpnPermissionAccepted API return values details:

Name Type Value Description [M]andatory/[O]ptional

Return values boolean TRUE User has already accepted the permission M

FALSE User has rejected the permission

2.7 VPN API initialization with user-tags

This API is used for sponsoring all VPN traffic to/from an application on cellular networks with user tags. The API signature is as follows:

void initSponsoredData (String sdkKey, Context context, int iconId, MessagingType messagingType, boolean startVPN, int
vpnConnectRetry, boolean controlledVpnConnection, List<String> userTags);

initSponsoredData API parameter details:

Name Type Description [M]andatory/[O]ptio

nal
 sdkKey String The API Access Key provided by Datami M

context Context The application context M

iconId int The iconId for notification icon in notification bar and notification drawer. It can be -1. M

When it is provided, the SDK displays the icon in notification bar and drawer when data is
sponsored.

ex.R.drawable.ic_launcher. Or -1

messagingType MessagingTy Following messaging type supported: M

pe NONE (No messages)
NOTIFICATION (Only notification)
POPUP (Only popup)
BOTH (both notification & popup)

startVPN Boolean FALSE - Initialize api without setting VPN. M

vpnConnectRetry int Customised retry count (default should be 0) M

controlledVpnConnect Boolean TRUE - Show system vpn popup only on call of startSponsoredData() API. M
ion
FALSE - The standard way.

userTags List<String> List of tags M

2.8 Update User Tags API

This API is used to update the tags in the SDK. The API signature is as follows:
void updateUserTag(List<String> tags);

updateUserTag API parameter details:

Name Type Description [M]andatory/[O]ptional

tags List<String> List of tags M

3 Testing and Verification

3.1 Initial Integration Testing

When SDK integration is complete, the following basic tests should be done by an application developer (before an active sponsored data
campaign is configured in Datami Portal):

1. Open the application in WiFi and verify that the SDK returns the SmiResult with sdState = SdState.WIFI.
2. Open the application in cellular mode and verify that the SDK returns the SmiResult with sdState = SdState.SD_NOT_AVAILABLE and
sdReason = SdReason. SD_NOT_AVAILABLE_PROMOTION_NOT_FOUND as there is no active campaign for your app at this time
3. Switch between WiFi and cellular, and verify that the SDK notifies the sdState accordingly.

3.2 Sponsored Data Testing

The following tests can be carried out when SDK integration is complete and there is an active campaign configured in the Datami Portal:

1. Open the application in cellular mode and verify that the SDK returns the SmiResult with sdState = SdState.SD_AVAILABLE.
2. Use the application in cellular and verify that the data usage in Datami portal increases for the campaign.
3. Use the application in WIFI and verify the data usage in Datami portal doesn’t increase for the campaign.

Note: The integrated application needs to be shared with Datami and cellular operator for complete testing and verification, including zero rating
verification.

4 Performance

4.1 Initialization Overhead

The 'initSponsoredData' API is asynchronous and it doesn’t block the calling application.
4.2 Runtime Overhead

The Datami SDK routes the traffic through Datami Gateway which can add a minor latency from 25 ms to 50 ms to the data path. The Datami
gateway(s) are deployed either within or close to wireless carrier core network to minimize the delays. However, Datami offers different
deployment models to minimize network latencies. The application developer can request for testing the correct integration from Datami.