Analytics

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 eventsA record of an action in your app, on your website, in the Airship system, or in an external system. Examples are a message send, an app open, or a purchase transaction.. They require enabling analytics for your app.

var event = CustomEvent(name: "event_name", value: 123.12)
try event.setProperties(
    [
        "my_custom_property": "some custom value",
        "is_neat": true,
        "any_json": [
            "foo": "bar"
        ]
    ]
)
event.track()

@import AirshipObjectiveC;

UACustomEvent *event = [[UACustomEvent alloc] initWithName:@"event_name" value:123.12];
[event setProperties: @{
    @"my_custom_property": @"some custom value",
    @"is_neat": @YES,
    @"any_json": @{
        @"foo": @"bar"
    }
} error:&error];
[event track];

Templates

Custom event templates are wrappers for custom events. See also CustomEvent in the iOS 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:

let acctEvent = CustomEvent(accountTemplate: .registered)
acctEvent.track()

With optional properties:

var acctEvent = CustomEvent(
    accountTemplate: .registered,
    properties: CustomEvent.AccountProperties(
        category: "Premium",
        isLTV: true
    )
)
acctEvent.eventValue = 9.99
acctEvent.transactionID = "12345"
acctEvent.track()

Track a registered account event:

@import AirshipObjectiveC;

UACustomEvent *acctEvent = [[UACustomEvent alloc] initWithAccountTemplate:[UACustomEventAccountTemplate registered]];
[acctEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventAccountProperties *properties = [[UACustomEventAccountProperties alloc] initWithCategory:@"Premium"
                                                                                                   type:nil
                                                                                                  isLTV:YES
                                                                                                 userID:nil];
UACustomEvent *acctEvent = [[UACustomEvent alloc] initWithAccountTemplate:[UACustomEventAccountTemplate registered] properties:properties];
acctEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"9.99"] decimalValue];
acctEvent.transactionID = @"12345";
[acctEvent 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:

let mediaEvent = CustomEvent(mediaTemplate: .consumed)
mediaEvent.track()

With an optional value:

var mediaEvent = CustomEvent(
    mediaTemplate: .consumed,
    properties: CustomEvent.MediaProperties(isLTV: true)
)
mediaEvent.eventValue = 1.99
mediaEvent.track()

With optional properties:

var mediaEvent = CustomEvent(
    mediaTemplate: .consumed,
    properties: CustomEvent.MediaProperties(
        id: "12322",
        category: "entertainment",
        type: "video",
        eventDescription: "Watching latest entertainment news.",
        author: "UA Enterprises",
        isFeature: true,
        isLTV: true
    )
)
mediaEvent.eventValue = 2.99
mediaEvent.track()

Track a consumed content event:

@import AirshipObjectiveC;

UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate consumed]];
[mediaEvent track];

With an optional value:

@import AirshipObjectiveC;

UACustomEventMediaProperties *properties = [[UACustomEventMediaProperties alloc] initWithId:nil
                                                                                     category:nil
                                                                                         type:nil
                                                                             eventDescription:nil
                                                                                        isLTV:YES
                                                                                       author:nil
                                                                                publishedDate:nil
                                                                                    isFeature:nil];
UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate consumed] properties:properties];
mediaEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"1.99"] decimalValue];
[mediaEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventMediaProperties *properties = [[UACustomEventMediaProperties alloc] initWithId:@"12322"
                                                                                     category:@"entertainment"
                                                                                         type:@"video"
                                                                             eventDescription:@"Watching latest entertainment news."
                                                                                        isLTV:YES
                                                                                       author:@"UA Enterprises"
                                                                                publishedDate:nil
                                                                                    isFeature:@YES];
UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate consumed] properties:properties];
mediaEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"2.99"] decimalValue];
[mediaEvent track];

Track a starred content event:

let mediaEvent = CustomEvent(mediaTemplate: .starred)
mediaEvent.track()

With optional properties:

