App Lifecycle Events

The Datafly mobile SDKs automatically track key app lifecycle events. This is enabled by default and can be disabled via the trackAppLifecycle configuration option.

Events tracked

first_open

Fired on the very first launch after install. Detected by checking for the absence of a stored app version.

{
  "type": "track",
  "event": "first_open",
  "properties": {
    "version": "2.1.0",
    "build": "42"
  }
}

app_update

Fired on the first launch after an app update. Detected by comparing the stored version/build with the current values.

{
  "type": "track",
  "event": "app_update",
  "properties": {
    "version": "2.2.0",
    "build": "45",
    "previous_version": "2.1.0",
    "previous_build": "42"
  }
}

app_open

Fired when the app enters the foreground.

{
  "type": "track",
  "event": "app_open",
  "properties": {
    "version": "2.2.0",
    "build": "45",
    "from_background": true
  }
}

The from_background property is false on cold launch and true when resuming from background.

app_background

Fired when the app enters the background.

{
  "type": "track",
  "event": "app_background",
  "properties": {}
}

Session management

The SDK maintains a session that tracks user engagement:

A new session is created when:

1. The app is launched for the first time
2. The app returns to foreground after being backgrounded for longer than the session timeout (default 30 minutes)

Implementation details

iOS

The SDK observes UIApplication notifications:

• willEnterForeground — triggers foreground logic + session check
• didEnterBackground — triggers background logic + records timestamp

Android

The SDK registers ActivityLifecycleCallbacks on the Application:

• Tracks an activity counter to determine foreground/background state
• Handles multi-activity apps correctly (only fires backgrounded when all activities are stopped)

Disabling lifecycle tracking

// iOS
let config = DataflyConfig(
    pipelineKey: "dk_live_abc123",
    endpoint: "https://data.example.com",
    trackAppLifecycle: false
)

// Android
val config = DataflyConfig(
    pipelineKey = "dk_live_abc123",
    endpoint = "https://data.example.com",
    trackAppLifecycle = false
)

When disabled, you can still manually track these events using track().

Naming

These follow GA4’s app event taxonomy and the platform’s snake_case event-ID standard, so blueprints can match them like any other catalogued event.

app_open fires on a real background-to-foreground transition, not on every didBecomeActive — returning from Control Centre or a system alert does not count. On a cold start it reports from_background: false.

There is deliberately no session_start event. Session boundaries travel on context.session.is_new, which the gateway stamps authoritatively for every event; emitting a separate event would double-count against the same signal the web collector already uses for GA4 _ss.