Lifecycle

public protocol Lifecycle

The Lifecycle module is a Collector module that automatically tracks application lifecycle events — launch, wake, and sleep. It maintains persistent counters and timestamps across sessions, detects crashes, tracks app version updates, and provides rich lifecycle metrics to the lifecycle events (or, optionally, to all tracked events). By default, the module automatically listens for application status changes and tracks corresponding lifecycle events without requiring manual intervention.

Collected Data Points

The Lifecycle module collects the following information when lifecycle events occur:

Installation/Configuration

The Lifecycle module can be configured using three different approaches:

Local and Remote Settings

Configure the module using local JSON settings file (via settingsFile parameter) and/or remote settings (via settingsUrl parameter):

var config = TealiumConfig(account: "tealiummobile",
                          profile: "your-profile",
                          environment: "dev",
                          settingsFile: "TealiumSettings",
                          settingsUrl: "https://tags.tiqcdn.com/dle/tealiummobile/lib/example_settings.json")

Default initialization - module will be initialized only if configured in settings file specified:

{
    "modules": {
        "Lifecycle": {
            "module_type": "Lifecycle"
        }
    }
}

Custom configuration - module with specific settings:

{
    "modules": {
        "Lifecycle": {
            "module_type": "Lifecycle",
            "enabled": true,
            "order": 1,
            "rules": {
                "operator": "and",
                "children": [
                    "rule_id_from_settings"
                ]
            },
            "configuration": {
                "autotracking_enabled": true,
                "session_timeout": 1440,
                "tracked_lifecycle_events": ["launch", "wake", "sleep"],
                "data_target": "lifecycleEventsOnly"
            }
        }
    }
}

When both local and remote settings are provided, they are deep merged with remote settings taking priority.

Programmatic Configuration

Configure the module programmatically by adding it to the modules parameter in TealiumConfig.

Default initialization - module will be initialized with default settings:

let config = TealiumConfig(account: "tealiummobile",
                          profile: "your-profile",
                          environment: "dev",
                          modules: [
                              Modules.lifecycle(),
                              // other modules...
                          ])

Custom configuration - module with enforced settings:

let config = TealiumConfig(account: "tealiummobile",
                          profile: "your-profile",
                          environment: "dev",
                          modules: [
                              Modules.lifecycle(forcingSettings: { builder in
                                  builder.setEnabled(true)
                                         .setOrder(1)
                                         .setRules(.and(["rule_id_from_settings"]))
                                         .setAutoTrackingEnabled(true)
                                         .setSessionTimeoutInMinutes(1440)
                                         .setTrackedLifecycleEvents([.launch, .wake, .sleep])
                                         .setDataTarget(.lifecycleEventsOnly)
                              }),
                              // other modules...
                          ])

⚠️ Important: Programmatic settings are deep merged onto local and remote settings and will always take precedence. Only provide programmatic settings for configuration values that you never want to be changed remotely, as they will override any remote updates.

Configuration Options

The Lifecycle module supports the following configuration options:

Settings Builders Reference

The Lifecycle module uses the LifecycleSettingsBuilder for configuration. This is an extension of the CollectorSettingsBuilder which offers common settings like:

• ModuleSettingsBuilder.setEnabled(_:)
• ModuleSettingsBuilder.setOrder(_:)
• RuleModuleSettingsBuilder.setRules(_:)

Lifecycle-specific methods:

• LifecycleSettingsBuilder.setAutoTrackingEnabled(_:) - Enable or disable automatic lifecycle tracking
• LifecycleSettingsBuilder.setSessionTimeoutInMinutes(_:) - Set the session timeout duration in minutes
• LifecycleSettingsBuilder.setTrackedLifecycleEvents(_:) - Set which lifecycle events generate dispatches
• LifecycleSettingsBuilder.setDataTarget(_:) - Set whether lifecycle data is attached to all events or only lifecycle events

Event Order Validation

The module enforces a strict event order to maintain data integrity:

• Launch: Valid as the first event in the current process lifetime (i.e., before any launch has been registered since the app started). A second launch event in the same process lifetime is invalid and will throw an invalidEventOrder error. Crash detection occurs on a fresh app start when the persisted last event indicates the app never went to sleep before terminating.
• Sleep: Valid only after a launch or wake event.
• Wake: Valid only after a sleep event.

Invalid event order in manual tracking mode throws a LifecycleError.invalidEventOrder error. In auto-tracking mode, invalid sequences are logged and ignored.

Crash Detection

Crashes are detected heuristically: if the last recorded lifecycle event was a launch or wake (meaning the app never went to sleep/background properly), and a new launch occurs, the module concludes the app likely crashed. On such launches:

• lifecycle_diddetectcrash is set to true
• lifecycle_totalcrashcount is incremented

Crash detection runs only when a launch event is accepted and recorded; invalid event orders that are ignored do not increment crash counters.

App Version Update Detection

On each launch, the module compares the current app version (CFBundleShortVersionString or CFBundleVersion) against the cached version. If a change is detected:

• lifecycle_isfirstlaunchupdate is set to true on that launch event
• lifecycle_updatelaunchdate is set to the current timestamp
• Session counters (lifecycle_launchcount, lifecycle_wakecount, lifecycle_sleepcount) are reset, then the launch itself is registered — so the first post-update launch dispatch will report lifecycle_launchcount=1, lifecycle_wakecount=1, lifecycle_sleepcount=0
• Total counters are not affected

Usage

You can use the lifecycle functionality by accessing an interface on the Tealium object.

// Manual tracking (only when auto-tracking is disabled)
tealium.lifecycle().launch().subscribe { result in
    // Optionally handle result here
}

tealium.lifecycle().sleep().subscribe { result in
    // Optionally handle result here
}

tealium.lifecycle().wake().subscribe { result in
    // Optionally handle result here
}

// With optional custom data
tealium.lifecycle().launch(["custom_key": "custom_value"]).subscribe { result in
    // Optionally handle result here
}

⚠️ Note: Manual tracking methods (launch(), wake(), sleep()) will return a manualTrackNotAllowed error if auto-tracking is enabled. Disable auto-tracking first if you need manual control.

See more on the interface definition below.

Lifecycle

The Lifecycle Module sends events related to application lifecycle - launch, wake, and sleep.