var mediaEvent = CustomEvent(
    mediaTemplate: .starred,
    properties: CustomEvent.MediaProperties(
        id: "12322",
        category: "entertainment",
        type: "video",
        eventDescription: "Watching latest entertainment news.",
        author: "UA Enterprises",
        isFeature: true
    )
)
mediaEvent.eventValue = 2.99
mediaEvent.track()

Track a starred content event:

@import AirshipObjectiveC;

UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate starred]];
[mediaEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventMediaProperties *properties = [[UACustomEventMediaProperties alloc] initWithId:@"12322"
                                                                                     category:@"entertainment"
                                                                                         type:@"video"
                                                                             eventDescription:@"Watching latest entertainment news."
                                                                                        isLTV:NO
                                                                                       author:@"UA Enterprises"
                                                                                publishedDate:nil
                                                                                    isFeature:@YES];
UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate starred] properties:properties];
mediaEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"2.99"] decimalValue];
[mediaEvent track];

Track a browsed content event:

let mediaEvent = CustomEvent(mediaTemplate: .browsed)
mediaEvent.track()

With optional properties:

let mediaEvent = CustomEvent(
    mediaTemplate: .browsed,
    properties: CustomEvent.MediaProperties(
        id: "12322",
        category: "entertainment",
        type: "video",
        eventDescription: "Browsed latest entertainment news.",
        author: "UA Enterprises",
        isFeature: true
    )
)
mediaEvent.track()

Track a browsed content event:

@import AirshipObjectiveC;

UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate browsed]];
[mediaEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventMediaProperties *properties = [[UACustomEventMediaProperties alloc] initWithId:@"12322"
                                                                                     category:@"entertainment"
                                                                                         type:@"video"
                                                                             eventDescription:@"Browsed latest entertainment news."
                                                                                        isLTV:NO
                                                                                       author:@"UA Enterprises"
                                                                                publishedDate:nil
                                                                                    isFeature:@YES];
UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate browsed] properties:properties];
[mediaEvent track];

Track a shared content event:

let mediaEvent = CustomEvent(mediaTemplate: .shared)
mediaEvent.track()

With a source and medium:

let mediaEvent = CustomEvent(
    mediaTemplate: .shared(source: "facebook", medium: "social")
)
mediaEvent.track()

With optional properties:

var mediaEvent = CustomEvent(
    mediaTemplate: .shared(source: "facebook", medium: "social"),
    properties: CustomEvent.MediaProperties(
        id: "1234",
        category: "entertainment",
        type: "video",
        eventDescription: "Watching latest entertainment news.",
        author: "UA Enterprises",
        isFeature: true
    )
)
mediaEvent.track()

Track a shared content event:

@import AirshipObjectiveC;

UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate sharedWithSource:nil medium:nil]];
[mediaEvent track];

With a source and medium:

@import AirshipObjectiveC;

UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate sharedWithSource:@"facebook" medium:@"social"]];
[mediaEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventMediaProperties *properties = [[UACustomEventMediaProperties alloc] initWithId:@"1234"
                                                                                     category:@"entertainment"
                                                                                         type:@"video"
                                                                             eventDescription:@"Watching latest entertainment news."
                                                                                        isLTV:NO
                                                                                       author:@"UA Enterprises"
                                                                                publishedDate:nil
                                                                                    isFeature:@YES];
UACustomEvent *mediaEvent = [[UACustomEvent alloc] initWithMediaTemplate:[UACustomEventMediaTemplate sharedWithSource:@"facebook" medium:@"social"] properties:properties];
[mediaEvent 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:

let retailEvent = CustomEvent(retailTemplate: .purchased)
retailEvent.track()

With optional properties:

var retailEvent = CustomEvent(
    retailTemplate: .purchased,
    properties: CustomEvent.RetailProperties(
        id: "1234",
        category: "mens shoe",
        eventDescription: "Low top",
        isLTV: true,
        brand: "SpecialBrand",
        isNewItem: true
    )
)
retailEvent.eventValue = 99.99
retailEvent.transactionID = "13579"
retailEvent.track()

Track a purchased event:

@import AirshipObjectiveC;

UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate purchased]];
[retailEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventRetailProperties *properties = [[UACustomEventRetailProperties alloc] initWithId:@"1234"
                                                                                       category:@"mens shoe"
                                                                                           type:nil
                                                                               eventDescription:@"Low top"
                                                                                          isLTV:YES
                                                                                          brand:@"SpecialBrand"
                                                                                      isNewItem:@YES
                                                                                       currency:nil];
UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate purchased] properties:properties];
retailEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"99.99"] decimalValue];
retailEvent.transactionID = @"13579";
[retailEvent track];

