1. Home
  2. /Guides
  3. /Messaging
  4. /User guide
  5. /Data + Analytics
  6. /Events

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:

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

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.

EventPredefined propertiesEnabled 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.

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@example.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.
    Events

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. 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:

  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