Mobile App Lifecycle Events

Updated

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 and Android SDKs send lifecycle events automatically

If you use iOS 3.0, Android 4.0, or later versions of those SDKs, we automatically capture the following events by default. Our other mobile SDKs are built around our Journeys Track API, which doesn’t automatically capture these events yet. We’re working to support these events in our React Native and Flutter 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"
  }
}
  • event string
    A person installed your app.

    Accepted values:Application Installed

    • build string
      The specific build of the app installed.
    • version string
      The version of the app installed.
  • type string
    Application events are always track calls.

    Accepted values:track

  • userId string
    The identifier of the user performing the event.

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"
  }
}
  • event string
    A person opened your app. Our SDKs automatically send this event when a person opens your app fresh or when they return to the app after sending it to the the background.

    Accepted values:Application Opened

    • build string
      The specific build of the app opened.
    • from_background boolean
      If true, the user opened the app from the background.
    • url string
      The value of UIApplicationLaunchOptionsURLKey from launchOptions. Collected on iOS only.
    • version string
      The version of the app opened.
  • type string
    Application events are always track calls.

    Accepted values:track

  • userId string
    The identifier of the user performing the event.

Application Backgrounded

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

{
  "userId": "019mr8mf4r",
  "type": "track",
  "event": "Application Backgrounded",
  "properties": {}
}
  • event string
    A person sent your app to the background. Our SDKs automatically send this event when a person backgrounds your app.

    Accepted values:Application Backgrounded

  • type string
    Application events are always track calls.

    Accepted values:track

  • userId string
    The identifier of the user performing the event.

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": {}
}
  • event string
    A person brought your app to the foreground after having backgrounded it, indicating that they’re using it again. Our SDKs automatically send this event when a person brings your app back to the foreground.

    Accepted values:Application Foregrounded

  • type string
    Application events are always track calls.

    Accepted values:track

  • userId string
    The identifier of the user performing the event.

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"
  }
}
  • event string
    A person updated your app.

    Accepted values:Application Updated

    • build string
      The specific build of the app the person upgraded to.
    • previous_build string
      The previous build of the app installed—the build a person is upgrading from.
    • previous_version string
      The previous version of the app installed—the version a person is upgrading from.
    • version string
      The version of the app a person upgraded to.
  • type string
    Application events are always track calls.

    Accepted values:track

  • userId string
    The identifier of the user performing the event.

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": {}
}
  • event string
    A person uninstalled your app.

    Accepted values:Application Uninstalled

  • type string
    Application events are always track calls.

    Accepted values:track

  • userId string
    The identifier of the user performing the event.

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": {}
}
  • event string
    A person experienced a crash in your app. Our SDKs automatically send this event when a person experiences a crash in your app.

    Accepted values:Application Crashed

  • type string
    Application events are always track calls.

    Accepted values:track

  • userId string
    The identifier of the user performing the event.
Copied to clipboard!
  Contents
Is this page helpful?