Track a browsed event:

let retailEvent = CustomEvent(retailTemplate: .browsed)
retailEvent.track()

With optional properties:

var retailEvent = CustomEvent(
    retailTemplate: .browsed,
    properties: CustomEvent.RetailProperties(
        id: "1234",
        category: "mens shoe",
        eventDescription: "Low top",
        brand: "SpecialBrand",
        isNewItem: true
    )
)
retailEvent.eventValue = 99.99
retailEvent.transactionID = "13579"
retailEvent.track()

Track a browsed event:

@import AirshipObjectiveC;

UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate browsed]];
[retailEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventRetailProperties *properties = [[UACustomEventRetailProperties alloc] initWithId:@"1234"
                                                                                       category:@"mens shoe"
                                                                                           type:nil
                                                                               eventDescription:@"Low top"
                                                                                          isLTV:NO
                                                                                          brand:@"SpecialBrand"
                                                                                      isNewItem:@YES
                                                                                       currency:nil];
UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate browsed] properties:properties];
retailEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"99.99"] decimalValue];
retailEvent.transactionID = @"13579";
[retailEvent track];

Track an added-to-cart event:

let retailEvent = CustomEvent(retailTemplate: .addedToCart)
retailEvent.track()

With optional properties:

var retailEvent = CustomEvent(
    retailTemplate: .addedToCart,
    properties: CustomEvent.RetailProperties(
        id: "1234",
        category: "mens shoe",
        eventDescription: "Low top",
        brand: "SpecialBrand",
        isNewItem: true
    )
)
retailEvent.eventValue = 99.99
retailEvent.transactionID = "13579"
retailEvent.track()

Track an added-to-cart event:

@import AirshipObjectiveC;

UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate addedToCart]];
[retailEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventRetailProperties *properties = [[UACustomEventRetailProperties alloc] initWithId:@"1234"
                                                                                       category:@"mens shoe"
                                                                                           type:nil
                                                                               eventDescription:@"Low top"
                                                                                          isLTV:NO
                                                                                          brand:@"SpecialBrand"
                                                                                      isNewItem:@YES
                                                                                       currency:nil];
UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate addedToCart] properties:properties];
retailEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"99.99"] decimalValue];
retailEvent.transactionID = @"13579";
[retailEvent track];

Track a starred product event:

let retailEvent = CustomEvent(retailTemplate: .starred)
retailEvent.track()

With optional properties:

var retailEvent = CustomEvent(
    retailTemplate: .starred,
    properties: CustomEvent.RetailProperties(
        id: "1234",
        category: "mens shoe",
        eventDescription: "Low top",
        brand: "SpecialBrand",
        isNewItem: true
    )
)
retailEvent.eventValue = 99.99
retailEvent.transactionID = "13579"
retailEvent.track()

Track a starred product event:

@import AirshipObjectiveC;

UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate starred]];
[retailEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventRetailProperties *properties = [[UACustomEventRetailProperties alloc] initWithId:@"1234"
                                                                                       category:@"mens shoe"
                                                                                           type:nil
                                                                               eventDescription:@"Low top"
                                                                                          isLTV:NO
                                                                                          brand:@"SpecialBrand"
                                                                                      isNewItem:@YES
                                                                                       currency:nil];
UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate starred] properties:properties];
retailEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"99.99"] decimalValue];
retailEvent.transactionID = @"13579";
[retailEvent track];

