Datami Android SDK

Introduction
EULA
Assumptions
Upgrade Steps
Integration Steps
Compatibility
Obfuscation
Limitations
1 Getting started with 'initSponsoredData' API
1.1 Add required permissions and entries in AndroidManifest.xml for 'initSponsoredData' API
1.2 Call 'initSponsoredData' API at the start of your Application onCreate() method
1.3 Setup a listener for Sponsored Data state changes in your Application class
1.4 Setup User Communication
1.5 Sponsored Data Support for Playback Media
1.5.1 Sponsored Data Support for Android Download Manager Content
1.6 Videos in WebViews
1.6.1 Using SmiWebView directly in your application
1.6.2 Using a sub-class of SmiWebView in your application
1.6.3 Using SmiWebView in the XML
1.7 Client IP and Carrier Name APIs
2 Using the 'stopSponsoredData' API
2.1 Sample Code for using the 'stopSponsoredData' API
3 Using the 'startSponsoredData' API
3.1 Sample Code for using the 'startSponsoredData' API
4 Using 'getSDAuth' API
4.1 Add required permissions and entries in AndroidManifest.xml for 'getSDAuth' API
4.2 Call 'getSDAuth' API for intended URL
5 Using 'getAnalytics' API
5.1 Sample Code using the 'getAnalytics' API
6 Using 'updateUserId' API
7 Using 'updateUserTag' API
8 Using 'getClientIP' API
9 Hybrid app integration
9.1 Integration Steps
9.2 Getting started with getSDAuth() API
9.3 Sponsoring Video Inside WebView
9.4 Listen to SD State Change in JS
9.5 Analytics API in Cordova JS
9.6 getSDAuth API in Cordova JS
9.7 updateUserId API in Cordova JS
9.8 updateUserTag API in Cordova JS
10 Testing and Verification
10.1 Initial Integration Testing
10.2 Sponsored Data Testing
11 Performance
11.1 Logging Overhead
11.2 Initialization Overhead
11.3 Runtime Overhead
12 Error Codes returned by SDK
13 Best Practices
14 FAQ
Appendix:
API Reference
I. API for sponsoring entire application
II. API for Stopping sponsored data
III. API for re-Starting sponsored data
IV. API for sponsoring Single Content URL
V. SDK Analytics API
Analytics getAnalytics();
VI. Update UserId API
VII. Update User Tags API
VIII. Get Client IP API

Introduction
Datami SDK (aka SmiSdk) for Android provides class libraries, code samples and documentation to help developers building Sponsored Data
enabled applications. It supports the following types of use-cases:

1.
 1. Sponsoring entire application - all HTTP(s) traffic from the App using the standard device frameworks will be enabled for sponsorship.
2. Sponsoring specific content URL – a single HTTP(S) URL may be sponsored in the App instead of the entire App

EULA
https://s3.amazonaws.com/smisdk-release/DataMi+SDK+License+Agreement+-+Non-Ink+Email_WorldWide.pdf

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.

Upgrade Steps
Upgrading from any previous release to 2.0.7+
Drop in the new SDK jar (if using jar based integration)
Remove NetworkChangeReceiver from AndroidManifest.xml

Removed NetworkChangeReceiver

//network change receiver

<receiver android:name="com.datami.smi.NetworkChangeReceiver">
<intent-filter >
<action android:name
="android.net.conn.CONNECTIVITY_CHANGE"/>
</intent-filter>
</receiver>

Remove SmiIntentService from Androidmanifest.xml

Removed SmiIntentService

//SmiIntentService
<service android:name= "com.datami.smi.SmiIntentService"/>

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 traffic to/from the App
1. Import Datami Android SDK using one of the following method
a. Using Gradle
i. In your top level gradle file add our maven repo.
 Top Level Gradle File

allprojects {
repositories {
jcenter()
.....
maven {
url
'https://s3.amazonaws.com/sdk-ga-releases.cloudmi.dat
ami.com/android/mvn/smisdk/'
}
}
}

ii. In your app level gradle file, add the sdk.

App Level Gradle File

