• Author / Uploaded
• GiulianoMoretti

Citation preview

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



Remove SmiIntentService from Androidmanifest.xml

Removed SmiIntentService

//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+



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



cloudmi.datami.com

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





cloudmi.datami.com



iii. Add the network security config to AndroidManifest.xml

AndroidManifest with network security config



...

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



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 = “[email protected]”; 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 = “[email protected]”; 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 exclusionDomains = new ArrayList(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



//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



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 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 3. Specify SdkNotificationMessage to be used as 4. Specify sdkMessage to be used as

Cordova Config.xml Android







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

AndroidManifest.xml

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(,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 Value

Description

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 [email protected] 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 [email protected] 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 [email protected] 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 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. The userId can be email, username, phone number etc. Datami uses an internal id when userId is not provided

O

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

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

O

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 tags); updateUserTag API parameter details: Name

Type

Description

[M]andatory/[O]ptional

tags

List

List of tags

M

VIII. Get Client IP API This API is used to get network client Ip from SDK. String getClientIP();