Events
Events power Airship automation, segmentation, and data products.
Airship SDKs and APIs generate dozens of different kinds of events, ranging in purpose from engagement events like app opens or screen views, to Airship system events like sends, to custom events that you can define to suit your brand’s needs.
See also: Events reference.
What are events?
From our friends at dictionary.com :
event [ ih-vent ] noun
- something that happens or is regarded as happening; an occurrence, especially one of some importance.
- the outcome, issue, or result of anything: The venture had no successful event.
- something that occurs in a certain place during a particular interval of time.
In the Airship system, your business systems, social media, and elsewhere, events happen all the time. People are using your app (or not!), changing location, opting in or out of notifications, and these actions or inactions generate events. Events can represent:
- Customer behavior — App open, pageview, purchase
- Airship system activity — Compliance, message sends, message expiration
- External events — Social media, POS transactions, CRM changes
What can I do with events?
Events power our internal data products, partner integrations, and automation and segmentation services. They are also emitted into the Airship Real-Time Data Streaming (RTDS)A service that delivers engagement events in real time via the Data Streaming API or an Airship partner integration. service, allowing you to use streaming event data for custom integrations.
To learn more about how to leverage Airship events, see the following resources:
- Event Segmentation — Segment audiences by event count, value, and recency, and with advanced filtering capabilities.
- Automation — Trigger messages based on events and event properties. See also: SequenceA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its audience and continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey., In-App AutomationMessages cached on users’ devices and displayed when users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times., SceneA single or multi-screen in-app experience cached on users’ devices and displayed when users meet certain conditions in your app or website, such as viewing a particular screen or when a Custom Event occurs. They can be presented in fullscreen, modal, or embedded format using the default swipe/click mode or as a Story. Scenes can also contain survey questions., and SurveyA question-and-answer experience used to collect and aggregate feedback or generate a net promoter score. Surveys are cached on users’ devices and displayed when users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times..
- Data & Analytics — Analyze customer trends and optimize your engagement strategy with our data products: Real-Time Data Streaming and Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data..
- Integrations — Gain a broader understanding of the customer lifecycle, from attribution to acquisition to engagement, with one of our ready-made partner integrations.
What do events look like?
Events typically include a timestamp for when the event occurred, information about the associated user and/or device, the event TYPE
, and additional user- or event-specific details.
Here’s an example of a SCREEN_VIEWED
event as it appears in the RTDS stream:
{
"id": "fe882bd1-e0b9-11ea-bc35-0242f70dd9ff",
"offset": "1000060042216",
"occurred": "2020-08-17T18:46:28.046Z",
"processed": "2020-08-17T18:46:44.405Z",
"device": {
"ios_channel": "e27dd2e0-62e8-44e1-b123-2a98f6dd873e",
"channel": "e27dd2e0-62e8-44e1-b123-2a98f6dd873e",
"device_type": "IOS",
"named_user_id": "pfd",
"identifiers": {
"com.urbanairship.limited_ad_tracking_enabled": "false",
"session_id": "261371DB-235A-45DE-B1F2-A6B92507BCD3",
"GA_CID": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d",
"com.urbanairship.idfa": "00000000-0000-0000-0000-000000000000",
"com.urbanairship.vendor": "164594EF-582D-4F1D-B1B8-844738591F86"
},
"attributes": {
"locale_variant": "",
"app_version": "738",
"device_model": "iPhone12,8",
"connection_type": "CELL",
"app_package_name": "com.urbanairship.stag.goat",
"iana_timezone": "America/Los_Angeles",
"push_opt_in": "true",
"locale_country_code": "US",
"device_os": "13.5.1",
"locale_timezone": "-25200",
"carrier": "Carrier",
"locale_language_code": "en",
"location_enabled": "true",
"background_push_enabled": "true",
"ua_sdk_version": "14.0.0-beta1",
"location_permission": "ALWAYS_ALLOWED"
}
},
"body": {
"duration": 80799213,
"viewed_screen": "home",
"session_id": "c7adcd61-47c3-412f-9a60-e626ab4c3d1a"
},
"type": "SCREEN_VIEWED"
}
Event segmentation
You can use events in a SegmentA grouping of audience members selected by unique or shared identifiers. Multiple identifiers can be combined within a segment.. Events can be combined with any other segmentation data, such as attributes and tags. Example audience targeting:
- Users who opened your app 3 times in the past 7 days
- Users who opened your app in the past 6 weeks
- Users who were sent an SMS 6 times in the last 2 weeks
- Users who made a purchase of more than $100 in the last 15 days
- Users who have not viewed more than 5 pieces of content
When building a segment, you will choose whether or not the event was performed and set the frequency of occurrence. You can also specify a date or range when the event occurred and filter by properties associated with the event.
This example shows a segment that targets users with the purchased
event occurring twice between the dates September 1, 2020 and September 15, 2020:
![Events Events](/images/segment-builder-events.png)
- Dashboard tutorials: Create reusable audience segments and Target Specific Users
- API references: Segments and Event Segmentation
Segment evaluation
Airship uses a 90-day “look back” for events and event properties used in segmentation. The exception is for “first” and “last” occurrences, which are stored even if they are more than 90 days old. This window (and the storage of first/last occurrences) starts when an event is activated for segmentation.
As of January 2023, we include “last performed” occurrences when evaluating segmentation queries for events without properties, even when not using the “last performed” operator.
For example, prior to this change, if you targeted all users who performed the event added_to_cart
one or more times, only users who performed the event one or more times in the last 90 days were included in the target audience.
With the change, users who performed the event one or more times in the last 90 days AND users who “last performed” the event prior to the 90-day period would be included in the target audience.
If the query includes a property, such as “added to cart 1 or more times, where the category = shoes,” the evaluation does not include “last performed” occurrences.
Event types
Many events are available out of the box for segmentation. Others require configuration in your SDK implementation and by activating them in the Airship dashboard.
We classify events as one of: default, predefined, or custom. Properties associated with the events can be used for filtering events used in automation and segmentation.
- Default events
- Default events, aka out-of-the-box events, are standard to every implementation, and are automatically enabled for segmentation. Common default events include app open and web click. Default events have properties assigned by Airship.
- Custom events
- Custom events are events for which you define your own name and custom properties. Custom events support a numeric value field which can hold values such as purchase price or a percentage of content consumed. Track custom events from our SDKs or associate them directly with a user using our Custom Events API. Once you define a custom event, you must activate the event for segmentation in the dashboard.
- Predefined events
- Predefined events are custom events that are built into our SDKs as Custom Event Templates. Predefined events represent many common customer use cases for retail-, account-, and media-related events, such as registered account or shared content. Predefined events must be activated for segmentation in the dashboard. Predefined events have properties assigned by Airship, but you can modify or remove them, and you can add your own.
Below is a table showing which events require additional configuration for segmentation.
Event | Predefined properties | Enabled for segmentation by default |
---|---|---|
Default (Out-of-the-box) | ✅ | ✅ |
Custom | ❌ | ❌ |
Predefined (built-in) | ✅1 | ❌ |
1. Can be modified, added, and removed.
See the Events reference for activity names and property information for default, predefined, and custom events.
Default events
Default (OOTB) events come standard with any implementation of our SDKs, or in the case of SMS and email, our channels APIs. Default events correlate with RTDS events, but for the purposes of segmentation, see our events reference, as event types and names may differ slightly.
For example, in RTDS, an email unsubscribe event has a type
of COMPLIANCE
, an event_type
of registration
, and a registration_type
of unsubscribe
.
{
"id": "bd8c90d6-5704-4438-8075-7530d06c4cba",
"offset": "1000001778792",
"occurred": "2018-11-27T23:47:54.641Z",
"processed": "2018-11-27T23:47:55.516Z",
"device": {
"channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
"device_type": "EMAIL",
"delivery_address": "[email protected]"
},
"body": {
"event_type": "registration",
"properties": {
"message_type": "commercial",
"registration_type": "unsubscribe"
}
},
"type": "COMPLIANCE"
}
When targeting an audience after an email unsubscribe event, however, you will use the activity
name of email_unsubscribe
in your request.
{
"audience": {
"activity": "email_unsubscribe",
"metric": "count",
"operator": "equals",
"value": 1
},
"notification": {
"email": {
"subject": "Sorry to see you go!",
"html_body": "<h2>We received your unsubscribe request.</h2><p>Hope you come back some day!</p>"
},
"device_types": [
"email"
]
}
In the dashboard, you can create this audience in the Segment Builder or in Target Specific Users in the Audience step of the Message and A/B Test composers:
- Search for and select the
email_unsubscribe
event. - Select Performed event.
- Select the Equals operator and enter the value
1
.
Predefined events
Predefined events are CUSTOM
events, and are available to use out-of-the-box with built-in templates in our iOS, Android, and Web SDKs. Predefined event are available for many common retail-, media- and account-related use cases. The properties for these events are also predefined, but you can edit or remove them and also add custom properties. See: Manage Events.
You must implement and track the events in your app or website using Custom Event Templates.
The following example uses the retail template in our Web SDK to create and track a purchased
event, passing in optional properties.
new sdk.CustomEvent.templates.retail.PurchasedEvent(99.99, {
id: "12345",
category: "mens shoes",
description: "Low top",
brand: "SpecialBrand",
new_item: true,
}, "13579").track()
Adding and tracking events in the SDK, however, does not activate them for segmentation. See Manage Events to learn how to activate predefined events in the dashboard.
Custom events
If predefined events don’t meet your requirements, you can create and track your own custom events in our SDKs, or submit events with our Custom Events API.
Unlike predefined events, you must define your own event name and properties. Custom events will appear in RTDS and Performance Analytics under the name
that you define for the event. As with predefined events, you must activate your custom event in the UI for segmentation.
{
"id": "036ea86a-4336-40c5-80af-27c4d30fb3d1",
"offset": "1000060042791",
"occurred": "2020-08-18T04:52:00.000Z",
"processed": "2020-08-18T04:52:04.695Z",
"device": {
"channel": "aafe7a54-e1f6-463e-8821-3ccfedf0cf3c",
"device_type": "WEB",
"named_user_id": "ivan_ivanovich"
},
"body": {
"name": "my_event",
"interaction_type": "url",
"interaction_id": "https://example.com",
"value": 20,
"session_id": "774afcd9-c5dd-47bf-94c9-a4f209d49f4a",
"source": "SDK",
"properties": {
"mood": "happy",
"value": 55
}
},
"type": "CUSTOM"
}
Custom events will have a type
of custom
and can represent any user action you wish to track in the SDK. You can also add events that are unrelated to an Airship app or site by using the API.
To learn more about custom events, see our Custom Events Guide.
Filtering by event properties
In addition to targeting your audience by event count, value, and recency, you may further refine your selection by filtering on event properties.
To target event properties, you will use the where object in the API, and include the path to the property along with the values you are filtering for, e.g., push ID, email address, or campaign category. Campaign categories are available only via the API and only when the message includes 1 property.
In the example below, the audience is users who have opened the app by tapping a push notification with the push_id
of "28e9d533-c8a7-4abf-93f4-4794b09391eb"
.
{
"audience": {
"activity": "app_open",
"value": 0,
"operator": "greater",
"metric": "count",
"where": {
"property": "/_triggering_push/push_id",
"operator": "equals",
"compare_as": "text",
"value": "28e9d533-c8a7-4abf-93f4-4794b09391eb"
}
}
}
In the dashboard, you can create this audience in the Segment Builder or in Target Specific Users in the Audience step of the Message and A/B Test composers:
Kategorien