dependencies {
......
compile 'com.datami:smisdk:+'
}

iii. Perform Gradle Sync

b. Manual Import
i. Add smisdk-android.jar to your libs folder.
2. Configure proguard/dexguard properties (See 'Obfuscation' section below)
3. Include required permissions and entries in AndroidManifest.xml (See Section 1.1).
4. Add config to support latest android versions.
a. Allow Apache HTTP library in AndroidManifest.xml
b. 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" />

c. Add the Network Security Configuration as below:

i. In the res/xml/network_security_config.xml add the rules to allow HTTP connections to cloudmi.data
mi.com
 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-config>
</network-security-config>

ii. 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

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-config>
</trust-anchors>
</base-config>
</network-security-config>

iii. 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>

5. Call the initSponsoredData() api at the start of your Application onCreate method (See Section 1.2).

a.
 5.

a. Note: The SDK must be initialized before App initiates any network traffic so the user does not get charged for the
mobile data.
6. Setup a listener to receive sponsored data status from Datami SDK (See Section 1.3).
7. Setup User Communication (See Section 1.4). This is optional and should be done to adequately
communicate the sponsored data status to the user.
8. If the application uses any of the below, please use getSDAuth() api in addition to the
initSponsoredData() (See Section 1.5) :
a. Playback Media through native player.
b. Android Download Manager.
9. Use SmiWebView for covering videos in WebViews (See Section 1.6)
10. Integrate with Datami Analytics API to give a feedback to app users for improving your app engagement. This is optional.
To sponsor data for individual object/URL
1. Integrate Datami Android SDK using one of the method described above.
2. Configure proguard/dexguard properties (See 'Obfuscation' section below)
3. Set the permissions in the AndroidManifest.xml (See Section 4.1).
4. Call the api getSDAuth(See section 4.2) for any url that needs to sponsored.

Compatibility
The Datami Android SDK is compatible with Android 4.0 (API Level 14) or higher.

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.

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

Limitations
1. No support for UDP or RTP/RTSP in the current release.
2. If App makes any direct socket connections or VPN connections with the back-end – it requires a custom API. Not supported by standard
SDK.
3. If the App has embedded video that is hosted by third parties and uses the third party video players or third party java scripts to play the
videos - this may require Datami custom API for third party videos and varies case to case depending on the implementation. Datami can
recommend the best approach for this use case after looking at the implementation.
NOTE: if the app uses native player then the videos can be supported using the URL api already available in the SDK.
4. Youtube and Facebook videos are not sponsored in general
5. Firebase Analytics using native sdk is not sponsored.
6. Use cases that are supported with additional integration:
a. Videos that use native player
b. Some third party video players.
c. Use of android download manager within the App is supported by use of URL API in the SDK

1 Getting started with 'initSponsoredData' API

The initSponsoredData() API needs to be called at the beginning of application’s onCreate method. This is to avoid any network connections not
getting sponsored. Please see the code sample in section 1.2

1.1 Add required permissions and entries in AndroidManifest.xml for 'initSponsoredData' API
 <!-- SmiSdk Required Permissions -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"
/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<!-- SmiSdk Intent Service required for all APIs -->

<service android:name="com.datami.smi.SmiIntentService" />

1.2 Call 'initSponsoredData' API at the start of your Application onCreate() method
Sample code for using getAppSDAuth API

import com.datami.smi.SmiResult;
import com.datami.smi.SdState;
import com.datami.smi.SmiSdk;
...
public class MyApplication extends Application implements
SdStateChangeListener {
...
protected void onCreate() {
super.onCreate();
// Call the Datami API at the beginning of onCreate, before other
initializations.
// IMPORTANT: If Datami API is not the first API called in the
application then any network
// connection made before Datami SDK initialization will be
non-sponsored and will be
// charged to the user.

String mySdkKey = “abcd1234qwer5678”; //Use the SDK API access key

given by Datami.
String myUserId = “abc@def.com”;
int sdIconId = R.drawable.ic_launcher;
Boolean sdkUserMessaging = true; //if “false” the application needs to
inform the user about the sponsorship in OnChange callback
SmiSdk.initSponsoredData(mySdkKey, this, myUserId, sdIconId,
sdkUserMessaging);

// Application specific initializations

.....
}
}
 Sample code for using getAppSDAuth API with 'exclusionDomainList'

