Lifecycle Tracking Module for Android

Lifecycle Tracking Module for Android

by Community Manager ‎01-04-2017 03:23 PM - edited ‎01-04-2017 03:55 PM (480 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 must be added manually. 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:
  3. dependencies {
        compile(name:'tealium.lifecycle-5.0.4', ext:'aar')
    }

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:

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