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.

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 and journeys based on events and event properties.
  • Data & Analytics — Analyze customer trends and optimize your engagment strategy with our suite of data products: Dashboard reports, Real-Time Data Streaming, and Performance Analytics.
  • Partner 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.

Examples:

  • Target users who opened your app 3 times in the past 7 days.
  • Target users who opened your app in the past 6 weeks.
  • Target users who were sent an SMS 6 times in the last 2 weeks.
  • Target users who made a purchase of more than $100 in the last 15 days.
  • Target users who have not viewed more than 5 pieces of content.

After selecting an event, 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 occured 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:

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.

EventPredefined propertiesEnabled for segmentation by default
Default (Out-of-the-box)
Custom
Predefined (built-in)1

1. Can be modified, added, and removed.

 Note

We have a 90-day “look back” for events and event properties for use in segmentation. The exception is for “first” and “last” occurrences, which are stored even if they are more than 90 days old.

This 90-day window (and the storage of first/last time an event happened) only begins once an event is activated for segmentation.

Default Events

Default or 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, 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.

Email unsubscribe event in RTDS
{
  "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": "former.user@unsubscriber.com"
  },
  "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.

Target a segment of users based on an email unsubscribe event
{
   "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:

  1. Search for and select the email_unsubscribe event.
  2. Select Performed event.
  3. 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.

Example custom event
{
   "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.

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:

  1. Search for and select the app_open event.
  2. Select Performed event.
  3. Select the Greater than operator and enter the value 0.
  4. Click Add Property.
  5. Search for and select /_triggering_push/push_id.
  6. Select the Equals operator and enter the value 28e9d533-c8a7-4abf-93f4-4794b09391eb.

Events Reference

 Note

For a complete list of events, see our RTDS API Reference.

Default Events and Properties

Below is a list of all available default events. Click Properties to see event properties, use cases, and paths. Default events need no additional configuration on your part.


App open

User opened mobile app.

Properties
PropertyUse CasePath
Push IDOpened app as result of a specific Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDOpened app as result of a specific Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id
Variant IDOpened app as result of a specific A/B test variant./_triggering_push/variant_id
Campaign CategoryOpened app as result of a push with a specific campaign category./_triggering_push/campaigns/categories

activity name: app_open


Message received

User was sent a message by Airship.

Properties
PropertyUse CasePath
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_msg/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_msg/group_id
Variant IDReceived message as a member a specific A/B test variant./_msg/variant_id
Campaign CategoryReceived message from a push with a specific campaign category./_msg/campaigns/categories

activity name: message_received

 Note

Message received events are not available to all customers at this time. Please contact your Airship Account Manager if you are interested in enabling this event.


Message Center read

User viewed Message Center message.

Properties
PropertyUse CasePath
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_msg/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_msg/group_id
Variant IDReceived message as a member a specific A/B test variant./_msg/variant_id
Campaign CategoryReceived message from a push with a specific campaign category./_msg/campaigns/categories

activity name: message_center_read


Message Center delivered

Message Center message was delivered to device.

Properties
PropertyUse CasePath
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_msg/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_msg/group_id
Variant IDReceived message as a member a specific A/B test variant./_msg/variant_id
Campaign CategoryReceived message from a push with a specific campaign category./_msg/campaigns/categories

activity name: message_center_delivered


Message Center deleted

Message Center message was deleted by user.

Properties
PropertyUse CasePath
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_msg/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_msg/group_id
Variant IDReceived message as a member a specific A/B test variant./_msg/variant_id
Campaign CategoryReceived message from a push with a specific campaign category./_msg/campaigns/categories

activity name: message_center_deleted


In-app message display

In-app message was displayed on user’s device.

Properties In-app message events have no properties at this time.

activity name: in_app_message_display


In-app message resolution

In-app message was cleared from the display, either by user action or timeout.

Properties In-app message events have no properties at this time.

activity name: in_app_message_resolution


First seen

An event that occurs when members of your audience opt in to notifications or open your app for the first time.

Properties
PropertyUse CasePath
PlatformTarget users who were first seenA trigger that initiates an automation or journey when members of your audience opt in to notifications or open your app for the first time. on a specific platform in a journey./_msg/platorm

activity name: first_seen


Screen View

User viewed a particular screen in your app.

Properties
PropertyUse CasePath
Viewed screenUser viewed a specific screen in your app, e.g., “Contact us”.viewed_screen

activity name: screen_view


SMS aborted

SMS message was aborted before reaching short message service center.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_aborted


SMS delivered

SMS message was delivered.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_delivered


SMS dispatched

SMS message was dispatched and accepted for delivery by the short message service center.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_dispatched


SMS expired

SMS message expired before delivery to the short message service center.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_expired


SMS failed

SMS message failed to be delivered.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_failed


SMS rejected

SMS message was rejected by short message service center.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_rejected


SMS undeliverable

SMS message could not be delivered.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_undeliverable


SMS unknown

SMS message was delivered to the short message service center, but no delivery receipt has been received or a delivery receipt that could not be interpreted was received.

Properties
PropertyUse CasePath
Vendor Delivery IDReceived SMS from specific vendor.vendorDeliveryId
Sender IDReceived SMS from specific sender.sender
Error codeSMS resulted in specific error code.error_code
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id

activity name: sms_unknown


Email bounce

Email could not be delivered to an address.

Properties
PropertyUse CasePath
SenderReceived email from a specific email address.sender
SubjectReceived email with specific subject.subject
Email addressMessage targeted recipient’s email address.email
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id

activity name: email_bounce


Email click

Recipient clicked a tracked link in a message.

Properties
PropertyUse CasePath
SenderReceived email from a specific email address.sender
SubjectReceived email with specific subject.subject
Link URLUser clicked on a specific email link.link_url
Email addressMessage targeted recipient’s email address.email
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id

activity name: email_click


Email delay

Mailbox provider temporarily rejected an email. In general, this event indicates that the provider will attempt to resend the message.

Properties
PropertyUse CasePath
SenderReceived email from a specific email address.sender
SubjectReceived email with specific subject.subject
Email addressMessage targeted recipient’s email address.email
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id

activity name: email_delay


Email delivered

Remote email server acknowledged receipt of a message.

Properties
PropertyUse CasePath
SenderReceived email from a specific email address.sender
SubjectReceived email with specific subject.subject
Email addressMessage targeted recipient’s email address.email
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id

activity name: email_delivered


Email injection

The email provider received a message that a member of the audience responded to an email.

Properties
PropertyUse CasePath
SenderReceived email from a specific email address.sender
SubjectReceived email with specific subject.subject
Email addressMessage targeted recipient’s email address.email
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id

activity name: email_injection


Email open

Recipient opened an email, rendering a tracking pixel at the bottom of the message.

Properties
PropertyUse CasePath
SenderReceived email from a specific email address.sender
SubjectReceived email with specific subject.subject
Email addressMessage targeted recipient’s email address.email
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id

activity name: email_open


Email unsubscribe

User clicked an unsubscribe link in an email you sent.

Properties
PropertyUse CasePath
UnsubscribeUser unsubscribes via the link that you provided. Note: there is only one unsubscribe event type (link_unsubscribe)unsubscribe_event_type
Push IDReceived a message associated with a Push IDA unique identifier for a push operation. ./_triggering_push/push_id
Group IDReceived message associated with a Group IDA unique identifier for a group of notifications delivered over an interval of time, e.g., multiple push IDs related to an ongoing automation, journey, or a push-to-local-time send. ./_triggering_push/group_id
Campaign CategoryReceived message from a push with a specific campaign category./_triggering_push/campaigns/categories

activity name: email_unsubscribe


Predefined Events and Properties

Below is a list of all available predefined events. Click Properties to see event properties and their type. See Custom Event Templates for SDK implementation details.

Before you can segment on predefined events you must activate them for segmentation in the dashboard. Predefined events are custom events, so you can define additional properties for them if you like, as long as you declare the properties in the SDK.

 Note

Transaction ID is not currently supported with event segmentation for predefined events.


Purchased

Properties
propertytype
categorystring
idstring
descriptionstring
brandstring
new_itemboolean

activity name: purchased


Registered for account

Properties
propertytype
categorystring

activity name: registered_account


Browsed

Properties
propertytype
categorystring
idstring
descriptionstring
brandstring
new_itemboolean

activity name: browsed


Added to cart

Properties
propertytype
categorystring
idstring
descriptionstring
brandstring
new_itemboolean

activity name: added_to_cart


Starred product

Properties
propertytype
categorystring
idstring
descriptionstring
brandstring
new_itemboolean

activity name: starred_product


Shared product

Properties
propertytype
categorystring
idstring
descriptionstring
brandstring
new_itemboolean

activity name: shared_product


Added to wishlist

Properties
propertytype
wishlist_idstring
wishlist_namestring
categorystring
idstring
descriptionstring
brandstring
new_itemboolean

activity name: add_to_wishlist


Removed from wishlist

Properties
propertytype
wishlist_idstring
wishlist_namestring
categorystring
idstring
descriptionstring
brandstring
new_itemboolean

activity name: remove_from_wishlist


Starred content

Properties
propertytype
categorystring
idstring
descriptionstring
typestring
authorstring
featurestring
published_datedate

activity name: starred_content


Shared content

Properties
propertytype
categorystring
idstring
descriptionstring
typestring
authorstring
featurestring
published_datedate

activity name: shared_content


Browsed content

Properties
propertytype
categorystring
idstring
descriptionstring
typestring
authorstring
featurestring
published_datedate

activity name: browsed_content


Consumed content

Properties
propertytype
categorystring
idstring
descriptionstring
typestring
authorstring
featurestring
published_datedate

activity name: consumed_content


Properties
propertytype
typestring
querystring
categorystring
idstring
total_resultsnumber

activity name: search


Logged in

Properties
propertytype
user_idstring
typestring

activity name: logged_in


Logged out

Properties
propertytype
user_idstring
typestring

activity name: logged_out


Custom Event Properties

Click Properties to see event properties, use cases, and paths.


Custom

An event that you define. See: Custom Events.

Properties
PropertyUse CasePath
ValueFilter on custom event value./_value
Custom PropertyFilter on custom event property.[my_property_name]

activity name: custom