Lifecycle Tracking Module

Provides app lifecycle tracking events.

Install

Install the Lifecycle Tracking module with Maven or manually.

Maven

To install the Lifecycle Tracking module using Maven:

  1. In your project’s top-level build.gradle file, add the following Maven repository:

    // Top-level build file where you add configuration options common to all sub-projects/modules.
    allprojects {
        repositories {
          jcenter()
          // Tealium Maven repo directive
          maven {
              url "https://maven.tealiumiq.com/android/releases/"
          }
        }
    }
    
  2. In your project module’s build.gradle file, add the following Maven dependency:

    dependencies {
        // only add if not already present
        implementation 'com.tealium:kotlin-core:1.5.0'
        // add lifecycle to list of dependencies
        implementation 'com.tealium:kotlin-lifecycle:1.1.1'
    }
    

Manual

To install the Lifecycle Tracking module manually, following these steps:

  1. Download the Tealium Lifecycle Tracking Module module.

  2. Copy the file tealium-kotlin.lifecycle-1.1.1.aar into your project’s <PROJECT_ROOT>/<MODULE>/libs directory.

  3. Add the Tealium library dependency to your project module’s build.gradle file:

    dependencies {
          implementation(name:'tealium-kotlin.lifecycle-1.1.1', ext:'aar')
    }
    

Automatically Tracked Events

The module tracks the following lifecycle events, set by the lifecycle_type variable:

Lifecycle Event Description
launch 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 launch event.
sleep 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 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.

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.

It is enabled with the following code:

val config = TealiumConfig(
                applicaiton,
                "accountName",
                "profileName",
                Environment.DEV,
                modules = mutableSetOf(Modules.Lifecycle)
                )

Manually Tracked Events

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 isAutoTrackingEnabled to false.

Configuration Options

val config = TealiumConfig(...)

config.isAutoTrackingEnabled = false

To manually track a launch event, call the trackLaunchEvent() method:

tealium.lifecycle?.trackLaunchEvent()

To manually track a sleep event, call the trackSleepEvent() method:

tealium.lifecycle?.trackSleepEvent()

To manually track a wake event, call the trackWakeEvent() method:

tealium.lifecycle?.trackWakeEvent()

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 has the lifecycle_diddetectcrash variable added.

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

Data Layer

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

Variable Type Description Example Event
lifecycle_ dayofweek_local Number Local day of week that call was made, such as 1=Sunday, 2=Monday 2 all
lifecycle_ dayssincelaunch Number Days since first launch in integer increments 23 all
lifecycle_ dayssinceupdate Number Days since the last detected app version update in integer increments 46 all
lifecycle_ dayssincelastwake Number Days since last detected wake in integer increments 1 all
lifecycle_ diddetectcrash Boolean Crash inferred from missing prior sleep event (only present if a launch event follows a wake event) [true, false] launch
lifecycle_ firstlaunchdate String GMT timestamp of the first detected launch/wake in ISO8601 format from Zulu time "2013-07-11T17:55:04Z" all
lifecycle_ firstlaunchdate_ MMDDYYYY String GMT Timestamp formatted as MM/DD/YYYY "01/17/2012" all
lifecycle_ hourofday_local String Local hour of day that call was made (24 hour format) "12" all
lifecycle_ isfirstlaunch Boolean Only present if call is the first launch call [true, false] launch
lifecycle_ isfirstlaunchupdate Boolean Only present if call is first launch after a detected updated [true, false] launch
lifecycle_ isfirstwakemonth Boolean Only present if call is first launch/wake of the month [true, false] launch, wake
lifecycle_ isfirstwaketoday Boolean Only present if call is first launch/wake of the day [true, false] launch, wake
lifecycle_ launchcount Number Total number of launches this version of your app (since the last update) 3 all
lifecycle_ secondsawake Number Whole seconds app was awake since last wake/launch (sent only with lifecycle_type:sleep or lifecycle_type:terminate calls) 30 all
lifecycle_ priorsecondsawake Number Whole seconds app was awake since last launch only - aggregates total from all wakes prior (sent only with lifecycle_type:launch calls) 126 all
lifecycle_ sleepcount Number Total number of times your app has gone to sleep (resets if updated) 5 all
lifecycle_ totalcrashcount Number Total number of crashes counted since install (only reset if app deleted) 21 all
lifecycle_ totallaunchcount Number Total number of launches since install (only reset if app deleted) 3 all
lifecycle_ totalsecondsawake Number Total number of seconds your app has been in a woken/active state since app install (only reset if app deleted) 36 all
lifecycle_ totalsleepcount Number Total number of times your app has gone into the background since app install (only reset if app deleted) 400 all
lifecycle_ totalwakecount Number Total number of launches + wakes since install (only reset if app deleted) 563 all
lifecycle_type String Type of lifecycle call ["initial", "launch", "wake", "sleep", "terminate"] all
lifecycle_ updatelaunchdate String GMT timestamp of first wake/launch after a version update has been detected "2014-09-08T18:10:01Z" all
lifecycle_ wakecount Number Total number of launches + wakes in this version of your app (resets if updated) 29 all

API Reference

For the reference of methods used by the Lifecycle Tracking module, see the LifeCycle class in the Tealium SDK for Android API.

Was this page helpful?

This page was last updated: January 7, 2023