1. Home
  2. Guides
  3. Audience & Segmentation
  4. Events
  5. 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 the 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 user-level events in real time to your backend or third-party systems using the Data Streaming API. 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",
         "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",
         "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 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 when building a SegmentA reusable audience group you create by selecting unique or shared user data. or targeting a specific audience:

  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.

Event segmentation

You can target your message and experiment audiences using events. Example audience targeting:

  • Users who opened your app three times in the past seven days
  • Users who opened your app in the past six weeks
  • Users who were sent an SMS six times in the last two weeks
  • Users who made a purchase of more than $100 in the last 15 days
  • Users who have not viewed more than five pieces of content

Using the API, see the Segments endpoint. See also the Event Segmentation schema.

In the dashboard, you can include events when using the Target by conditions and Target specific users audience options for messages and experiments. You can also create SegmentsA reusable audience group you create by selecting unique or shared user data. instead of having to recreate your audience selections. Both use the same process.

Events can be combined with other segmentation data, such as Attributes and Tags. For full instructions and usage locations, see Segments. Details about configuring event conditions, see the next section.

When defining your audience, add each event as a condition, 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.

To configure event conditions:

  1. Select Performed event, First performed event, Last performed event, or Did not perform event.
  2. (For Performed event and Did not perform event only) Select the Equals or Between operator and configure the frequency of the event.
  3. (Optional) Select Specify when to target when the event was performed, then select an operator and configure a date or range. Availability and requirements depend on the operator.
    • Specific — Select a Year/Month/Day. With the Equals operator you can also use formats Month/Day, and Year/Month.
    • Relative — Specify the number of years/months/days/hours/minutes from today’s date. With the Equals operator, also select Month/Day or Year/Month/Day.
    • Today — Select Month/Day or Year/Month/Day.
       Note

      For the Between operator, the end date is not inclusive, e.g., selection Between July 5 - July 17 includes dates July 5 to July 16.

  4. (Optional) Filter events using numeric values associated with the events or by key/value properties attached to the events. Filtering events this way can help you more precisely target your audience.
    1. Select Add Property and search for a property, or select Add Event Value.
    2. If applicable, select the operator you want to use to evaluate the value or property.
    3. Enter a value, then select outside the field or hit Enter on your keyboard to save the value. Repeat for multiple values. Multiple values are evaluated as a boolean OR.
    4. (Optional) Select Add Property or Add Event Value to add more filters.
    5. Select AND/OR to determine how to evaluate multiple filters and alternatives within each filter.
      • AND = all criteria must be met
      • OR = any criteria must be met
         Note

        Properties of type “Array” may have multiple values defined for the same sub-property. When segmenting with array sub-properties that can hold multiple values, be aware that the evaluation of AND and OR conditions can be complex. Ensure your boolean logic precisely matches how you intend to filter based on these potentially multiple values within a single sub-property.

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, “last performed” occurrences are included 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.

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, 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 a condition:

  1. Add the app_open event.
  2. Select Performed event.
  3. Select the Greater than operator and enter the value 0.
  4. Select 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