Android SDK Integration guide

Document created by Akhil Jayaprakash Employee on Jan 27, 2016Last modified by Akhil Jayaprakash Employee on Mar 9, 2016
Version 4Show Document
  • View in full screen mode

Summary

This document details the process of integrating VOC SDK with your Android application to accelerate web traffic.

Introduction

The SDK internally takes care of pre-positioning the content based on user preferences and policies set up between client and server. SDK provides APIs (networking libraries) to be used by developers that takes care of acceleration and stats collection.

 

The SDK provides API for developers to access real time network conditions such as congestion state. This information can be used to augment user experience by taking necessary action based on network state.

 

In addition, SDK also provides APIs for logging user events which could be used to associate traffic originated from the app with events such as the click of a button.

Getting Started

 

Step 1: click here to download the SDK

 

Step 2: proceed with the document

 

There are primarily two ways of accessing content over the network. One of the most common ways is to use standard HTTP libraries such as HttpURLConnection. The SDK provides the AkaURLConnection library which sub-classes java.net.URLConnection class. This library can be used in a similar fashion as HttpURLConnection to access HTTP/HTTPS content over the network.

 

Another way to access content over the network is to use WebViews. The SDK provides an API for developers which delegates all network-related requests originating from WebViews via the AkaURLConnection library.

 

The AkaURLConnection library also collects network-related statistics (such as HTTP time to first byte, request size, response size, duration etc.) alongside serving content. These stats are sent periodically to a server and can be later accessed via the portal.

Requirements and Dependencies

The SDK supports API 15 and above.

Installing the Android SDK

Download the Voc SDK  and unzip it.

 

In a file explorer (not Android Studio), drag the unzipped voc-sdk-version.aar file into the /app/libs directory in your project’s root directory.

 

In Android Studio, edit the build.gradle file in the app directory (not the one in the root folder ) and edit the dependencies sub-section to include .AAR file and following libraries:

 

dependencies {

  compile fileTree(dir: 'libs', include: ['*.jar'])

       compile 'com.google.android.gms:play-services:4.3.23'

       compile 'com.loopj.android:android-async-http:1.4.4'

       compile 'com.google.code.gson:gson:2.2.4'

  compile (name:'voc-sdk-version', ext:'aar')

       ...

}



 

Updating your Android Manifest

Client AndroidManifest.xml will need to be updated in order to complete the SDK integration.

 

<provider

android:name="com.akamai.android.sdk.db.AnaContentProvider"

android:authorities="<your_package_name>.AnaContentProvider" >

</provider>

 

 

Integration with your Android Application

Initialization

The first step after app start would be to create an Instance of VocService using VocService.createInstance(Context applicationContext), then setup the configuration using VocConfigBuilder. This can be done on the main application's onCreate (class that extends Application) or onCreate of the main activity.

 

Registration

The next step is to register with the VOC server using VocService.register API. The Register call is non-blocking, so the client will need to pass a handler for a registration status result.  Registration is a one-time event; the client can check the registration status using VocService.getRegistrationStatus to see if it is already registered.

 

Registration requires a valid license key and an optional unique identifier string. This identifier (if passed) can be used later to push content only to the device identified by this ‘uniqueUserIdentifier’.

 

Important: It is strongly recommended that user PII (Personally Identifiable Information) NOT be used in uniqueUserIdentifier directly.



In client App InitActivity

 