Track a shared product event:

let retailEvent = CustomEvent(retailTemplate: .shared())
retailEvent.track()

With a source and medium:

let retailEvent = CustomEvent(
    retailTemplate: .shared(source: "facebook", medium: "social")
)
retailEvent.track()

With optional properties:

var retailEvent = CustomEvent(
    retailTemplate: .shared(source: "facebook", medium: "social"),
    properties: CustomEvent.RetailProperties(
        id: "1234",
        category: "mens shoe",
        eventDescription: "Low top",
        brand: "SpecialBrand",
        isNewItem: true
    )
)
retailEvent.transactionID = "13579"
retailEvent.track()

Track a shared product event:

@import AirshipObjectiveC;

UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate sharedWithSource:nil medium:nil]];
[retailEvent track];

With a source and medium:

@import AirshipObjectiveC;

UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate sharedWithSource:@"facebook" medium:@"social"]];
[retailEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventRetailProperties *properties = [[UACustomEventRetailProperties alloc] initWithId:@"1234"
                                                                                       category:@"mens shoe"
                                                                                           type:nil
                                                                               eventDescription:@"Low top"
                                                                                          isLTV:NO
                                                                                          brand:@"SpecialBrand"
                                                                                      isNewItem:@YES
                                                                                       currency:nil];
UACustomEvent *retailEvent = [[UACustomEvent alloc] initWithRetailTemplate:[UACustomEventRetailTemplate sharedWithSource:@"facebook" medium:@"social"] properties:properties];
retailEvent.transactionID = @"13579";
[retailEvent track];

Search

Use this template to create custom events for search-related events.

Track a search event:

let searchEvent = CustomEvent(searchTemplate: .search)
searchEvent.track()

With optional properties:

var searchEvent = CustomEvent(
    searchTemplate: .search,
    properties: CustomEvent.SearchProperties(
        category: "hotels",
        query: "beach resort",
        totalResults: 53
    )
)
searchEvent.eventValue = 1.0
searchEvent.track()

Track a search event:

@import AirshipObjectiveC;

UACustomEvent *searchEvent = [[UACustomEvent alloc] initWithSearchTemplate:[UACustomEventSearchTemplate search]];
[searchEvent track];

With optional properties:

@import AirshipObjectiveC;

UACustomEventSearchProperties *properties = [[UACustomEventSearchProperties alloc] initWithId:nil
                                                                                          query:@"beach resort"
                                                                                   totalResults:@53
                                                                                       category:@"hotels"
                                                                                           type:nil
                                                                                          isLTV:NO];
UACustomEvent *searchEvent = [[UACustomEvent alloc] initWithSearchTemplate:[UACustomEventSearchTemplate search] properties:properties];
searchEvent.eventValue = [[NSDecimalNumber decimalNumberWithString:@"1.0"] decimalValue];
[searchEvent track];

Associated Identifiers

Associated identifiers (also called custom identifiers) associate an external identifier with a channelA device or address registered with Airship to receive messages, such as a mobile app, web browser, email address, or SMS number. It stores opt-in status, device-specific information, and metadata used for targeting. Each channel has a unique channel ID.. 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.

let identifiers = Airship.analytics.currentAssociatedDeviceIdentifiers()
identifiers.set(identifier: "value", key:"key")
Airship.analytics.associateDeviceIdentifiers(identifiers)

@import AirshipObjectiveC;

UAAssociatedIdentifiers *identifiers = [UAirship.analytics currentAssociatedDeviceIdentifiers];
[identifiers setWithIdentifier:@"value" key:@"key"];
[UAirship.analytics associateDeviceIdentifier:identifiers];

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")

@import AirshipObjectiveC;

[UAirship.analytics trackScreen:@"MainScreen"];