import com.datami.smi.SmiResult;
import com.datami.smi.SdState;
import com.datami.smi.SmiSdk;
...
public class MyApplication extends Application implements
SdStateChangeListener {
...
protected void onCreate() {
super.onCreate();
// Call the Datami API at the beginning of onCreate, before other
initializations.
// IMPORTANT: If Datami API is not the first API called in the
application then any network
// connection made before Datami SDK initialization will be
non-sponsored and will be
// charged to the user.

String mySdkKey = “abcd1234qwer5678”; //Use the SDK API access key

given by Datami.
String myUserId = “abc@def.com”;
int sdIconId = R.drawable.ic_launcher;
Boolean sdkUserMessaging = true; //if “false” the application needs to
inform the user about the sponsorship in OnChange callback
List<String> exclusionDomains = new ArrayList<String>(2);
exclusionDomains.add("www.example.com");
exclusionDomains.add("www.google.com");
SmiSdk.initSponsoredData(mySdkKey, this, myUserId, sdIconId,
sdkUserMessaging, exclusionDomains);

// Application specific initializations

.....
}
}

1.3 Setup a listener for Sponsored Data state changes in your Application class

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 message to its users.
 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.4 Setup User Communication

There are two ways in which SDK shows user messaging for Sponsored Data. The Application can choose one, both or none of these options.

1.4.1 User Messaging using Notification

The SDK can show a notification in the notification drawer when the application is in foreground and sponsored data is available (SdState =
SD_AVAILABLE) for the application. The notification uses the 'iconId', passed to the 'initSponsoredData' API.

The 'iconId' is the hexadecimal number specifying the id of the icon (ex. R.drawable.ic_launcher). If the application passes the iconId as -1, the
SDK will not show any notification.

Possible iconId values are :

1. R.drawable.notificationDrawable
2. -1

1.4.2 User Messaging using Toast

The sdk driven toast messaging is available when application passes 'showMessaging' = true in the 'initSponsoredData' API. In such case, SDK
will show a toast message if the application is in foreground and sponsored data is available (SdState = SD_AVAILABLE) for the application.

A toast message a short description message shown as a popup message at the bottom of the screen to inform the user about the availability or
unavailability of the sponsorship. The toast uses dark background. The toast message will be shown on the bottom center of the screen, and the
SDK cannot customise the placement.

1.5 Sponsored Data Support for Playback Media

Besides initSponsoredData API, the application needs to use getSDAuth() for medial URL(s) that are played though native player.
 public class VideoPlayerActivity extends Activity {
private VideoView videoView;
private MediaController controller;
....
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
....
SmiResult sr = SmiSdk.getSDAuth(mySdkKey, this, origVideoUrl,
myUserId);
videoView.setVideoPath(sr.getUrl());
videoView.setMediaController(controller);
videoView.start();
...
}
...
}

1.5.1 Sponsored Data Support for Android Download Manager Content

Besides initSponsoredData API, the application needs to use getSDAuth() for the URL(s) requested through Android System Services (like And
roid Download Manager).

....
DownloadManager downloadmanager =
(DownloadManager)getSystemService(DOWNLOAD_SERVICE);
SmiResult sr = SmiSdk.getSDAuth(mySdkKey, myActivityCtx, myUrl,
myUserId);
Uri sdUri = Uri.Parse(sr.getUrl());
DownloadManager.Request request = new DownloadManager.Request(sdUri);
.....

1.6 Videos in WebViews

Besides initSponsoredData API, the application needs to use SmiWebView for covering videos in a WebView. The SmiWebView is a sub-class
of Android WebView, providing user messaging for the videos when there are not sponsored.

1.6.1 Using SmiWebView directly in your application

Follow the below sample code if your application uses the android WebView directly.
 //use SmiWebView as class variable
