20

Mobile App Lifecycle Events

How it works

Our Mobile App Lifecycle Event specification helps you send events in a uniform format that automatically maps data destinations. Following this spec makes it easier to use data from your mobile apps without having to re-map your incoming data to each destination.

These events typically contain information about your app version and build. If you use our SDKs, we capture some of the following events automatically. Some, like Application Crashed, are events you’ll send manually.

Our iOS 3.x SDK sends some events automatically

If you use iOS 3.x or later, we automatically capture the following events for you. Our other mobile SDKs are built around our Journeys Track API, which doesn’t automatically capture these events yet. We’re working to add this functionality to our other SDKs.

• Application Installed
• Application Opened
• Application Backgrounded
• Application Foregrounded
• Application Updated

These events can help you understand your customer’s lifecycle—like the time they spend in the app (time from opened to backgrounded), how often they update the app, and so on.

You’ll notice that our mobile SDKs don’t capture events like Application Crashed automatically. That’s because the app must be opened for us to send events from your app to Customer.io.

Application Installed

Our CDP-enabled SDKs send this event the first time a user opens your application. If the user never opens your app, we won’t be able to collect this event. This event doesn’t wait for the SDK to capture attribution or campaign information, and is collected automatically. Destinations like Facebook and Google require discrete install events to correctly attribute installs to ads served through their platforms.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Installed",
  "properties": {
    "version": "1.2.3", "build": "1234"
  }
}

Application Opened

Send this event when a user launches your mobile application—after the first open. The first open results in an Application Installed event, so we only send this event on subsequent opens. Like the Application Installed event, this event also does not wait for the SDK to capture attribution information but it can include information about referring applications or deep link URLs if available when the app opens.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Opened",
  "properties": {
    "from_background": false,
    "referring_application": "GMail",
    "url": "url://location"
  }
}

Application Backgrounded

Send this event when a user backgrounds the application upon applicationDidEnterBackground.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Backgrounded",
  "properties": {}
}

Application Foregrounded

Send this event when your audience returns to your app after previously backgrounding it. This event is distinct from Application Opened in that the app is considered opened already, even if it’s in the background.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Foregrounded",
  "properties": {}
}

Application Updated

This event fires when the user opens your app after updating your app. Our CDP-enabled SDKs automatically collect this event rather than the “Application Opened” event after someone updates your app.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Updated",
  "properties": {
    "previous_version": "1.1.2",
    "previous_build": "1234",
    "version": "1.2.0",
    "build": "1456"
  }
}

Application Uninstalled

You can send this event when a user uninstalls your app. Like similar events that happen outside of your app itself, our CDP-enabled SDKs cannot capture this event automatically.

However, some direct-mode destinations detect this for you using silent push notifications through their own SDKs. You might also be able to send these events to Customer.io using callbacks.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Uninstalled",
  "properties": {}
}

Application Crashed

You can send this event when you receive a crash notification from your app, but it is not meant to supplant traditional crash reporting tools. By tracking crashes this way, you can analyze which types of users are impacted by crashes and how those crashes affect their engagement. You may also want to send messages to users who experience crashes through other messaging channels.

Like similar events that happen outside of your app itself, our CDP-enabled SDKs cannot capture this event automatically. But you might be able to capture this kind of event with a callback or a webhook.

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Crashed",
  "properties": {}
}