Overview:

Custom events allow you to track user activities and key conversions in your app or from your website. Events consist of two very basic pieces of information. They tell us that a) something happened and b) at a particular time. Events are distinct from tags, which describe the condition of a user, e.g., a stated preference or information about their app version.

The benefit of using custom events is that they change with an individual user’s behavior.
Tags are static: “opted in for sales alerts.” Custom events are dynamic: read_>5_sports_articles. When the user reads more articles the custom event for that user will change.

How does it all work?

Custom events require SDK 5.0.0+ on iOS/ Android. Analytics need to be turned on in the application before you can start adding and tracking app events.

The first step is identifying what user activities in your app you want to capture. Click through your app- what user actions could trigger a message? What user actions do you want to count how frequently/how much a user does something? Conversion events like viewed_content, purchased_item are good places to start.

Custom event properties can be used for further qualifying trigger conditions, increasing personalization in messaging, and generating more sophisticated analytics through use in Insight.

A list of recommended custom events, properties, and use cases are below.

Once you define your custom events and use cases, you can start messaging users based on these custom events & behaviors within the app.

Setting up an Automation within the Dashboard:

You can view custom events within Performance Analytics, our user-level analytics and reporting tool,  to show you how users are moving through the funnel:

How does it all work?

Custom Events can be set from within the SDK as well as events sent from a backend database.

Once you’ve determined what events you want to set, it’s time to determine who to set those events on.

When a user performs a specific event within your lifecycle, use the API or the SDK to add an event and any meta-data and that event will be associated to that user as having triggered that event.

Ensure you have integrated the Sample App (for links to each one, see Developer Resources) in order to take full advantage of working Custom Events to build off of. This will guide you to a better understanding of the inner workings of Custom Events.

More detailed instructions for implementing the Custom Events can be found in our iOS and Android documentation.

Given that you may have multiple platforms to support, you may choose one or both of the options below to integrate Custom Events.

Mobile App integration: Recording a Custom Event

iOS

// Set tags
UAirship.push().tags = ["one", "two", "three"]

// Add a tag
UAirship.push().addTag("a_tag")

// Remove a tag
UAirship.push().removeTag("a_tag")

// Update registration
UAirship.push().updateRegistration()

Android

let event = UACustomEvent(name: "event_name", value: 123.12)

// Record the event
UAirship.shared().analytics.add(event)

Server/Non-Mobile App integration

Airship provides several different options to record Custom Events that may be coming from an external source, such as another analytics provider or database.

One of the more popular integrations is to track Google Analytic events as Airship Custom Events. Setting up Google Analytics and Airship events will require integrating the Google Analytics tracker.

If you have another analytics provider or another system of record that is recording user activity that you would like to also set as Custom Events, you may use the Airship API to record Server-side Custom Events. These allow you to set up events that may be occurring on other platforms, outside of your mobile app.

Testing

Event Tracking report

Performance Analytics Events

Strategic Advice:

Custom events serve two purposes: messaging and measurement.
The best way to get started is to look at every page or screen of your digital experience and circle every action a user can take. Do you want to measure how often a user does that specific action, such as viewed content or added to cart? Would you want to message a user after they completed that task for the first time, or for the third?

Make these actions custom events. You’ll then be able to trigger messaging after the event occurs, and also measure the effectiveness or use of these features.

Implementation Best Practices:

Custom Event Templates - Having trouble thinking of Custom Events to record? Use the Custom Event Templates for a list of Custom Events you can easily set in your app for your mobile use case.

Next Steps:

Once you’ve deployed custom events, you can:

• Message users based on events or changes to an event
• Set-up automated messaging triggers for when a user adds an event (purchased_footwear could trigger a targeted message thanking them for buying shoes)
• Measure how users progress through your conversion funnel with Insight

Now that you’ve implemented Custom Events into your application, you’ll want to start integrating Named Users in your app. This will allow you to map your own customer ID to an Airship Channel Id, enabling more granular analysis of your audience and push data.

• Step 7: Named User