Lifecycle Tracking Module for Android

Lifecycle Tracking Module for Android

by Community Manager on ‎01-04-2017 03:23 PM - edited on ‎08-07-2017 02:48 PM by (752 Views)
The Tealium Lifecycle Module provides app lifecycle tracking capability to an existing 5.x implementation of the Tealium Androiod framework.
 
This guide covers the following topics:
 
Table of Contents Placeholder

Installing

The Lifecycle Module dependency can be added manually, or via Tealium's Maven repository.

 

Manual Install 

The module can be downloaded here: Tealium Android Lifecycle Tracking Module.

Follow these steps add the module to your app:

  1. Add tealium.lifecycle-5.0.x.aar to <PROJECT_ROOT>/<MODULE>/libs.
  2. Add the Tealium library dependency to your build.gradle file:

    dependencies {
        compile(name:'tealium.lifecycle-5.0.4', ext:'aar')
    }

 

Maven Install 

  1. Ensure you have the Tealium Maven repo added in your project's build.gradle file

    // Top-level build file where you can add configuration options common to all sub-projects/modules.
    buildscript {
    repositories {
    jcenter()
    }
    dependencies {
    classpath 'com.android.tools.build:gradle:2.3.3'
    }
    }

    allprojects {
    repositories {
    jcenter()
    // Tealium Maven repo directive
    maven {
    url "http://maven.tealiumiq.com/android/releases/"
    }
    }
    }
  2. In your app-level build.gradle file, add the Tealium lifecycle module. The current version is 1.1:

    dependencies {
    // only add if not already present
    compile 'com.tealium:library:5.3.1'
    // add lifecycle to list of dependencies
    compile 'com.tealium:lifecycle:1.1'
    }

Tracking

The module tracks the following lifecycle events:

  • launch
  • sleep
  • wake

These events are indicated in the lifecycle_type variable.

Automatic Tracking

Tealium Lifecycle tracking solely associates usage with the Activity lifecycle.

The library leverages the Application.ActivityLifecycleCallbacks API and evaluates its conditions on onActivityResumed and onActivityPaused.

To enable, call:

Tealium.Config config = Tealium.Config.create(application, "YOUR_ACCOUNT", "YOUR_PROFILE", "ENVIRONMENT");
boolean isAutoTracking = true;

// Additional instance for Lifecycle tracking
LifeCycle.setupInstance("INSTANCE_NAME", config, isAutoTracking);

// Standard Tealium instance Tealium.createInstance("INSTANCE_NAME", config);

 

Launch Event

Generated on the first onActivityResumed to occur. If onActivityPaused is called before onActivityResumed (when the library is initialized in the middle of the Activity lifecycle), then the module creation time is used to generate a launchevent.

Sleep Event

Generated 5 seconds after onActivityPaused is called and onActivityResumed was not called. This indicates that the application has been backgrounded because a new view has not been presented.

Wake Event

Generated during onActivityResumed when more than 5 seconds has elapsed since the last onActivityPaused. This indicates that onActivityResumed is called because the app is foregrounding and not because of a view change.

Manual Tracking

Available for specific lifecycle paradigms and unconventional lifecycle tracking. This approach is not recommended for most implementations. To allow manual lifecycle tracking update your lifecycle initiation code to set isAutoTracking to false.

Tealium and the attached LifeCycle multitons are remote-killable by pubish settings in Tealium iQ. Null checks should be performed when getting the instances to call their methods. 

Launch Event

To manually track a launch event, call trackLaunchEvent:

LifeCycle lifeCycle = LifeCycle.getInstance(TEALIUM_INSTANCE_ID);

if(lifeCycle != null) {

    // OPTIONAL
    Map<string, string=""> data = new HashMap<>();
    data.put("boot_time", "5ms");

    lifeCycle.trackLaunchEvent(data);
}

Sleep Event

To manually track a sleep event, call trackSleepEvent:

LifeCycle lifeCycle = LifeCycle.getInstance(TEALIUM_INSTANCE_ID);

