Overview

Skill Level: Intermediate

You must integrate and implement the Digital Analytics SDK for Android before you can use Digital Analytics to generate reports on the activity of visitors to your Android application.

Prerequisites

To get started, see Digital Analytics SDK for Android overview  for the following information:

  • SDK improvements to the SDK.
  • Supported versions for iOS, Android, Apple Xcode, and Swift.

Before you begin, download the SDK by using the SDK Manager. Depending on your OS, following these tutorials before integrating the Digital Analytics SDK:

Step-by-step

  1. Integrate the SDK into your Android application.

    These are the files that you will need to integrate the Digital Analytics Software Development Kit (SDK). They are part of the release package that is provided with the SDK. Copy these files from the release package and place them in the specified folders in the Android project inside Eclipse.

     File  Folder location
    DigitalAnalyticsBasicConfig.properties  assets 
    DigitalAnalyticsAdvancedConfig.json  assets 
    EOCoreBasicConfig.properties assets 
    EOCoreAdvancedConfig.json  assets 
    digitalanalyticsmod.jar  libs
    eocore.jar libs

     

  2. Customize SDK behavior.

    You can use the DigitalAnalyticsBasicConfig.properties file to customize the SDK behavior. It is unlikely that you will need to modify the other files in this list. 

    Name Value
    PostMessageUrl

    URL of the Host where tag data must be sent. By default, it is set to the test data warehouse at: https://testdata.coremetrics.com/cm

    To send data to the production server, change this value to https://data.coremetrics.com/cm

    ClientId¬† ClientId uniquely identifies the client sending the tag data. In case of multiple clients the client IDs, the ID values must be concatenated and separated by a delimiter. Use the ‚Äė;‚Äô character between 8-digit ID values and the ‘|’ character between Multisite Global Id and SiteId values.
    Example sending data to a single 9-series ID: 99999991
    Example sending data to multiple 9-series IDs:
    “99999991;99999992;99999993”
    Example sending data to a single Multisite ClientId with accompanying SiteId value:
    59999999|SiteId
    Example sending data to multiple Multisite ClientIds with accompanying SiteId values:
    59999991|SiteId;59999992|SiteId;59999993|SiteId
    AppName  Name of the Application 
    DisplayLogging  Specify true to activate logging by the SDK. Specify false to deactivate it. 
     CaptureAllOfflineTags Specify true to capture all tags when the App is offline. Specify false to restrict this capturing to only 10 tags. True is the default. 

     

  3. Register the application component.

    Setup hooks to handle SDK lifecycles in the application class.

    1. If no application class was defined and you only instrument with the DA SDK, a com.digitalanalytics.api.DigitalAnalyticsApplication
      component is supplied as part of the Digital Analytics Android SDK.

      Specify the following in the application xml element:

      android:name=”com.digitalanalytics.api.DigitalAnalyticsApplication” on the ‚Äúapplication‚ÄĚ xml element.

    2. If an existing application class was defined or you plan to instrument with both the DA and Tealeaf SDKs,
      merge these API calls in the application class:

      // Example DA application class

      public class DigitalAnalyticsApplication extends Application {
         @Override
         public final void onCreate() {
             // Startup the Tealeaf module, uncomment below if using Tealeaf SDK
             // Tealeaf tealeaf = new Tealeaf(this);
             // Tealeaf.enable();
             // Startup the Digital Analytics Module
             DigitalAnalytics.startup(this);
             super.onCreate();
         }
         @Override
         public final void onTerminate() {
             // Shutdown the Digital Analytics Module
             DigitalAnalytics.shutdown();
             // Uncomment below if using Tealeaf SDK
             // Tealeaf.disable();
             super.onTerminate();
         }
         @Override
         public void onLowMemory()
         {
             // Uncomment below if using Tealeaf SDK
             // Tealeaf.onLowMemory();
             super.onLowMemory();
         }
      }
    3. Add the following permissions:

      <uses-permission android:name=”android.permission.INTERNET” />

      <uses-permission android:name=”android.permission.ACCESS_NETWORK_STATE” />

      <uses-permission android:name=”android.permission.ACCESS_WIFI_STATE”/>

  4. Manage sessions for Android applications.

    Use the following methods to manage sessions for Android applications.

     

    startNewSession method for Android

    This method call ensures that additional methods are associated with the same session.

    In the Digital Analytics system, there is a concept of a session that is associated with a set of tags that are fired during the life time of that Session. It is up to the Application to decide how to demarcate the sessions, but the Digital Analytics SDK API provides a clear way to differentiate one Session from another. Typically, at the start of a new session, before starting any fire API method calls, the developer starts the following method:

    DigitalAnalytics.startNewSession(this.activity)

    When it is time in your application to start another Session with a new set of Tags, start the

    DigitalAnalytics.startNewSession(this.activity)

    method again.

     

    visitorID method for Android

    Use this method to get the visitor ID associated with the user of the application. The visitor ID remains the same across multiple invocations of this method.

    [ DigitalAnalytics visitorID ];

     

    session ID method for Android

    Use this method to get the session ID associated with the currently active tag session. The session ID will change across the creation of new tag sessions.

    DigitalAnalytics.sessionID()
  5. Customize tag post default behavior for Android.

    By default, tags are put in a queue and processed every 30 seconds. When a tag is fired, the SDK engine collects the tag data and places it in a queue to be submitted to the server. By default, this queue service runs every 30 seconds. If the queue server finds tag data, it submits it in the background. This behavior makes more efficient use of system resources by not activating a network process for each tag. This is the default behavior.

    Modify tag post default behavior by using the EOCoreBasicConfig.properties file in the assets folder.

    1. Locate the EOCoreBasicConfig.properties file in the assets directory.
    2. Modify one of the following parameters:
       Parameter Description
      ManualPostEnabled 

       
      false – tag data is placed in a queue to be processed based on the PostMessageTimeInterval value. This is the default value.

      true Рtags are posted immediately, but more system resources are used. Use this setting only if your application requires tags to run immediately.   

      PostMessageTimeInterval  The number of seconds the tag queue service waits to submit tags. The default is 30 seconds. This property is activated when ManualPostEnabled=false.
  6. Configure the Digital Analytics client ID.

    The dynamic client ID feature allows you to change the Digital Analytics client ID to a different value depending upon the context in which the application is executing.

    For example, if your application is linked to two different businesses, those businesses will need to collect data separately using two separate client IDs. Use this feature to ensure that user activity associated with each business is sent to the correct client ID.

    You configure the default client ID in the DigitalAnalyticsBasicConfig.properties file. For information, refer to Step 2 of this tutorial.

     

    Override the default client ID

    You can override the default client ID that is defined in the DigitalAnalyticsBasicConfig.properties file by invoking the following method:

    DigitalAnalytics.activateClientId(String newClientId)

     

    where newClientId is a new client ID. After this method is invoked, all tags that are executed are associated with the StringnewClienId value rather than the default value.

     

    Return to the default client ID

    If you override the default client ID, you can return to the default client ID that is defined in the DigitalAnalyticsBasicConfig.properties file by invoking the following method:

    DigitalAnalytics.resetToDefaultClientId()

     

    After this method is invoked, all tags that are executed are associated with the default value that is defined in the DigitalAnalyticsBasicConfig.properties file.

Expected outcome

The Digital Analytics SDK for Android is integrated and implemented.

2 comments on"Getting started with the Digital Analytics SDK for Android"

  1. My name is Malli and work for Delta.I am currently integrating TLeaf with Xamarin framework.Do you have any SDK for Xamarin.

  2. Hemant Dixit February 01, 2019

    Hi Mali, it seems SDK for Xamarin is available, please check the link
    https://github.com/ibm-watson-cxa

Join The Discussion

Your email address will not be published. Required fields are marked *