Analytics for the Android SDK

Track user engagement and app performance with Airship analytics, including custom events, screen tracking, and associated identifiers.

View as Markdown

Analytics allows you to track user engagement and app performance through custom events, screen tracking, and associated identifiers.

For information about controlling what data Airship collects, see Privacy Manager.

Note

Analytics events are batched and uploaded asynchronously in the background to minimize battery impact. The database size is fixed, so events are safely stored even when offline. Events may not upload immediately and may wait until the next app initialization if the app is closed before the upload completes.

Custom Events

Track user activities and key conversions with Custom EventsEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom Events can trigger automation, including Sequences and Scenes. You can code them into your app or website, or send them to Airship from an external source using the Custom Event API. Custom Events contain properties that you can use to personalize messages.. They require enabling analytics for your app.

customEvent("event_name") {
    addProperty("my_custom_property", "some custom value")
    addProperty("is_neat", true)
    addProperty("any_json", jsonMapOf("foo" to "bar"))
}.track()

CustomEvent.newBuilder("event_name")
        .setEventValue(123.12)
        .addProperty("my_custom_property", "some custom value")
        .addProperty("is_neat", true)
        .addProperty("any_json", JsonMap.newBuilder()
                .put("foo", "bar")
                .build())
        .build()
        .track();

Templates

Custom Event Templates are a wrapper for Custom Events and are available for Android, iOS, and Web. See also CustomEvent in the Android SDK library.

Account

Use this template to create Custom Events for account-related events. The template is written with account registration as the example.

Track a registered account event:

customEvent(AccountEventTemplate.Type.REGISTERED) { }.track()

With optional properties:

customEvent(
    type = AccountEventTemplate.Type.REGISTERED,
    properties = AccountEventTemplate.Properties(
        category = "premium"
    )
) {
    setEventValue(9.99)
    setTransactionId("12345")
}.track()

Media

Use this template to create Custom Events for media-related events, including consuming, browsing, starring, and sharing content.

Track a consumed content event:

customEvent(MediaEventTemplate.Type.Consumed) { }.track()

With an optional value:

customEvent(MediaEventTemplate.Type.Consumed) {
    setEventValue(1.99)
}.track()

With optional properties:

customEvent(
    type = MediaEventTemplate.Type.Consumed,
    properties = MediaEventTemplate.Properties(
        id = "12345",
        category = "entertainment",
        type = "video",
        eventDescription = "Watching latest entertainment news.",
        author = "UA Enterprises",
        isFeature = true,
        publishedDate = "August 25, 2016"
    )
) {
    setEventValue(2.99)
}.track()

Track a starred content event:

customEvent(MediaEventTemplate.Type.Starred) { }.track()

With optional properties:

customEvent(
    type = MediaEventTemplate.Type.Starred,
    properties = MediaEventTemplate.Properties(
        id = "12345",
        category = "entertainment",
        type = "video",
        eventDescription = "Watching latest entertainment news.",
        author = "UA Enterprises",
        isFeature = true,
        publishedDate = "August 25, 2016"
    )
) {
    setEventValue(2.99)
}.track()

Track a browsed content event:

customEvent(MediaEventTemplate.Type.Browsed) { }.track()

With optional properties:

customEvent(
    type = MediaEventTemplate.Type.Browsed,
    properties = MediaEventTemplate.Properties(
        id = "12345",
        category = "entertainment",
        type = "video",
        author = "UA Enterprises",
        isFeature = true,
        publishedDate = "August 25, 2016"
    )
) { }.track()

Track a shared content event:

customEvent(MediaEventTemplate.Type.Shared()) { }.track()

With a source and medium:

customEvent(
    MediaEventTemplate.Type.Shared(source = "facebook", medium = "social")
) { }.track()

With optional properties:

customEvent(
    type = MediaEventTemplate.Type.Shared(source = "facebook", medium = "social"),
    properties = MediaEventTemplate.Properties(
        id = "12345",
        category = "entertainment",
        type = "video",
        eventDescription = "Watching latest entertainment news.",
        author = "UA Enterprises",
        isFeature = true,
        publishedDate = "August 24, 2016"
    )
) { }.track()

Retail

Use this template to create Custom Events for retail-related events, including browsing a product, adding an item to a cart, purchasing an item, starring a product, and sharing a product.

Track a purchased event:

customEvent(RetailEventTemplate.Type.Purchased) { }.track()

With optional properties:

customEvent(
    type = RetailEventTemplate.Type.Purchased,
    properties = RetailEventTemplate.Properties(
        id = "12345",
        category = "mens shoes",
        eventDescription = "Low top",
        brand = "SpecialBrand",
        isNewItem = true
    )
) {
    setEventValue(99.99)
    setTransactionId("13579")
}.track()

Track a browsed event:

customEvent(RetailEventTemplate.Type.Browsed) { }.track()

With optional properties:

customEvent(
    type = RetailEventTemplate.Type.Browsed,
    properties = RetailEventTemplate.Properties(
        id = "12345",
        category = "mens shoes",
        eventDescription = "Low top",
        brand = "SpecialBrand",
        isNewItem = true
    )
) {
    setEventValue(99.99)
    setTransactionId("13579")
}.track()

Track an added-to-cart event:

customEvent(RetailEventTemplate.Type.AddedToCart) { }.track()

With optional properties:

customEvent(
    type = RetailEventTemplate.Type.AddedToCart,
    properties = RetailEventTemplate.Properties(
        id = "12345",
        category = "mens shoes",
        eventDescription = "Low top",
        brand = "SpecialBrand",
        isNewItem = true
    )
) {
    setEventValue(99.99)
    setTransactionId("13579")
}.track()

Track a starred product event:

customEvent(RetailEventTemplate.Type.Starred) { }.track()

With optional properties:

customEvent(
    type = RetailEventTemplate.Type.Starred,
    properties = RetailEventTemplate.Properties(
        id = "12345",
        category = "mens shoes",
        eventDescription = "Low top",
        brand = "SpecialBrand",
        isNewItem = true
    )
) {
    setEventValue(99.99)
    setTransactionId("13579")
}.track()

Track a shared product event:

customEvent(RetailEventTemplate.Type.Shared()) { }.track()

With a source and medium:

customEvent(
    RetailEventTemplate.Type.Shared(source = "facebook", medium = "social")
) { }.track()

With optional properties:

customEvent(
    type = RetailEventTemplate.Type.Shared(source = "facebook", medium = "social"),
    properties = RetailEventTemplate.Properties(
        id = "12345",
        category = "mens shoes",
        eventDescription = "Low top",
        brand = "SpecialBrand",
        isNewItem = true
    )
) {
    setEventValue(99.99)
    setTransactionId("13579")
}.track()

Associated Identifiers

Associated identifiers (also called custom identifiers) associate an external identifier with a Channel IDAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address.. They are visible in Real-Time Data StreamingA service that delivers user-level events in real time to your backend or third-party systems using the Data Streaming API.. We recommend adding any IDs that you may want to be visible in your event stream. You can assign up to 20 associated identifiers to a device. Unlike other identifiers (e.g., tags), you cannot use associated identifiers to target your users.

Airship.analytics.editAssociatedIdentifiers {
    addIdentifier("key", "value")
}

Airship.getAnalytics()
    .editAssociatedIdentifiers()
    .addIdentifier("key", "value")
    .apply();

Screen Tracking

The Airship SDK gives you the ability to track which screens a user views within the application, how long a user stayed on each screen, and also includes the user’s previous screen. These events then come through Real-Time Data StreamingA service that delivers user-level events in real time to your backend or third-party systems using the Data Streaming API., allowing you to see the path a user took through the application, or trigger actions based on a user visiting a particular area of the application.

Airship.analytics.trackScreen("MainScreen")

Airship.getAnalytics().trackScreen("MainScreen");