private SmiWebView myWebView;
....
myWebView = new SmiWebView(myActivity);
myWebView.setWebChromeClient(new MyChromeClient());
myWebView.setWebViewClient(new MyWebClient());
.....

1.6.2 Using a sub-class of SmiWebView in your application

Follow the below sample code if your application uses a sub-class of the android WebView.

//sub-class of SmiWebView
class MyWebView extends SmiWebView {
.....
public MyWebView(Context ctx) {
super(ctx);
...
setWebChromeClient(new MyChromeClient());
setWebViewClient(new MyWebClient());
...
}
}

1.6.3 Using SmiWebView in the XML

Follow the below sample code if your application inflates webview via XML
 <-- layout xml -->
<com.datami.webview.SmiWebView
android:id="@+id/sponsorWebView"
android:layout_width="match_parent"
android:layout_height="match_parent" >
</com.datami.webview.SmiWebView>

//in java Code

private SmiWebView webView;

@Override
protected void onCreate(Bundle savedInstanceState) {
...
webView = (SmiWebView) findViewById(R.id.sponsorWebView);
...
}

1.7 Client IP and Carrier Name APIs

Datami Android SDK provides the following additional details of current cellular data connection to parent apps:

Client IP
Cellular Carrier Name

The above two values can be obtained through SmiResult object, which is part of sdState change notifications.

Note: These values not available for WiFi connection. The Client IP is available only when SdState = SD_AVAILABLE.
 public class MyApplication extends Application implements
SdStateChangeListener{
...
@Override
public void onChange(SmiResult currentSmiResult) {
SdState sdState = currentSmiResult.getSdState();
Log.d(TAG, "sponsored data state : "+sdState);
String cleintIp = "";
String carrierName = "";
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

//getCleintIp of cellular data connection

cleintIp = currentSmiResult.getClientIp();

// getCarrierName of cellular data connection

carrierName = currentSmiResult.getCarrierName();

} 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());

// getCarrierName of cellular data connection

carrierName = currentSmiResult.getCarrierName();

} else if(sdState == SdState.SD_WiFI) {

// device is in wifi
}
}
...
}

2 Using the 'stopSponsoredData' API

Apps can use this API to stop sponsored data at any time during the application runtime. For example, this API will be useful if the app wants to
provide sponsored data for only logged in users. The App can call this API when user logs out.

2.1 Sample Code for using the 'stopSponsoredData' API

 Using 'stopSponsoredData' API

class MyLoginActivity extends Activity {

.....
provate void postLogout() {
Log.d(TAG, "user is logged out, stopping sponsored data");
SmiSdk.stopSponsoredData();
}
}

3 Using the 'startSponsoredData' API

Apps can use this API to start sponsored data at any time during the application runtime. For example, this API will be useful if the app wants to
provide sponsored data for only logged in users. The App can call this API when user logs in.

3.1 Sample Code for using the 'startSponsoredData' API

Using 'startSponsoredData' API

class MyLoginActivity extends Activity {

.....
provate void postLogin() {
Log.d(TAG, "user is logged in, starting sponsored data");
SmiSdk.startSponsoredData();
}
}

4 Using 'getSDAuth' API

4.1 Add required permissions and entries in AndroidManifest.xml for 'getSDAuth' API

<!-- SmiSdk Required Permissions -->

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

4.2 Call 'getSDAuth' API for intended URL

 import com.datami.smi.SmiResult;
import com.datami.smi.SdState;
import com.datami.smi.SmiSdk;
..

SmiResult sr = SmiSdk.getSDAuth(mySdkKey, myActivityCtx, myUrl,

myUserId);
SdState sdState = sr.getSdState();

// get sponsored data url

String sdUrl = sr.getUrl();

if(sdState == SdState.SD_AVAILABLE) {
// sdUrl is a sponsored data url
} else if(sdState == SdState.SD_NOT_AVAILABLE) {
// sdUrl is not sponsored, same as original url
} else if(sdState == SdState.WIFI) {
// device is in wifi, sdUrl is same as original url
}