if(lifeCycle != null) {

    // OPTIONAL
    Map<string, string=""> data = new HashMap<>();
    data.put("foreground_time", "4000ms");

    lifeCycle.trackSleepEvent(data);
}

Wake Event

To manually track a wake event, call trackWakeEvent:

LifeCycle lifeCycle = LifeCycle.getInstance(TEALIUM_INSTANCE_ID);

if(lifeCycle != null) {

    // OPTIONAL
    Map<string, string=""> data = new HashMap<>();
    data.put("background_time", "600000ms");

    lifeCycle.trackWakeEvent(data);
}

Crash Detection

When a launch event follows a wake event or vice-versa, this indicates a crash has occurred since the app did not successfully sleep. If the aforementioned sequence occurs because of a Tealium library shutdown, this is not considered to be a crash event.

When a crash event is detected, the launch or wake event data will have the lifecycle_diddetectcrash variable will be added.

{
    "lifecycle_type" : "launch",
    "lifecycle_diddetectcrash" : "true",
    //...
}

Data Layer Variables

The module adds the following additional variables for the listed event types (launch, wake, sleep):

Variable Description Type Example Event
lifecycle_dayofweek_local Local day of week that call was made - 1=Sunday, 2=Monday, etc.) Number "13" all
lifecycle_dayssincelaunch Days since first launch in integer increments Number "23" all
lifecycle_dayssinceupdate Days since the last detected app version update in integer increments Number "46" all
lifecycle_dayssincelastwake Days since last detected wake in integer increments Number "1" all
lifecycle_diddetectcrash Only present if a launch event follows a wake event (crash inferred from missing prior sleep event) Boolean "true" launch
lifecycle_firstlaunchdate GMT timestamp of very first detected launch/wake in ISO8601 format from Zulu time String "2013-07-11T17:55:04Z"  all 
lifecycle_firstlaunchdate_MMDDYYYY  GMT Timestamp formatted as MM/DD/YYYY  String "01/18/2012"  all
lifecycle_hourofday_local Local hour of day that call was made (24 hour format)  String "true"  all
lifecycle_isfirstlaunch Only present if call is very first launch call String "true" launch
lifecycle_isfirstlaunchupdate  Only present if call is first launch after a detected updated Boolean "true" launch
lifecycle_isfirstwakemonth Only present if call is first launch/wake of the month Boolean "true" launch, wake 
lifecycle_isfirstwaketoday Only present if call is first launch/wake of the day  Boolean  "true" launch, wake
lifecycle_launchcount Total number of launches this version of your app (since the last updtae) Number "3"  all
lifecycle_secondsawake Whole seconds app was awake since last wake/launch. Sent only with lifecycle_type:sleep or lifecycle_type:terminate calls Number "30" all 
lifecycle_priorsecondsawake  Whole seconds app was awake since last launch only. Aggregates total from all wakes prior. Sent only with lifecycle_type: launch calls.  Number  "126"  all
lifecycle_sleepcount Total number of times your app has gone to sleep (resets if updated)  Number  "5"   all
lifecycle_totalcrashcount Total number of crashes counted since install (only reset if app deleted)  Number  "21"   all
lifecycle_totallaunchcount Total number of launches since install (only reset if app deleted)  Number  "3"   all
lifecycle_totalsecondsawake  Total number of seconds your app has been in a woken/active state since app install (only reset if app deleted)  Number  "36"  all
lifecycle_totalsleepcount  Total number of times your app has gone into the background since app install (only reset if app deleted)   Number  "400"  all
lifecycle_totalwakecount  Total number of launches + wakes since install (only reset if app deleted)  Number   "563"  all
lifecycle_type   Type of lifecycle call String "initial", "launch", "wake", "sleep", "terminate"  all
lifecycle_updatelaunchdate  GMT timestamp of first wake/launch after a version update has been detected  String  "2014-09-08T18:10:01Z"  all
lifecycle_wakecount  Total number of launches + wakes in this version of your app (resets if updated)  Number   "29"  all