Swift Module: Lifecycle

Swift Module: Lifecycle

by on ‎02-21-2017 08:08 AM - edited on ‎12-22-2017 08:48 AM by (874 Views)

Purpose

Automatically tracks app lifecycle events and associated data. The launch event is triggered when the library is loaded for the first time, sleep event on UIApplicationWillResignActive notification and wake event on UIApplicationDidBecomeActive.

Supported Platforms

  • iOS
  • tvOS
  • watchOS
  • macOS

External Dependencies

UIKit*, Foundation

  • If the UIKit dependency is added to the target app, no further configuration or implementation is necessary. For other platform builds (watchOS, macOS), the lifecycle functions can be triggered manually, see the Delegate Methods section below.

Recommended Usage

Usage of this module is recommended/optional/mandatory.

It is automatically included in Carthage and CocoaPods framework builds.

Included Variables

The following variables will be transmitted with each tracking call while the module is enabled:

Variable Name Description Data Type Example
lifecycle_diddetect_crash Was a crash detected during this launch/wake event. Populated only if true. Boolean true
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_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 update) Number 3
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_secondsawake Whole seconds app was awake since most recent wake/launch. Number 30
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_updatelaunchdate GMT timestamp of first wake/launch after a version update has been detected String 2014-09-08T18:10:01Z
lifecycle_type Type of lifecycle call String "launch", "wake", "sleep"
lifecycle_wakecount Total number of launches + wakes in this version of your app (resets if updated) Number "29"

Crash Detection

The Lifecycle module performs basic crash detection, but does not collect any details about the cause of the crash. It records a crash whenever a lifecycle launch event is seen, without a preceding sleep event. Normally, when an app is closed by the user, a notification from the OS would trigger a lifecycle sleep event, but if the app crashes, there is no time for this to happen, and thus, no sleep event takes place. On the subsequent launch after the crash, the "lifecycle_diddetectcrash" variable is set to true, and the "lifecycle_totalcrashcount" variable is incremented by 1.

Public API

You only need to use these API methods if you are targeting a platform that doesn't support UIKit.

launchDetected

Updates lifecycle records with a launch event and trigger a lifecycle event dispatch.

// launchDetected()
// SAMPLE
func someMethodCalledAtLaunchTime {
    
    // Presuming 'tealium' was initialized earlier
    tealium.lifecycle().launchDetected()

}

wakeDetected

Updates lifecycle records with a wake event and trigger a lifecycle event dispatch. NOTE: wakeDetected() calls can be safely added after a launchDetected() in the same function. The module will only accept a single launch event per instantiated instance.

// wakeDetected()
// SAMPLE
func someMethodCalledWhenAppStarts {
    
    // Presuming 'tealium' was initialized earlier
    tealium.lifecycle().wakeDetected()

}

sleepDetected

Update lifecycle records with a sleep event and trigger a lifecycle event dispatch.

// sleepDetected()
// SAMPLE
func someMethodCalledBeforeAppTerminated {
    
    // Presuming 'tealium' was initialized earlier
    tealium.lifecycle().sleepDetected()

}

Future Improvements

No planned changes

Change Log

Build 1.4.0

  • Changed to use same NSNotifications as Objective-C library (UIApplicationDidBecomeActive and UIApplicationWillResignActive). This ensures lifecycle events are captured as quickly as possible. May potentially impact lifecycle reporting, but should be more accurate than before.
  • Changed implementation of NSKeyedUnarchiver to support Swift 4.0, and add additional error checking