protected void onCreate(Bundle savedInstanceState) {

    // Initialize VocService

    VocService vocService = VocService.createVocService(getApplicationContext());

               

         VocRegistrationStatus status = vocService.getRegistrationStatus();

        if(!status.isActive()){         

                // Register with VOC server

                VocRegistrationInfo regInfo = new VocRegistrationInfo(licenseKey,  uniqueUserIdentifier);

      mVocService.register(regInfo , new VocAysncResponseHandler(){

                public void onSuccess(){

                     // Do something if needed

                }

                        

          public void onFailure(String message){

      // Do something if needed

         });

    }

}

 

 

 

API Reference

In this section, we see examples of how to use APIs provided by the SDK.  Developers need to replace all instances of HttpURLConnection with AkaURLConnection.

AkaURLConnection

AkaURLConnection provides similar APIs to those provided by HttpURLConnection. It takes care of delivering fresh content either from the cache or from the network. It also takes care of collecting relevant network statistics related to each request made through AkaURLConnection.

In order to replace HttpURLConnection with AkaURLConnection, we first need to change URL instantiation as follows.

 

final String uri = "http://www.bestbuy.com/";

 

//Before

URL url = new URL(uri);

 

//After

URL url = new URL(null, uri, new AkaURLStreamHandler());

// AkaURLStreamHandler instantiates an object of AkaURLConnection.

 

Next, replace all instances of HttpURLConnection with AkaURLConnection as shown below.

 

// AkaURLConnection usage.

 

final String uri = "http://www.bestbuy.com/";

 

AkaURLConnection urlConnection = null;

try {

       // AkaURLStreamHandler that instantiates an object of AkaURLConnection.

       URL url = new URL(null, uri, new AkaURLStreamHandler());

       urlConnection = (AkaURLConnection) url.openConnection();

       ...   

       // Download content using the InputStream

       InputStream inputStream = new BufferedInputStream(urlConnection.getInputStream());

       ...

       // Close the stream once done with the download.

       inputStream.close();

       } catch (IOException e) {

                e.printStackTrace();

       } finally {

// Make sure to call AkaURLConnection#disconnect() to release resources and collect stats.

                if (urlConnection != null) {

                         urlConnection.disconnect();

                }

       }



Here is a side-by-side comparison of API usage for HttpURLConnection and AkaURLConnection which shows before and after changes.



Before

After

final String uri = "http://www.bestbuy.com/";

 

HttpURLConnection urlConnection = null;

try {

URL url = new URL(uri);

 

urlConnection = (HttpURLConnection) url.openConnection();

       ...   

InputStream inputStream = new BufferedInputStream(urlConnection.getInputStream());

       ... 

inputStream.close();

} catch (IOException e) {                                              e.printStackTrace();

} finally {

if (urlConnection != null) {                        urlConnection.disconnect();

}

}

final String uri = "http://www.bestbuy.com/";

 

AkaURLConnection urlConnection = null;

try {

URL url = new URL(null, uri, new AkaURLStreamHandler());


urlConnection = (AkaURLConnection) url.openConnection();

       ...   

InputStream inputStream = new BufferedInputStream(urlConnection.getInputStream());

       ... 

inputStream.close();

} catch (IOException e) {                                              e.printStackTrace();

} finally {

if (urlConnection != null) {                        urlConnection.disconnect();

}

}



WebViews

In order to accelerate traffic originated from WebViews, the SDK provides following custom WebViewClient.

AkaWebViewL21Client - For Android API level 21 and above.

AkaWebViewL15Client - For Android API level 15 and above.

Both WebViewClients delegate all network calls via the AkaURLConnection library internally. The only difference between the two is that the L21 WebViewClient uses newer APIs added in level 21 and above.

The caller can use the appropriate client depending on API level as follows:

 

WebView webView;

...

if (Build.VERSION.SDK_INT >= 21) {

       webView.setWebViewClient(new AkaWebViewL21Client());

} else {

       webView.setWebViewClient(new AkaWebViewL15Client());

}

Custom Event Tracking

Custom events are actions triggered due to some activity performed by the end user, such as a button click. The SDK provides APIs that are helpful for developers to clock one or more custom events.

 

We classify events as timed and instantaneous events. Timed events are ones that have a start and an end point associated with them. Apart from clocking the duration between start and stop, such events can be used to determine network calls originated between start and stop.



/**

* API method to track timed events. Caller must call {@link #stopEvent(String)} to mark an event as complete.

* @param eventName Name of the event to track. Same name should be used for {@link #stopEvent(String)}

*/

public void startEvent(String eventName);

 

/**

* API method to track timed events. Caller must call {@link #startEvent(String)} before calling this method.

* @param eventName Name of the event used during {@link #startEvent(String)}

*/

public void stopEvent(String eventName);

 

 

Instantaneous events, unlike timed events, do not have a start and stop associated with them. Such events can be used to log a set of sequence or form a timeline of operations.

 

/**

* API method to track instantaneous events.

* @param eventName Name of the event to track.

*/

public void logEvent(String eventName);

 

 

Examples

Sample usage of above user events API.

 

VocService vocService;

...

vocService.logEvent("Initialization");

...

vocService.logEvent("Clicked XYZ.com");

String url = "http://www.xyz.com/abc.html";

WebView webView;

...

webView.setWebViewClient(new AkaWebViewL21Client() {

       @Override

       public void onPageStarted(WebView view, String url, Bitmap favicon) {

    super.onPageStarted(view, url, favicon);

         // url loading started.

    vocService.startEvent(url);

       }

 

       @Override

       public void onPageFinished(WebView view, String url) {

    super.onPageFinished(view, url);

         // url loading finished.

    vocService.stopEvent(url);

       }

});

Network Aware Experience

The SDK provides APIs that helps a developer to access client side network congestion data to augment client request.

 

For example - Load the absolute minimum needed for a particular user event.

 

VocService vocService;

...

int congestionStatus = vocService.getCongestionStatus();

 

switch(congestionStatus) {

       case VocCongestionStatus.CONGESTION_HIGH:

                // Exit download.

                break;

       case VocCongestionStatus.CONGESTION_MEDIUM:

                // Throttle download.

                break;

       case VocCongestionStatus.NO_CONGESTION:

                // Download content.

                break;

}



1 person found this helpful

Attachments

    Outcomes