5 Using 'getAnalytics' API

Apps can use this api to fetch the SDK collected analytics at anytime after the app is notified with an sdState.

5.1 Sample Code using the 'getAnalytics' API

Using 'getAnalytics' API

class MyAnalyticsActivity extends Activity {

.....
provate void showUsage() {
Analytics analytics = SmiSdk.getAnalytics();
long appUsageTimeInCellular = analytics.getCellularSessionTime();
long appUsageTimeInWifi = analytics.getWifiSessionTime();
long appSdDataUsage = analytics.getSdDataUsage();
String msg = "SD Usage: "+appSdDataUsage+", Cellular Time:
"+appUsageTimeInCellular+", Wifi Time: "+appUsageTimeInWifi;
Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
}
}

6 Using 'updateUserId' API

Apps can update the user id in the SDK for better analytics as per requirements.
Just pass the new user id as String to updateUserId API. SDK will always use the new user id and will replace the old user id if any.

Update User Id

...
String newUserId = "userid";
SmiSdk.updateUserId(newUserId);
...

7 Using 'updateUserTag' API

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

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

Update User Tags

....

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

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

SmiSdk.updateUserTag(tags);
....

Please Note:

1. Max 32 characters are supported for a tag

2. Max 6 Tags are supported

8 Using 'getClientIP' API

Apps can use this API to get network client IP.

Using getClientIp API

...

String clientIp = SmiSdk.getClientIP();

...
9 Hybrid app integration
In case when the developers use Cordova to develop hybrid application for Android, there needs to be special integration done at the native code
for i.e. Java for Android as explained below.

9.1 Integration Steps

1. Install Datami SmiSdk Cordova plugin.

a. If using cordova-android 6.3.0 or below cordova plugin add https://bitbucket.org/datami/cordova-smisdk-plugin.git
b. If using cordova-android 7.0.0 or above cordova plugin add https://bitbucket.org/datami/cordova-smisdk-plugin.git#cordo
va8
2. Specify apiKey in config.xml as <preference name="api_key" value="apiKey" />
3. Specify SdkNotificationMessage to be used as <preference name="sdk_notficiation_messaging" value="true" />
4. Specify sdkMessage to be used as <preference name="sdk_messaging" value="true" />

Cordova Config.xml Android

<allow-intent href="mailto:*" />

<allow-intent href="geo:*" />
<platform name="android">
<allow-intent href="market:*" />
<preference name="api_key" value="<your-api-key" />
<preference name="sdk_messaging" value="true" />
<preference name="sdk_notficiation_messaging" value="false"
/>
</platform>

5. If using Cordova version 6.X, update AndroidManifest.xml file with attribute name (android:name) in application node.

AndroidManifest.xml

<application
android:name="com.datami.DatamiApplication"
...
>

6. Build the android project with cordova build android.

9.2 Getting started with getSDAuth() API

When the app is using a plugin to play the video from the URL, the video will not be sponsored. To make it sponsored, the application needs to
use the getSDAuth() in the plugin code. As the plugin code is open source, we can find the location where the plugin actually passes the URL to
the media player. Here we are taking the example of StreamingMedia plugin for playing videos in hybrid app. Call the getSDAuth() api in correct
location. Here we need to change the file SimpleVideoStream.java and the function play()
 SimpleVideoStream

public class SimpleVideoStream extends Activity implements

