Mobile App Events
These are the events the mobile SDKs emit automatically. They are cross-vertical: an app in any industry produces them, alongside whichever vertical events it tracks explicitly.
The names follow GA4’s app taxonomy so that a GA4 app property gets its automatic reporting without remapping, and the snake_case convention every other event ID in these specs uses.
Auto-tracking is on by default and controlled by the trackAppLifecycle
config option. Set it to false if you would rather emit these yourself.
Lifecycle events
first_open
Fired on the first launch after install. Emitted once per install, not once per device — a reinstall fires it again.
// Emitted automatically by the SDK
{ version: '2.4.0', build: '1180' }| Property | Type | Required | Description |
|---|---|---|---|
version | string | Optional | App version string (CFBundleShortVersionString / versionName) |
build | string | Optional | Build number (CFBundleVersion / versionCode) |
app_update
Fired on the first launch after the app version or build number changes.
| Property | Type | Required | Description |
|---|---|---|---|
version | string | Optional | The new app version |
build | string | Optional | The new build number |
previous_version | string | Optional | The version this install upgraded from |
previous_build | string | Optional | The build this install upgraded from |
app_open
Fired when the app enters the foreground, including on a cold start.
Only a real background-to-foreground transition counts. Returning from Control Centre, a system alert, or the app switcher does not fire it again.
| Property | Type | Required | Description |
|---|---|---|---|
from_background | boolean | Optional | false on a cold start, true when returning from background |
version | string | Optional | App version string |
build | string | Optional | Build number |
app_background
Fired when the app enters the background. The SDK flushes its queue at the same moment, so events collected during the session are not held until next launch.
This event has no properties.
Screen views
screen_view
The mobile equivalent of a page view, emitted by screen(name).
datafly.screen('ProductDetail', { item_id: 'SKU-001' })
// → event: 'screen_view', properties: { screen_name: 'ProductDetail', item_id: 'SKU-001' }The screen name travels as a property, not as the event name, so a blueprint matches one event rather than needing a rule per screen.
| Property | Type | Required | Description |
|---|---|---|---|
screen_name | string | Required | Name of the screen viewed |
Any additional properties passed to screen() are carried through unchanged.
What is not an event
There is deliberately no session_start event.
Session boundaries travel on context.session.is_new, which the ingestion
gateway stamps authoritatively for every event — the same signal the web
collector uses to drive GA4’s _ss parameter. Emitting a separate event would
double-count against it.
Session identifiers are available to blueprints as context.session.id,
context.session.number and context.session.is_new.