MediaPlayer.OnCompletionListener, MediaPlayer.OnPreparedListener,
MediaPlayer.OnErrorListener, MediaPlayer.OnBufferingUpdateListener {
...
...

private void play() {

mProgressBar.setVisibility(View.VISIBLE);
Uri videoUri;
try{
SmiResult zr = SmiSdk.getSDAuth(<SDK_KEY>,this, mVideoUrl);
videoUri = Uri.parse(zr.getUrl());
Log.i("Datami","Returned URL " + zr.getUrl());
}catch(Exception e){
videoUri = Uri.parse(mVideoUrl);
}
...
...
}

9.3 Sponsoring Video Inside WebView

If the hybrid app is loading Embedded youtube and facebook videos inside the app, the app need to use the SmiWebView class to make the
videos sponsored or blocked depending on the configuration at the backend. As the Cordova Library loads the Custom WebView we need to
extend the SmiWebView in SystemWebView.java at the location {Project_name}/platforms/android/CordovaLib/src/org/apache/cordova/en
gine

SystemWebView.java

import com.datami.webview.*;

public class SystemWebView extends SmiWebView implements

CordovaWebViewEngine.EngineView {
private SystemWebViewClient viewClient;
SystemWebChromeClient chromeClient;
private SystemWebViewEngine parentEngine;

...
...
}
9.4 Listen to SD State Change in JS

You can use getSdState method to listen to SD State Change in your index.js . You can use this to show custom message to user.

SD State Change in JS

.....
onDeviceReady: function() {

this.receivedEvent('deviceready');
smiSdkPlugin.getSdState(function(sdState) {
// Custom Messaging Code Here
console.log('SD STATE CHANGE ' + sdState);

})
},
....

9.5 Analytics API in Cordova JS

Analytics can be accessed in JS using the following code.

Analytics in JS

smiSdkPlugin.getAnalytics(function(data){
console.log(data)
//To get Cellular session time
console.log(data.CellularSessionTime);
//To get Wifi Session time
console.log(data.WifiSessionTime);
//To get SD Data used
console.log(data.SdDataUsage);
})

9.6 getSDAuth API in Cordova JS

getSDAuth API is used to generate a sponsored url from a regular url.

getSDAuth in JS

smiSdkPlugin.getSDAuth(function(data){
console.log(data)
//For the url use -> data.Url
},"https://www.datami.com");
9.7 updateUserId API in Cordova JS

Apps can update the user id in the SDK for better analytics as per requirements.

Just pass the new user id as String to updateUserId API. SDK will always use the new user id and will replace the old user id if any

updateUserId in JS

var userid = "new user id";

smiSdkPlugin.updateUserId(function(data){
console.log(data)
},userid);

9.8 updateUserTag API in Cordova JS

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

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

updateUserTag in JS

var tags = ['tag1','tag2','tag3'];

smiSdkPlugin.updateUserTag(function(data){
console.log(data)
},tags);

10 Testing and Verification

10.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 notifies the application with sdState = SdState.WIFI through
SdStateChangeListener’s onChange() callback.
2. Open the application in cellular mode and verify that the SDK notifies the application with sdState = SdState.SD_NOT_AVAILABLE and
sdReason = SdReason. SD_NOT_AVAILABLE_PROMOTION_NOT_FOUND through SdStateChangeListener’s onChange() callback.
The sdReason can vary, depending on current stage of the application provisioning in Datami backend. For example, if the application is
not whitelisted, the sdReason would be different.
3. Switch between WiFi and cellular, and verify that the SDK notifies the sdState accordingly.

10.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 notifies the application with sdState = SdState.SD_AVAILABLE through
SdStateChangeListener’s onChange() callback.
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 doen’t increase for the campaign.

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

11.1 Logging Overhead

Datami SDK uses very minimal logging in its release version. The logging rate is less than 1 KB per hr.

11.2 Initialization Overhead

1. initSponsoredData API is asynchronous and it doesn’t block the calling application.

2. getSDAuth API is synchronous as it needs to return a sponsored url. However there is no network call involved in this api when used
after initSponsoredData API.

11.3 Runtime Overhead

The Datami SDK routes the traffic through Datami Gateway which adds a minor latency to the data flow of no more than 100ms. 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 minimise network latencies. The application developer can request for testing the correct integration from Datami.

12 Error Codes returned by SDK

Error Code Name Error Code Description

Value

SD_NOT_AVAILABLE_PROMOTION_LIMIT_EXCEEDED 7 When data usage exceeds the total campaign

limit

SD_NOT_AVAILABLE_USER_LIMIT_EXCEEDED 8 When the per user data limit is exceeded

SD_NOT_AVAILABLE_PROMOTION_NOT_FOUND 9 When no campaign exists or campaign expired

SD_NOT_AVAILABLE_SD_REGISTRATION_NOT_DONE 10 When initial launch with no internet connection

SD_NOT_AVAILABLE_SDK_VERSION_NOT_SUPPORTED 11 When the SDK version is not supported by

server

SD_NOT_AVAILABLE_SD_NOT_SUPPORTED_FOR_APP_OR_CARRIER 12 When Sponsored Data is not supported for that

operator

SD_NOT_AVAILABLE_URAM_NO_HEADER_INJECTED 13 When header injection fails in case of Uram

SD_NOT_AVAILABLE_SD_NOT_SUPPORTED_IN_ROAMING 14 When sponsored data in roaming is disabled and

device is in roaming

SD_NOT_AVAILABLE_SD_STOP_API_CALL 16 When stopSponsoredData Api is called

SD_NOT_AVAILABLE_ANDROID_VERSION_NOT_SUPPORTED 17 When running on non supported Android Version

SD_NOT_AVAILABLE_GW_CONNECTION_FAILURE 19 When unable to connect to Gateway

SD_NOT_AVAILABLE_NO_DATA_CONNECTION 20 When Data & Wifi are turned off

SD_NOT_AVAILABLE_CONNECTION_TIMEOUT 21 When the connection to server times out

SD_NOT_AVAILABLE_DNS_ERROR 22 When the DNS resolution fails

SD_NOT_AVAILABLE_REASON_UNKNOWN 100 Other than above mentioned issues

13 Best Practices
In order to achieve the best results from Datami SDK assuring best experience for the user :

1. The App developer should call the Datami SDK before making any network connections.
2. The app developer should let the SDK handle messaging the user about the sponsorship availability.
14 FAQ
When do I need to use initSponsoredData API?

You should use initSponsoredData API when you want entire application traffic (http/https) needs to be sponsored

Where should I call the initSponsoredData API in my application code?

The initSponsoredData API should be called before making any network call from the application. The best place for this API call is at the
beginning of application’s onCreate() method, see code sample in section 1.2

When do I need to use getSDAuth API?

You should use getSDAuth API for sponsoring individual content like specific url. You also need to use this API along with initSponsoredData for
sponsoring videos that played through native media player or a url that is handled by Android Download Manager service.

Where should I call the getSDAuth API?

First of all, the getSDAuth API is only used for sponsoring specific content, unless it is a media url played through native media player or a url that
is handled by Android Download Manager. This API should be called just before using the specific url in your application code.

How do I check whether SDK integration correct?

If your application is receiving onChange() callbacks then you can assume that the integration correct.

How does the SDK sponsor the application traffic?

The Datami SDK routes the traffic through Datami getway, if the subscriber and application are authorized for sponsored data. The data going
through Datami gateway is not charged to subscriber’s data plan as Datami gateways are whitelisted by cellular provider.

Should I use SDK user messaging or my own messaging?

Notifying the user about sponsored data is critical. The SDK provides basic user messaging through a Toast message as it doesn’t include any
UI. The application needs to implement an UI based user messaging for better visibility and user experience.

My application is global, but Datami is not enabled for all locations or cellular providers. Do I need to check the location and/or wireless
operator before calling Datami API?

The Datami SDK API calls are no-op where Datami service is not enabled. The SDK checks with Datami backend and goes dormant for a period
if the service not enabled for the given location or cellular provider. The dormant period is configurable from Datami backend and its default value
is 48 hrs.

I have already implemented the API but do not see any user messaging?

Check if there is a campaign running with Datami for the country where you are trying to run the tests. If not please send a query to ts@datami.co
m

My app has videos inside the app, how do I make them sponsored?

In order to make any video Sponsored, please use URL API provided in the section 4.

I have used URL api for my videos, but my videos are still not sponsored, what am I missing?

This can happen if the application is using a third party library to play videos, please send the name of the library with your query to ts@datami.co
m

My application uses WebView to show content, how do I make sure the videos in the html are not getting sponsored?

Datami SDK provides a provision of blocking the videos on Webview, you can follow the section 1.6.

Can the SDK cause an application crash?

We have taken utmost care to ensure that the SDK will not cause an application crash. We have verified it by running the SDK on all possible
devices and versions of the operating systems. After integration with our SDK, please test your application thoroughly by testing it on all versions
of devices and operating systems before you release it to the Playstore. You can use third-party services like Keynote, AWS, etc.
I use Hybrid application to develop iOS and Android app, how do I integrate the SDK?

If you are using Cordova as the platform to develop Hybrid Application you can follow section 6 to integrate the SDK.

In my Hybrid application I do not use StreamingMedia plugin to show video, where do I integrate the URL api in the code?

In most of the video plugins, they use simple setVideoURI() function to show video on the device. If you can find the location of that, you can
integrate the API at that location. If not, then you can mail the name of the plugin to ts@datami.com and we will get back to you with the solution.

I am Hybrid application developer, and not aware of the Java code for the Android, how do I integrate with the SDK?

We have made the SDK integration document easy to understand and integrate. But if you face any issues, you can mail your query at ts@datami
.com and we will get back to you.

P.S. we will soon be coming up with Cordova plugin to make the integration easier.

Appendix:

API Reference

I. API for sponsoring entire application

Datami Android SDK includes an API to facilitate sponsored data solution for entire application. This api needs be only called once during
application startup. The API method signature is as follows:

Note: getAppSDAuth API is deprecated, please use initSponsoredData API instead.

void initSponsoredData(String sdkKey, final Context appCtx, String userId, int iconId, boolean showMessaging, List<String> exclusion
DomainList);

initSponsoredData API parameter details:

Name Type Description [M]andator

y/[O]ptional

sdkKey String The API Access Key provided by Datami M

appCtx Context The application context M

userId String The userId of the application. When provided, it can be used for analytics and/or authorization purposes. O
The userId can be email, username, phone number etc. Datami uses an internal id when userId is not
provided

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

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

showMessaging boolean When it is 'true', sdk shows a toast message when SdState is SD_AVAILABLE O

exclusionDomainList List<String> List of exclusion domains (ex. www.example.com, www.google.com, etc.) that need to be excluded for O
sponsored data.

Note: Sub-domains are not excluded by default. Any sub-domain that needs to be excluded should be
included in the parameter 'exclusionDomainList'.

II. API for Stopping sponsored data

This API is used for stopping sponsored data for the application. When the sponsored data is stopped, the SDK will notify the sdState change to
application through onChange callback.

The method signature is as follows:

void stopSponsoredData();
III. API for re-Starting sponsored data

This API is used for restarting sponsored data after it is stopped. Calling this API without calling initSponsoredData API will result in an
exception. When the sponsored data is re-started, the SDK will notify the sdState change to application through onChange callback.

The method signature is as follows:

void startSponsoredData() throws Exception;

IV. API for sponsoring Single Content URL

This API is used for sponsoring individual url content on cellular networks. The API signature is as follows:

void getSDAuth(String sdkKey, final Context activityCtx, String url, String userId);

getSDAuth API parameter details:

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

sdkKey String The API Access Key provided by Datami M

activityCtx Context The Activity context from which the api call is made M

url String The specific url that needs to be sponsored M

userId String The userId of the application. When provided, it can be used for analytics and/or authorization purposes O

V. SDK Analytics API

The Datami SDK collects the following metrics:

Metric Description

cellularSessionTime Total application time (in seconds) in cellular mode (regardless of application is sponsored or not).

wifiSessionTime Total application time (in seconds) in wifi mode.

sdDataUsage Total sponsored data (in bytes) used by the application. This doesn't include the data usage in wifi.

This API is provided for application to fetch the above metrics on demand basis. The API signature is as follows:

Analytics getAnalytics();

VI. Update UserId API

This API is used to update the user id in the SDK. The API signature is as follows:

void updateUserId(String userid);

updateUserId API parameter details:

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

userid String The new userid you want to use M

VII. 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

VIII. Get Client IP API

This API is used to get network client Ip from SDK.

String getClientIP();