# Real-Time Data Streaming API Airship's Real-Time Data Streaming service exposes an event stream for each user. Events may be behavior-driven, system-driven, or custom. Use its REST API to consume and integrate Airship user event data. # Introduction > Airship's Real-Time Data Streaming API exposes a stream of events describing a user's experience within a mobile app or browser. Events reflect user action, automated device responses to their environment (e.g., encountering a beacon), and experience-changing actions initiated by app/site publishers, such as sending a push notification. To consume the event stream, you must issue an authenticated request including a starting point for the stream and optional filter and subset specifications. The event data is delivered as [newline-delimited JSON](https://github.com/ndjson/ndjson-spec), with each event on its own line. The accept header should be set to `application/vnd.urbanairship+x-ndjson; version=3;`. Each event contains an offset that denotes its location on the stream. If a client disconnects for any reason, it should reconnect with instructions to start at the last offset it successfully processed, to avoid missing any data. For each app key authorized to use Real-Time Data Streaming, Airship stores 7 days or 100 GB worth of data, whichever comes first. ## Base URL {#servers} Select the domain associated with your Airship project. | URL | Description | |-----|-------------| | `https://connect.urbanairship.com` | The North American base URL for Airship's Real-Time Data Streaming API | | `https://connect.asnapieu.com` | The European base URL for Airship's Real-Time Data Streaming API | ## Authentication {#security} ### Basic Auth (Master) {#security-basicAuth} Type: `http` (basic) Authorization header containing the word `Basic` followed by a space and a Base64-encoded string generated from your App Key and Master Secret in `appKey:masterSecret` format. For example, `Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0`. This security type is only accepted by the Compliance endpoint. ### Bearer Token {#security-bearerAuth} Type: `http` (bearer) Authorization header containing the word `Bearer` followed by a space and a bearer token, which can be obtained from Airship [when configuring a direct integration](/docs/guides/reports/real-time-data-streaming/). Tokens can be revoked at will. # Real-Time Data Streaming API Authorization Reference > Find which authentication methods are supported for each Real-Time Data Streaming API endpoint. ## Authorization per authentication method The following table indicates supported authentication methods per endpoint in the [Real-Time Data Streaming API](https://www.airship.com/docs/developer/rest-api/connect/operations/). See the column for each authentication method to understand what access it allows. | Operation | Endpoint | Basic Auth (Master) | Bearer Token | | --- | --- | :---: | :---: | | [Open a compliance event stream](https://www.airship.com/docs/developer/rest-api/connect/operations/compliance-event-stream/#opencomplianceeventstream) | `POST` /api/events/general | ✓ | × | | [Open an event stream](https://www.airship.com/docs/developer/rest-api/connect/operations/event-stream/#openeventstream) | `POST` /api/events | × | ✓ | {class="table-col-2-wrap"} ## Operations API endpoints organized by functionality. Each section groups related operations for managing different aspects of the platform. # Compliance Event Stream > The compliance event stream provides real-time access to `COMPLIANCE` type events. This endpoint is open to all Airship users. ## Open a compliance event stream {#opencomplianceeventstream} Opens a stream delivering events proving data-safety regulation compliance for email and SMS channel-related events (registration, unsubscription, etc.). Unlike a standard event stream, a compliance event stream uses basic authorization, like API calls to `https://go.urbanairship.com/api`. [Jump to examples ↓](#opencomplianceeventstream-examples) ### `POST /api/events/general` **Security:** - [basicAuth]({{< ref "/developer/rest-api/connect/introduction/" >}}#security-basicAuth) **Request headers:** | Name | Type | Required | Description | |------|------|----------|-------------| | `X-UA-Appkey` | `string` | Required | The App Key for the project you want to return compliance events for. | **Request body** **Content-Type:** `application/json` [Compliance request]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#compliancerequest) **Responses** **`200`** The response to a successful request is an unending stream of [newline-delimited JSON](https://github.com/ndjson/ndjson-spec). Each non-empty line in the response represents a single compliance event. Unlike events in a normal event stream, this endpoint returns events of the `compliance` type, and is open to SMS and email customers. As long as the connection is open, Airship will continue to write to the event stream. If a stream records no events for a period of time, the API will write a blank line (a single newline character) to the connection to prevent it from being closed for inactivity. If the `enable_offset_updates` field in the request is `true`, then the blank line is replaced with an `OFFSET_UPDATE` event. These events have no `body` or `device` field, and always have `occurred` and `processed` times indicating when they were sent. The `offset` field will contain the offset of the last event considered for inclusion in the stream whether or not it was actually sent. This may be useful to track position in the stream when using a filter which removes much of it. You should not store these events; they will be different for every connection even if requests are identical. `OFFSET_UPDATE` events are not subject to filters, and are delivered even if not specified in the list of events you want to return. You should always check the type field before handling any delivered event. If you do not receive data or new line characters for ninety seconds, close the connection and reconnect. Response body: **Content-Type:** `application/vnd.urbanairship+x-ndjson; version=3;` **All of:** - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Compliance events are the only types of events returned by this event stream. Possible values: `COMPLIANCE` - `oneOf` **Examples** *Example compliance event stream request* ```http POST /api/events/general HTTP/1.1 Authorization: Basic X-UA-Appkey: Accept: application/vnd.urbanairship+x-ndjson; version=3; Content-Type: application/json { "start":"LATEST", "enable_offset_updates": true } ``` *Response* ```http HTTP/1.1 200 OK Content-encoding: gzip Content-Type: application/vnd.urbanairship+json; version=3; { "id": "9781ff2e-fa4a-4fa8-bd9d-41f318c48963", "offset": "1000001778910", "occurred": "2018-11-28T00:02:41.794Z", "processed": "2018-11-28T00:02:45.270Z", "device": { "channel": "5a39b6d8-0a5a-4c2b-a4a0-3d4a71e5254b", "device_type": "EMAIL", "delivery_address": "bogus@example.com" }, "body": { "event_type": "bounce", "properties": { "bounce_event_type": "bounce", "sender": "msprvs1=17870ayYKWpBI=bounces-179492-4@example.com", "subject": "You there?", "email": "bogus@example.com", "bounce_class": "10" } }, "type": "COMPLIANCE" } ``` --- # Event Stream > Opens an event stream to your filter specifications. ## Open an event stream {#openeventstream} Opens a new event stream according to your request filters. Unlike our other APIs, a request to /api/events/ returns a stream of data, where each line is a JSON object. The response body contains all the events in that stream. Since streams by definition go on forever, Real-Time Data Streaming will never end the response without some external reason. [Jump to examples ↓](#openeventstream-examples) ### `POST /api/events` {{< note >}} In the request specification, JSON collection types have semantic meaning. **array**: Arrays indicate a boolean `"OR"`. Wherever an array appears in the specification, the resulting stream will contain the events passing any of the conditions defined by the array. An empty array results in a `400` response. **object**: Object attributes indicate a boolean `"AND"`. All conditions in the object must be satisfied in order for an event to be written to the response. If you would like all events to pass the condition the attribute defines, omit the attribute. If an unexpected attribute appears on an event, a status code `400` response will be returned. {{< /note >}} {{< important >}} Airship will occasionally add: * New properties to existing objects. * New event types, which will be JSON objects with new values for the type field. Your integration must be tolerant of these kinds of changes. {{< /important >}} **Security:** - [bearerAuth]({{< ref "/developer/rest-api/connect/introduction/" >}}#security-bearerAuth) **Request headers:** | Name | Type | Required | Description | |------|------|----------|-------------| | `X-UA-Appkey` | `string` | Required | The App Key for the project you want to return events for. | **Request body** **Content-Type:** `application/json` [Events request]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#eventsrequest) **Responses** **`200`** The response to a successful request is an unending stream of [newline-delimited JSON](https://github.com/ndjson/ndjson-spec). Each non-empty line in the response represents a single event. This response body is of arbitrarily large size. As long as the connection is open, Airship will continue to write to the data stream. If no events have been dispatched down a connection for some time, the API will write to the connection to prevent it from being closed for inactivity. By default, only a blank line (a single newline character) will be written. If the `enable_offset_updates` field in the request is `true`, then instead of a blank line, an event will be written with type `OFFSET_UPDATE`. These events have no `body` or `device` field, and always have `occurred` and `processed` times indicating when they were sent. The `offset` field will contain the offset of the last event considered for inclusion in the stream whether or not it was actually sent. This may be useful to track position in the stream when using a filter which removes much of it. These events should not be stored, and will be different for every connection even if requests are identical. `OFFSET_UPDATE` events are not subject to filters, and if requested will be delivered regardless of those specified. You should always check the type field before handling any delivered event. If you receive no data or new line characters for ninety seconds, close the connection and reconnect. Response body: **Content-Type:** `application/vnd.urbanairship+x-ndjson; version=3;` **One of:** - [Attribute operation event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#attribute_operation) Attribute operation events indicate a change in the device's attributes. Because attribute operations are related to a device, they will have a `device` field. If you set an attribute on a Named User, Airship records events for each device associated with the Named User. - [Close]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#close) Occurs when a user closes the app. Close events are often latent, as they aren't sent back to Airship until the user activates the app again. - `allOf` Events relating to regulatory compliance for email and SMS channels. - [Contact change]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#contact_change) Occurs when a contact is uninstalled, associated with a channel or Named User, or dissociated from a channel or Named User. - [Control]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#control) Occurs when a device is excluded from a push because it was arbitrarily selected as a member of a control group for a [Message A/B test](/docs/guides/experimentation/a-b-tests/messages/), [Sequence A/B test](/docs/guides/experimentation/a-b-tests/sequences/), or [Holdout Experiment](/docs/guides/experimentation/holdout-experiments/). - [Custom]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#custom) Represents Custom Events that are either emitted from the Airship SDK or submitted through the Custom Events API. You can configure Custom Events yourself. There are also several CUSTOM-type events for email and SMS that are defined by Airship. In general, you can expect device information if the event source is `SDK` or if the event is one of the defined email or SMS events (as defined by `event_type`). - [Feature Flag interaction event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#feature_flag_interaction) Occurs when a user interacts with a tracked flagged feature. See [Feature Flags](/docs/guides/experimentation/feature-flags/#interaction-events). The events have a flag ID and flag name, which identify which flagged feature a user interacted with. They also have a boolean `eligible` field, which indicates whether or not the user was in the Feature Flag audience and had access to the feature. - [First open]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#first_open) This event occurs when a user first registers a channel in your app. This event fires only once per user, when a channel is first registered. Channel registration most commonly occurs immediately after the first app open but can happen at other times as well, for example, if channel registration was delayed. The [open](#open) event fires on every app open, including the first. - [First opt-in]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#first_opt_in) This event appears in the stream when a channel is first opted in. This event is specific to email (commercial), SMS, and open channels. - [In-app button tap]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_button_tap) Occurs when a button is tapped within a Scene. - [In-app experiences]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_experiences) Events that occur related to the display and completion behavior of a Scene. These events are derived from source events generated by the SDK, so a single user action may generate two events: one for the SDK event, one representing the user action as it relates to their actual activity within the app or website. - [In-app form display]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_form_display) Occurs when a survey form in a Scene is displayed. - [In-app form result]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_form_result) Occurs when a survey form in a Scene is submitted. - [In-app message control]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_message_control) Occurs when an In-App Automation or Scene is not delivered because the targeted user's contact or Channel ID was part of a control group for a [Holdout Experiment](/docs/guides/experimentation/holdout-experiments/). - [In-app message display]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_message_display) Occurs when an In-App Automation or Scene is displayed to a user. Because the event pertains to a specific device, the device information object will be populated. - [In-app message exclusion]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_message_exclusion) Occurs when an In-App Automation or Scene is not displayed on a device because the user was banned. See [Ban Lists](/docs/guides/audience/segmentation/ban-lists/). - [In-app message expiration]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_message_expiration) Occurs when a new In-App Automation or Scene message has taken the place of another message, a message has passed its expiration, or because displaying the message in-app would be redundant. This event type may be latent. It is not emitted until the app becomes active. - [In-app message resolution]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_message_resolution) Occurs when an In-App Automation or Scene is cleared from the display, either by user action or timeout. Because this event pertains to an individual device, the device information object will be present. - [In-app page swipe]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_page_swipe) Occurs when a user swipes to the next or previous page (screen) in a pager (specific to Scenes). - [In-app page view]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_page_view) Occurs when a page (screen) is displayed within a pager (specific to Scenes). - [In-app pager completed]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_pager_completed) Occurs when the last page (screen) of a pager is viewed for the first time (specific to Scenes). - [In-app pager summary]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#in_app_pager_summary) Describes the full path a user took within a pager (specific to Scenes), including the order of pages (screens) visited and time spent per page. - [Label event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#label_event) Occurs when you update a Scene screen name. - [Location]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#location) An event declaring the device to be at a particular latitude and longitude. - [Mobile originated event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#mobile_originated) Represents a message action that originated from a user — like an inbound SMS or email. - [Open]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#open) Occurs when a user opens your app. This event fires every time a user opens your app, including the first time. See also the [first open](#first-open) event. - [Push body]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#push_body) Occurs when you initiate a push, automation, or sequence. Airship fulfills delivery over a time interval with a number of child pushes, each with a unique Push ID and a common Group ID. There is no guarantee that push body events (defined in Push Body Event) for the child pushes fulfilling a group will appear in the stream. **Note:** When you start, pause, or publish a sequence, Airship emits a `push_body` event for the sequence itself, and each message contained within the sequence (i.e., messages +1). After you start a sequence, Airship does not issue subsequent `push_body` events for the sequence unless you pause or publish changes to the sequence. - [Region event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#region) Region events are emitted when a device enters or exits a geofence or the range of any of a set of bluetooth beacons. Region events require a Gimbal integration. Events for Gimbal customers include the Gimbal application instance identifier as `com.urbanairship.gimbal.aii` within the `identifiers` object. - [Rich control]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#rich_control) Occurs when a Message Center message is not delivered to a user because they are in a control group for a [Sequence A/B test](/docs/guides/experimentation/a-b-tests/sequences/) or [Holdout Experiment](/docs/guides/experimentation/holdout-experiments/). - [Rich delete]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#rich_delete) Occurs when a user deletes a Message Center message from their inbox. - [Rich delivery]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#rich_delivery) Occurs when a Message Center message is delivered to a user's inbox. Even though rich push deliveries may or may not cause an alert on the user's lock screen, they are always associated with a push identifier in the Airship system. - [Rich read]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#rich_read) Occurs when a user reads a Message Center message in their inbox. - [Screen viewed]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#screen_viewed) Occurs when a user has finished viewing a screen. It is up to you to instrument your application with names for each screen. Doing so will allow you to determine the user's path by filtering on the fields in the table below. - [Send]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#send) Occurs whenever a push notification is sent to a device identified in the audience selector of a message. - [Send aborted]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#send_aborted) Occurs when a push is dropped from our system before delivery is attempted. This can happen: * When using [External Data Feeds](/docs/guides/personalization/sources/external-data-feeds/) to personalize a message and an error was encountered or the feed returned a non-successful response * When a [Message Limit](/docs/guides/messaging/project/config/message-limits/) is met * When a [Ban List](/docs/guides/audience/segmentation/ban-lists/) webhook issues a `drop` response for a user Device information for the device that did not receive the push is included with `SEND_ABORTED` events. - [Send rejected]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#send_rejected) Occurs when a push fails during communication with a third party, like APNs or GCM. This typically indicates that the user has uninstalled the app or otherwise invalidated the last-registered credentials stored in Airship. The event contains the rejected push and the group, variant, or campaigns the push belonged to. Device information for the device that did not receive the push is included with `SEND_REJECTED` events. - [Short link click event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#short_link_click) Occurs when a user taps or "clicks" an Airship-shortened link in an SMS or MMS message. - [Subscription event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#subscription) `SUBSCRIPTION` events reflect changes to users' subscription preferences — reflected in opt_in and opt_out values. These events help you track a user's subscription status in the system and the total number of subscribers. - [Subscription list event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#subscription_list) Occurs when subscription list enrollment changes for a device or user. - [Tag change]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#tag_change) Occurs when tags change for a device. - [Uninstall]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#uninstall) Occurs when a user uninstalls an Airship-integrated app in response to a push. - [Web click event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#web_click) Occurs when a user interacts with a web notification, e.g., clicked or tapped it. Web Click events have a device attribute on the event indicating the channel that was the target of the notification. The body of a Web Click Event is an associated push object. - [Web session event]({{< ref "/developer/rest-api/connect/schemas/events/" >}}#web_session) Occurs when an opted in user begins interacting with a website. Web Session events have a device attribute, indicating the channel associated with the user. **`402`** Like other Airship applications, Real-Time Data Streaming supports a limited number of simultaneous connections. If you exceed this number, you may receive this response. **`404`** We do not have data for the specified App key. This is likely because we have yet to ingress or generate any data for your app. **Examples** *Example event stream request* ```http POST /api/events HTTP/1.1 Authorization: Bearer X-UA-Appkey: Accept: application/vnd.urbanairship+x-ndjson; version=3; Content-Type: application/json { "filters": [ { "device_types": [ "android", "amazon" ], "devices": [ { "channel": "5b389366-7caf-43e2-a19c-6159c7ea9936" }, { "channel": "c8044c8a-d5fa-4e58-91d4-54d0f70b7409" }, { "named_user_id": "George" } ], "latency": 20000000 }, { "notifications": [ { "group_id": "a30abf06-7878-4096-9535-b50ac0ad6e8e" } ], "types": [ "OPEN" ] } ], "resume_offset": "MTAwMDAwMDAyMjg1NA", "subset": { "proportion": 0.3, "type": "SAMPLE" } } ``` *Response* ```http HTTP/1.1 200 OK Content-encoding: gzip Content-Type: application/vnd.urbanairship+json; version=3; {"id" : "ff76bb85-74bc-4511-a3bf-11b6117784db", "type": "UNINSTALL", "offset": "MTIzNQ", "occurred": "2015-05-03T02:32:12.088Z", "processed": "2015-05-03T12:12:43.180Z", "device": {"channel":"a61448e1-be63-43ee-84eb-19446ba743f0", "device_type":"ANDROID", "android_channel": "a61448e1-be63-43ee-84eb-19446ba743f0"}} {"id" : "8e50350e-dd9f-41af-b98e-b0e5d4b27dea","type": "SEND","offset": "NTIxMDM1","occurred": "2015-05-02T02:31:22.088Z","processed": "2015-05-02T02:32:43.181Z","device": {"channel":"5117f2a7-ba58-4981-9456-169959511d1a", "device_type":"IOS", "ios_channel": "5117f2a7-ba58-4981-9456-169959511d1a" },"body": {"push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e", "alerting": true}} {"id" : "ff76bb85-74bc-4511-a3bf-11b6117784db", "type": "UNINSTALL", "offset": "MTIzNQ", "occurred": "2015-05-03T02:32:12.088Z", "processed": "2015-05-03T12:12:43.180Z", "device": {"channel":"a61448e1-be63-43ee-84eb-19446ba743f0", "device_type":"ANDROID", "android_channel": "a61448e1-be63-43ee-84eb-19446ba743f0"}} {"device":{"channel":"820e4493-e4c9-4577-99bc-a98180599f73","delivery_address":"new.user@urbanairship.com","device_type":"EMAIL"},"id":"00000169-4a14-67b2-1ddd-d9e733622c3a","occurred":"2019-03-04T19:00:45.106Z","offset":"1000001260057","processed":"2019-03-04T19:00:47.094Z","type":"FIRST_OPT_IN"} ``` *Response object* ```json { "id": "8e50350e-dd9f-41af-b98e-b0e5d4b27dea", "type": "SEND", "offset": "NTIxMDM1", "occurred": "2015-05-02T02:31:22.088Z", "processed": "2015-05-02T02:32:43.181Z", "device": { "channel": "5117f2a7-ba58-4981-9456-169959511d1a", "device_type": "IOS" }, "body": { "push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e", "alerting": true } } { "device": { "channel": "820e4493-e4c9-4577-99bc-a98180599f73", "delivery_address": "new.user@urbanairship.com", "device_type": "EMAIL" }, "id": "00000169-4a14-67b2-1ddd-d9e733622c3a", "occurred": "2019-03-04T19:00:45.106Z", "offset": "1000001260057", "processed": "2019-03-04T19:00:47.094Z", "type": "FIRST_OPT_IN" } ``` --- ## Data Formats JSON schemas for API requests and responses. Schemas define the structure, types, and validation rules for data exchanged with the API. # Custom email events > Airship delivers email messages through a provider (SparkPost). Custom email events represent events that occur at the provider level — outside Airship, between the provider and recipient. ## Email bounce event {#emailbounceevent} Occurs when an email could not be delivered to an address. The `bounce_class` provides additional information about the reason your message bounced. This event occurs in conjunction with a similar `COMPLIANCE` event. [Jump to examples ↓](#emailbounceevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `bounce` - **`properties`** `object` **REQUIRED** **All of:** - - **`email`** `string` The recipient's email address. - **`sender`** `string` The sender of the email specified by the event. - **`subject`** `string` The subject line of the email specified by the event. - - **`bounce_class`** `string` A number between 1 and 100 that represents the specific reason the email bounced. Format: `(100)|[1-9]\d?` - **`bounce_event_type`** `string` Possible values: `bounce` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email bounce Custom Event* ```json { "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e", "offset": "1000001778145", "occurred": "2019-02-27T23:20:14.000Z", "processed": "2019-02-27T23:20:49.347Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.subscriber@example.com" }, "body": { "name": "bounce", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99", "campaigns": { "categories": [ "new", "Baseball Fan" ] } }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "sender": "baseball@example.com", "subject": "Baseball Season is Almost Here!", "email": "new.subscriber@example.com", "bounce_event_type": "bounce", "bounce_class": "10", } }, "type": "CUSTOM" } ``` --- ## Email click event {#emailclickevent} Occurs when a recipient clicks a tracked link in a message. Tracked links are redirected through the provider's click-tracking server to record the event. Only HTTP and HTTPS links are tracked. Unsubscribe link clicks do not trigger this event. [Jump to examples ↓](#emailclickevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `click` - **`properties`** `object` **REQUIRED** **All of:** - - **`email`** `string` The recipient's email address. - **`sender`** `string` The sender of the email specified by the event. - **`subject`** `string` The subject line of the email specified by the event. - - **`link_name`** `string` The [name of the link](/docs/guides/messaging/messages/content/email/email/#link-names), if set. - **`link_url`** `string` The URL of the link that the user clicked. - - **`agent_family`** `string` The name of the family of user agent software used to access the email, e.g., WebKit - **`device_brand`** `string` The brand of the device that was used to access the user agent software, e.g., Samsung or Apple. - **`device_family`** `string` The name of the device used to access the user agent software. - **`is_mobile`** `boolean` Indicates whether or not the user agent is from a mobile device. - **`is_prefetched`** `boolean` Indicates if this event was likely prefetched, for example through Apple MPP. This field does not apply to clicks. The value returned in click events is always false. - **`os_family`** `string` The name of the operating system used to access the user agent software. - **`os_version`** `string` The version of the operating system used to access the user agent software. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email click Custom Event* ```json { "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e", "offset": "1000001778145", "occurred": "2019-02-27T23:20:14.000Z", "processed": "2019-02-27T23:20:49.347Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.subscriber@example.com" }, "body": { "name": "click", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99", "campaigns": { "categories": [ "new", "Baseball Fan" ] } }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "sender": "baseball@example.com", "subject": "Baseball Season is Almost Here!", "email": "new.subscriber@example.com", "link_name": "Homepage", "link_url": "https://www.example.com", "os_family": "Android", "is_mobile": "true", "device_brand": "Motorola", "os_version": "11", "device_family": "moto g stylus", "is_prefetched": "false", "agent_family": "Chrome" } }, "type": "CUSTOM" } ``` --- ## Email delay event {#emaildelayevent} Occurs when a mailbox provider temporarily rejects an email. In general, this event indicates that the provider will attempt to resend the message. [Jump to examples ↓](#emaildelayevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `delay` - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`email`** `string` The recipient's email address. - **`sender`** `string` The sender of the email specified by the event. - **`subject`** `string` The subject line of the email specified by the event. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email delay Custom Event* ```json { "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e", "offset": "1000001778145", "occurred": "2019-02-27T23:20:14.000Z", "processed": "2019-02-27T23:20:49.347Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "addressResponding4xx@example.com" }, "body": { "name": "delay", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99", "campaigns": { "categories": [ "new", "Baseball Fan" ] } }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "sender": "baseball@example.com", "subject": "Baseball Season is Almost Here!", "email": "addressResponding4xx@example.com" } }, "type": "CUSTOM" } ``` --- ## Email delivery event {#emaildeliveryevent} Occurs when the remote MTA (email server) acknowledges receipt of a message. [Jump to examples ↓](#emaildeliveryevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `delivery` - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`email`** `string` The recipient's email address. - **`sender`** `string` The sender of the email specified by the event. - **`subject`** `string` The subject line of the email specified by the event. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email delivery Custom Event* ```json { "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e", "offset": "1000001778145", "occurred": "2019-02-27T23:20:14.000Z", "processed": "2019-02-27T23:20:49.347Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.subscriber@example.com" }, "body": { "name": "delivery", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99", "campaigns": { "categories": [ "new", "Baseball Fan" ] } }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "sender": "baseball@example.com", "subject": "Baseball Season is Almost Here!", "email": "new.subscriber@example.com" } }, "type": "CUSTOM" } ``` --- ## Email initial open event {#emailinitialopenevent} Occurs when a recipient opens an email, rendering a tracking pixel at the top of the email. {{< note >}} This event requires images to load in the email client. If a user blocks images in their email client, Airship will not register this event. {{< /note >}} [Jump to examples ↓](#emailinitialopenevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `initial_open` - **`properties`** `object` **REQUIRED** **All of:** - - **`email`** `string` The recipient's email address. - **`sender`** `string` The sender of the email specified by the event. - **`subject`** `string` The subject line of the email specified by the event. - - **`agent_family`** `string` The name of the family of user agent software used to access the email, e.g., WebKit - **`device_brand`** `string` The brand of the device that was used to access the user agent software, e.g., Samsung or Apple. - **`device_family`** `string` The name of the device used to access the user agent software. - **`is_mobile`** `boolean` Indicates whether or not the user agent is from a mobile device. - **`is_prefetched`** `boolean` Indicates if this event was likely prefetched, for example through Apple MPP. This field does not apply to clicks. The value returned in click events is always false. - **`os_family`** `string` The name of the operating system used to access the user agent software. - **`os_version`** `string` The version of the operating system used to access the user agent software. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email initial_open Custom Event* ```json { "id": "544da998-9338-4506-8564-8adf7b2597cf", "offset": "1000032367699", "occurred": "2020-07-29T20:26:03.000Z", "processed": "2020-07-29T20:27:47.780Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.subscriber@example.com", "named_user_id": "a_person" }, "body": { "name": "initial_open", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99" }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "sender": "baseball@example.com", "subject": "Baseball Season is Almost Here!", "email": "new.subscriber@example.com", "os_family": "Android", "is_mobile": "true", "device_brand": "Motorola", "os_version": "11", "device_family": "moto g stylus", "is_prefetched": "false", "agent_family": "Chrome" } }, "type": "CUSTOM" } ``` --- ## Email injection event {#emailinjectionevent} This event occurs when the provider (SparkPost) receives a message — typically when a member of the audience responds to an email. [Jump to examples ↓](#emailinjectionevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `injection` - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`email`** `string` The recipient's email address. - **`sender`** `string` The sender of the email specified by the event. - **`subject`** `string` The subject line of the email specified by the event. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email injection Custom Event* ```json { "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e", "offset": "1000001778145", "occurred": "2019-02-27T23:20:14.000Z", "processed": "2019-02-27T23:20:49.347Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.subscriber@example.com" }, "body": { "name": "injection", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99", "campaigns": { "categories": [ "new", "Baseball Fan" ] } }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "sender": "baseball@example.com", "subject": "Baseball Season is Almost Here!", "email": "new.subscriber@example.com" } }, "type": "CUSTOM" } ``` --- ## Email open event {#emailopenevent} Occurs when a recipient opens an email, rendering a tracking pixel at the bottom of the message. If a message is truncated by a client or email provider, a user may have to open it in a separate window to render the tracking pixel (and register this event). {{< note >}} This event requires images to load in the email client. If a user blocks images in their email client, Airship will not register this event. {{< /note >}} [Jump to examples ↓](#emailopenevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `open` - **`properties`** `object` **REQUIRED** **All of:** - - **`email`** `string` The recipient's email address. - **`sender`** `string` The sender of the email specified by the event. - **`subject`** `string` The subject line of the email specified by the event. - - **`agent_family`** `string` The name of the family of user agent software used to access the email, e.g., WebKit - **`device_brand`** `string` The brand of the device that was used to access the user agent software, e.g., Samsung or Apple. - **`device_family`** `string` The name of the device used to access the user agent software. - **`is_mobile`** `boolean` Indicates whether or not the user agent is from a mobile device. - **`is_prefetched`** `boolean` Indicates if this event was likely prefetched, for example through Apple MPP. This field does not apply to clicks. The value returned in click events is always false. - **`os_family`** `string` The name of the operating system used to access the user agent software. - **`os_version`** `string` The version of the operating system used to access the user agent software. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email open Custom Event* ```json { "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e", "offset": "1000001778145", "occurred": "2019-02-27T23:20:14.000Z", "processed": "2019-02-27T23:20:49.347Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.subscriber@example.com" }, "body": { "name": "open", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99", "campaigns": { "categories": [ "new", "Baseball Fan" ] } }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "sender": "baseball@example.com", "subject": "Baseball Season is Almost Here!", "email": "new.subscriber@example.com", "os_family": "Android", "is_mobile": "true", "device_brand": "Motorola", "os_version": "11", "device_family": "moto g stylus", "is_prefetched": "false", "agent_family": "Chrome" } }, "type": "CUSTOM" } ``` --- ## Email unsubscribe link event {#emailunsubscribelinkevent} Occurs when a user clicks an unsubscribe link in an email you sent. [Jump to examples ↓](#emailunsubscribelinkevent-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`name`** `string` **REQUIRED** Possible values: `unsubscribe` - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`unsubscribe_event_type`** `string` Possible values: `link_unsubscribe` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email unsubscribe link Custom Event* ```json { "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e", "offset": "1000001778145", "occurred": "2019-02-27T23:20:14.000Z", "processed": "2019-02-27T23:20:49.347Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.subscriber@example.com" }, "body": { "name": "unsubscribe", "triggering_push": { "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99", "campaigns": { "categories": [ "new", "Baseball Fan" ] } }, "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9", "source": "API", "properties": { "unsubscribe_event_type": "link_unsubscribe" } }, "type": "CUSTOM" } ``` --- # Custom SMS events > Airship delivers SMS messages through service providers Sinch (formerly known as CLX) and Twilio. Custom SMS events represent events that occur between the service provider and recipient. They do not represent Airship service events. ## RCS read report {#rcs-read-report} Read reports are Custom Events sent when an RCS message is marked as read. These events use the `delivery_report` interaction type with a `name` of `read`. See [RCS branded senders](/docs/developer/api-integrations/sms/rcs/). - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`interaction_type`** `string` Possible values: `delivery_report` - **`name`** `string` **REQUIRED** Indicates the event is an RCS read. Possible values: `read` - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`is_rcs`** `boolean` A boolean describing whether the message was delivered as RCS. - **`number_of_message_parts`** `number` The number of message parts delivered. - **`recipient_country_code`** `string` The country code of the message recipient. - **`sender`** `string` **REQUIRED** The number or short code that the message originated from. - **`vendor`** `string` **REQUIRED** The delivery service for the message. Possible values: `CLX`, `TWILIO` - **`vendorDeliveryId`** `string` **REQUIRED** A unique identifier for the message from the SMS vendor. - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` Identifies the push notification that caused the event. **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`device`** `object` **REQUIRED** Device properties for Custom Events with the `delivery_report` interaction type always specify an SMS device. **OBJECT PROPERTIES** - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The phone number associated with the channel. - **`device_type`** `string` **REQUIRED** Possible values: `SMS` - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `CUSTOM` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- ## SMS delivery report {#delivery-report} Delivery reports are Custom Events sent from our third-party SMS providers. These events report the status of your message between the provider and your audience up to, and including, delivery. [Jump to examples ↓](#delivery-report-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`interaction_type`** `string` Possible values: `delivery_report` - **`name`** `string` **REQUIRED** The name of the delivery report as specified by the vendor. Most events reference the status of the message with reference to the short message service center (SMSC) — the server that receives your message and dispatches it to your audience. * dispatched — Message has been dispatched and accepted for delivery by the SMSC. * aborted — Message was aborted before reaching SMSC. * rejected — Message was rejected by SMSC. * delivered — Message has been delivered. * failed — Message failed to be delivered. * expired — Message expired before delivery to SMSC. This may happen if the expiry time for the message was very short. * unknown — Message was delivered to SMSC but no Delivery Receipt has been received or a Delivery Receipt that could not be interpreted was received. * undeliverable — Message cannot be delivered. * deleted — Message has been deleted. Possible values: `dispatched`, `aborted`, `rejected`, `delivered`, `failed`, `expired`, `unknown`, `undeliverable`, `deleted` - **`properties`** `object` **REQUIRED** **One of:** - **SMS Delivery Properties** `object` A delivery report for SMS. - **`error_code`** `string` An error code from the short message service center, if applicable. - **`is_rcs`** `boolean` A boolean describing if the message was delivered as RCS or not. - **`sender`** `string` **REQUIRED** The number or short code that the message originated from. - **`vendor`** `string` **REQUIRED** The delivery service for the message. Possible values: `CLX`, `TWILIO` - **`vendorDeliveryId`** `string` **REQUIRED** A unique identifier for the message from the SMS vendor. - **MMS Delivery Properties** `object` A delivery report for MMS. - **`carrier_id`** `string` Identifies the carrier the message was sent through. - **`error_code`** `string` An error code from the short message service center, if applicable. - **`handset`** `string` The profile of the handset that received the message. This information is only present if the `result_status` is `N102`. - **`is_rcs`** `boolean` A boolean describing if the message was delivered as RCS or not. - **`result_code`** `string` **REQUIRED** A status code from the vendor, if applicable. Possible values: `N101`, `N102`, `E101`, `E102` - **`result_status`** `string` Possible values: `Message Sent`, `Message Sent/Delivered`, `Message Failed`, `Message,Sent/Expired`, `Message Sent/Rejected`, `Message Sent/Failed`, `Message Sent/Not Supported` - **`sender`** `string` **REQUIRED** The number or short code that the message originated from. - **`sent_as`** `string` Indicates whether the MMS was delivered as MMS (binary) or SMS (HTML). Possible values: `MMS`, `SMS` - **`tracking_Id`** `string` An ID assigned by the delivery service (CLX only). - **`vendor`** `string` **REQUIRED** The delivery service for the message. Possible values: `CLX` - **`source`** `string` **REQUIRED** Possible values: `API` - **`triggering_push`** `object` Identifies the push notification that caused the event. **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` **REQUIRED** Device properties for Custom Events with the `delivery_report` interaction type always specify an SMS device. **OBJECT PROPERTIES** - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The phone number associated with the channel. - **`device_type`** `string` **REQUIRED** Possible values: `SMS` - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `CUSTOM` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS delivery report Custom Event* ```json { "body": { "interaction_type": "delivery_report", "name": "dispatched", "properties": { "sender": 15551234567, "vendor": "CLX", "vendorDeliveryId": "FENhObMKbCjMOwtw" }, "source": "API", "triggering_push": { "campaigns": { "categories": [ "New Users" ] }, "push_id": "9323b708-7741-4a85-8b1b-e55ad8ce64fc" } }, "device": { "channel": "db7576c7-6b3d-4f07-b13a-ea3824fea262", "delivery_address": "15558675309", "device_type": "SMS" }, "id": "48af12e8-6920-4e4e-bef8-b5a6918eec35", "occurred": "2019-01-31T17:45:38.700Z", "offset": "1000002098217", "processed": "2019-01-31T17:45:41.285Z", "type": "CUSTOM" } ``` --- # Device information > Events are ascribed to devices. App, web, SMS, email, and open channel `devices` return different information. ## App device information {#appdevices} Information about app users generated by the SDK. [Jump to examples ↓](#appdevices-examples) - **`amazon_channel`** `string` The identifier for a Fire OS channel. In general, this is also the same value as the `channel`. - **`android_channel`** `string` The identifier for an Android channel. In general, this is also the same value as the `channel`. - **`attributes`** `object` Attributes specific to app devices. **OBJECT PROPERTIES** - **`app_package_name`** `string` A unique identifier for the app name. - **`app_version`** `string` The version of the app. - **`background_push_enabled`** `string` Indicates whether or not the device has background push notifications enabled. Possible values: `true`, `false` - **`device_model`** `string` The device model. - **`device_os`** `string` The device operating system. - **`iana_timezone`** `string` The time zone of the device. - **`locale_country_code`** `string` The ISO 3166-1 country code as defined in device settings. - **`locale_language_code`** `string` The ISO 639-1 two-letter language code reflecting the language that the device is set to. - **`locale_timezone`** `string` The device's time zone offset in seconds from UTC. - **`locale_variant`** `string` The language variant. - **`location_enabled`** `string` Indicates whether or not the device has location services enabled. Possible values: `true`, `false` - **`location_permission`** `string` * `SYSTEM_LOCATION_DISABLED` Location is disabled in system settings * `NOT_ALLOWED` Android: missing manifest permissions, iOS: opted out * `ALWAYS_ALLOWED` Android: has manifest permissions, iOS: opted in background and foreground * `FOREGROUND_ALLOWED` iOS only: opted in foreground only * `UNPROMPTED`: iOS only Possible values: `SYSTEM_LOCATION_DISABLED`, `NOT_ALLOWED`, `ALWAYS_ALLOWED`, `FOREGROUND_ALLOWED`, `UNPROMPTED` - **`push_opt_in`** `string` Indicates whether or not the device is opted into push notifications. - **`ua_sdk_version`** `string` The version of the Airship SDK used in the app. - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`device_type`** `string` **REQUIRED** The platform that the channel is on. Possible values: `IOS`, `ANDROID`, `AMAZON` - **`identifiers`** `object` Identifying information specific to app devices. **OBJECT PROPERTIES** - **`com.urbanairship.aaid`** `string` Android/Fire OS ad identifier Format: `uuid` - **`com.urbanairship.gimbal.aii`** `string` Gimbal application instance identifier Format: `uuid` - **`com.urbanairship.idfa`** `string` Apple ad identifier Format: `uuid` - **`com.urbanairship.limited_ad_tracking_enabled`** `string` If true, the user has enabled limited ad tracking. Possible values: `true`, `false` - **`com.urbanairship.vendor`** `string` Apple vendor identifier Format: `uuid` - **`ios_channel`** `string` The identifier for an iOS channel. In general, this is also the same value as the `channel`. - **`named_user_id`** `string` The Named User identifier for the device. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example device information object* ```json { "channel": "a6b392d6-3b0d-4c00-98ef-5cb91d51268a", "device_type": "IOS", "named_user_id": "Albert", "identifiers": { "com.urbanairship.idfa": "fb0d01e0-9e21-4466-9217-8eacfd2b81c7", "com.urbanairship.gimbal.aii": "c5720f06-516a-4b91-b7bb-53523fc43a3d", "com.urbanairship.limited_ad_tracking_enabled": "false" }, "attributes": { "app_package_name": "com.company_name.app_name", "app_version": "1.0.0", "ua_sdk_version": "7.0.2" } } ``` --- ## Device information for SMS and email {#sms-email-devices} Information about the SMS or email device related to an event. - **`channel`** `string` **REQUIRED** The channel identifier. - **`delivery_address`** `string` * If `device_type` is `SMS`, this field shows the MSISDN. * If `device_type` is `EMAIL`, this field shows the email address. - **`device_type`** `string` **REQUIRED** The platform that the channel is on. Possible values: `EMAIL`, `SMS` - **`named_user_id`** `string` The Named User the channel is associated with. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- ## Named User {#nameduser} User information for events which occur at the user level. - **`named_user_id`** `string` **REQUIRED** The Named User identifier for the device. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- ## Open channel device information {#opendevices} Information about open channel users. - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`device_type`** `string` The platform that the channel is on. Possible values: `OPEN` - **`named_user_id`** `string` The Named User identifier for the device. - **`open_platform_name`** `string` If `device_type` is set to `OPEN`, this field shows the full name of the platform. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- ## Web device information {#webdevices} Information about web users generated by the SDK. - **`attributes`** `object` **OBJECT PROPERTIES** - **`iana_timezone`** `string` The time zone of the device. - **`locale_country_code`** `string` The ISO 3166-1 country code as defined in device settings. - **`locale_language_code`** `string` The ISO 639-1 two-letter language code reflecting the language that the device is set to. - **`locale_timezone`** `string` The device's time zone offset in seconds from UTC. - **`locale_variant`** `string` The language variant. - **`push_opt_in`** `string` **REQUIRED** Indicates whether or not the device is opted into push notifications. - **`ua_sdk_version`** `string` **REQUIRED** The version of the Airship SDK used in the app. - **`web_browser_name`** `string` **REQUIRED** The name of the browser running the SDK. - **`web_browser_type`** `string` **REQUIRED** Indicates whether the browser was running on a desktop or mobile device. - **`web_browser_version`** `string` **REQUIRED** The version of the browser. - **`web_user_agent_string`** `string` **REQUIRED** The user agent reported by the browser. - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`device_type`** `string` **REQUIRED** The platform that the channel is on. Possible values: `WEB` - **`named_user_id`** `string` The Named User identifier for the device. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- # Email compliance events > Contains event body information specific to email compliance events. ## Email bounce event {#bounce} An event that occurs when an email could not be delivered to a particular address. The `bounce_class` can provide more information about why the message bounced. [Jump to examples ↓](#bounce-examples) - **`body`** `object` **REQUIRED** Contains the event subtype and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Possible values: `bounce` - **`identifiers`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`address`** `string` The email address registered. - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`bounce_class`** `integer` The bounce classification as specified in SparkPost. Min: 1, Max: 100 - **`bounce_event_type`** `string` Possible values: `bounce` - **`email`** `string` The email address that bounced. Format: `email` - **`sender`** `string` The address that the bounced email came from (typically the sender address for your project in Airship). - **`subject`** `string` The subject line of the bounced email. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email bounce event* ```json { "id": "9781ff2e-fa4a-4fa8-bd9d-41f318c48963", "offset": "1000001778910", "occurred": "2018-11-28T00:02:41.794Z", "processed": "2018-11-28T00:02:45.270Z", "device": { "channel": "5a39b6d8-0a5a-4c2b-a4a0-3d4a71e5254b", "device_type": "EMAIL", "delivery_address": "bademail@example.com" }, "body": { "event_type": "bounce", "properties": { "bounce_event_type": "bounce", "sender": "msprvs1=17870ayYKWpBI=bounces-179492-4@example.com", "subject": "Red Means Go", "email": "bademail@example.com", "bounce_class": "10" } }, "type": "COMPLIANCE" } ``` --- ## Email Create and Send event {#emailcreateandsend} An event that occurs for email addresses used as a part of a [Create and Send](/docs/guides/audience/segmentation/bulk-sending/). [Jump to examples ↓](#emailcreateandsend-examples) - **`body`** `object` **REQUIRED** Contains the event subtype and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Possible values: `create_and_send` - **`identifiers`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`address`** `string` **REQUIRED** The email address a message was sent to using Create and Send. - **`properties`** `object` **REQUIRED** Properties for an email [Create and Send](/docs/guides/audience/segmentation/bulk-sending/) event. **OBJECT PROPERTIES** - **`channel_registered`** `boolean` **REQUIRED** If true, a new channel was created to represent the identifiers in the event. If false, the address was already registered to Airship. - **`commercial_opted_in`** `string` The date and time when the `address` opted into commercial email messages. - **`transactional_opted_in`** `string` The date and time when the `address` opted into transactional email messages. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email Create and Send event* ```json { "id": "adf8794c-c3c3-4507-9ea3-1a554ed4b94f", "offset": "1000001778141", "occurred": "2018-11-27T23:20:12.167Z", "processed": "2018-11-27T23:20:12.443Z", "device": { "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d", "device_type": "EMAIL", "delivery_address": "new.address@example.com" }, "body": { "event_type": "create_and_send", "identifiers": { "address": "new.address@example.com" }, "properties": { "channel_registered": "true", "commercial_opted_in": "2018-10-12T12:12:12" } }, "type": "COMPLIANCE" } ``` --- ## Email registration event {#registration} An event that occurs when users register to receive email messages. [Jump to examples ↓](#registration-examples) - **`body`** `object` **REQUIRED** Contains the event subtype and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Possible values: `registration` - **`identifiers`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`address`** `string` The email address registered. - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`commercial_opted_in`** `string` The date and time when the user opted into commercial email messages. - **`registration_type`** `string` **REQUIRED** `create` indicates that a channel was created in Airship. `update` represents a `PUT` call to the email channel registration API. Possible values: `create`, `unbounce`, `update`, `opt_in`, `unsubscribe` - **`source`** `string` Only appears when [suppression is removed from an email channel using the dashboard Contact Management tool](/docs/guides/audience/contact-management/#removing-email-suppression). Possible values: `ui` - **`suppression_state`** `string` The suppression state of the email address. Possible values: `imported`, `spam_complaint`, `commercial_spam_complaint`, `out_of_band`, `bounce`, `none` - **`user`** `string` The username of the Airship dashboard user that [removed suppression from an email channel using the dashboard Contact Management tool](/docs/guides/audience/contact-management/#removing-email-suppression) and acknowledged the compliance implications. - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email registration event* ```json { "id": "8058bfd3-9081-4f48-845c-809bf5462ca4", "offset": "1000000739139", "occurred": "2018-12-18T21:24:11.836Z", "processed": "2018-12-18T21:24:12.608Z", "device": { "channel": "93f32fb8-0e40-440b-8944-2f9ef933ca88", "device_type": "EMAIL" }, "body": { "event_type": "registration", "identifiers": { "address": "new.user@example.com" }, "properties": { "commercial_opted_in": "2018-10-20T12:00:00.000Z", "registration_type": "create" } }, "type": "COMPLIANCE" } ``` *Example email suppression removal event* ```json { "id": "d7ece0e7-b160-49ff-974d-2fd4dd5b34fd", "offset": "1000000287040", "occurred": "2026-03-12T19:45:00.620Z", "processed": "2026-03-12T19:45:02.065Z", "device": { "channel": "e839cdb5-4b79-4652-ab94-b1ac84294f3f", "device_type": "EMAIL", "delivery_address": "some.user@example.com" }, "body": { "event_type": "registration", "identifiers": { "address": "some.user@example.com" }, "properties": { "suppression_state": "none", "source": "ui", "user": "some_user", "registration_type": "unbounce" } }, "type": "COMPLIANCE" } ``` --- ## Email unsubscribe event {#unsubscribe} A compliance event representing a user who unsubscribed from your email notifications. [Jump to examples ↓](#unsubscribe-examples) - **`body`** `object` **REQUIRED** Contains the event subtype and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Unsubscribe events are considered `registration` events; the `registration_type` indicates the type of registration occurring. Possible values: `registration` - **`identifiers`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`address`** `string` The email address registered. - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`message_type`** `string` **REQUIRED** The message type that the user unsubscribed from. Possible values: `commercial` - **`registration_type`** `string` **REQUIRED** Possible values: `unsubscribe` - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example email unsubscribe event* ```json { "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" } ``` --- # Events > Contains information about events organized by `type`. Some events contain additional subtypes or device information. ## Attribute operation event {#attribute-operation} Attribute operation events indicate a change in the device's attributes. Because attribute operations are related to a device, they will have a `device` field. If you set an attribute on a Named User, Airship records events for each device associated with the Named User. [Jump to examples ↓](#attribute-operation-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`remove`** `array[object]` The attributes removed from the `device` in this event. Min items: 1 - **`set`** `array[object]` Min items: 1 - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - [Web device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#webdevices) Information about web users generated by the SDK. - [Device information for SMS and email]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#sms_email_devices) Information about the SMS or email device related to an event. - [Open channel device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#opendevices) Information about open channel users. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `ATTRIBUTE_OPERATION` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example Attribute operation event* ```json { "id": "00000173-bb88-8804-b6ec-a40f4ae36648", "offset": "1000059326194", "occurred": "2020-08-04T22:12:33.924Z", "processed": "2020-08-04T22:12:37.672Z", "device": { "android_channel": "b57f0e3c-da10-4a2b-99d2-5fe2cb30cad3", "channel": "b57f0e3c-da10-4a2b-99d2-5fe2cb30cad3", "device_type": "ANDROID", "named_user_id": "cool_user", "attributes": { "locale_variant": "", "app_version": "2020-02-10T222436-staging", "device_model": "Pixel 2 XL", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "10", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "12.2.0", "location_permission": "NOT_ALLOWED" } }, "user": { "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "cool_user" }, "body": { "set": [ { "key": "first_name", "value": "Pierre" } ] }, "type": "ATTRIBUTE_OPERATION" } ``` --- ## Close {#close} Occurs when a user closes the app. Close events are often latent, as they aren't sent back to Airship until the user activates the app again. [Jump to examples ↓](#close-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `CLOSE` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example close event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "user": { "contact_id": "982B35f2-0375-6384-893e-a19b5cd5R771" }, "body": { "session_id": "61acb6c9-527b-4632-b789-a3e6085b094e" }, "type": "CLOSE" } ``` --- ## Contact change {#contact-change} Occurs when a contact is uninstalled, associated with a channel or Named User, or dissociated from a channel or Named User. [Jump to examples ↓](#contact-change-examples) - **`body`** `object` **OBJECT PROPERTIES** - **`change_type`** `string` Describes the reason the contact change event was emitted. * `ASSOCIATION`: The contact was associated to a channel or Named User. * `DISSOCIATION`: The contact was dissociated from a channel or Named User. * `UNINSTALL`: The contact was uninstalled. Possible values: `ASSOCIATION`, `DISSOCIATION`, `UNINSTALL` - **`channel_id`** `string` The ID of the channel that was associated or dissociated from the contact, depending on the change event type. - **`contact_id`** `string` The ID of the contact related to the change event. - **`named_user_id`** `string` An optional string that represents the Named User ID related to the change event. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> Information about app users generated by the SDK. - **`id`** `string` Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` Possible values: `CONTACT_CHANGE` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example contact change event* ```json { "id": "fe882bd1-e0b9-11ea-bc35-0242f70dd9ff", "offset": "1000076075647", "occurred": "2024-09-25T19:03:13.903Z", "processed": "2024-09-25T19:03:14.426Z", "user": { "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "mini_me" }, "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS" }, "body": { "change_type": "DISSOCIATION", "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "mini_me", "channel_id": "1ef235f0-03d5-1384-893e-a19b5cd0d110", }, "type": "CONTACT_CHANGE" } ``` --- ## Control {#control} Occurs when a device is excluded from a push because it was arbitrarily selected as a member of a control group for a [Message A/B test](/docs/guides/experimentation/a-b-tests/messages/), [Sequence A/B test](/docs/guides/experimentation/a-b-tests/sequences/), or [Holdout Experiment](/docs/guides/experimentation/holdout-experiments/). [Jump to examples ↓](#control-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`experiment_id`** `string` The unique identifier for the Message A/B test or Holdout Experiment. Format: `uuid` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - [Web device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#webdevices) Information about web users generated by the SDK. - **`experiment_id`** `string` The unique identifier for the Message A/B test or Holdout Experiment. Format: `uuid` - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `CONTROL` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example control event* ```json { "id" : "ff76bb85-74bc-4511-a3bf-11b6117784db", "type": "CONTROL", "offset": "MTIzNQ", "occurred": "2015-05-03T02:32:12.088Z", "processed": "2015-05-03T12:12:43.180Z", "device": { "channel":"a61448e1-be63-43ee-84eb-19446ba743f0", "device_type":"ANDROID", "android_channel": "a61448e1-be63-43ee-84eb-19446ba743f0" }, "user": { "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "mini_me" }, "body:" { "push_id": "c91d9e1b-605f-4bad-a45d-cdf3e6e0773f", "group_id": "3eec7de4-4b19-436e-ad15-88278f9ddb82" } } ``` --- ## Custom {#custom} Represents Custom Events that are either emitted from the Airship SDK or submitted through the Custom Events API. You can configure Custom Events yourself. There are also several CUSTOM-type events for email and SMS that are defined by Airship. In general, you can expect device information if the event source is `SDK` or if the event is one of the defined email or SMS events (as defined by `event_type`). [Jump to examples ↓](#custom-examples) **All of:** - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `CUSTOM` **One of:** - [Email delivery event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emaildeliveryevent) - [Email injection event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emailinjectionevent) - [Email open event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emailopenevent) - [Email initial open event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emailinitialopenevent) - [Email delay event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emaildelayevent) - [Email bounce event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emailbounceevent) - [Email click event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emailclickevent) - [Email unsubscribe link event]({{< ref "/developer/rest-api/connect/schemas/custom-email-events/" >}}#emailunsubscribelinkevent) - [SMS delivery report]({{< ref "/developer/rest-api/connect/schemas/custom-sms-events/" >}}#delivery_report) - [RCS read report]({{< ref "/developer/rest-api/connect/schemas/custom-sms-events/" >}}#rcs_read_report) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`customer_id`** `string` An external customer-side ID, such as an email address. Absent if empty. - **`interaction_id`** `string` An Airship identifier uniquely identifying the interaction. May be absent. - **`interaction_type`** `string` The type of interaction as set by the Airship SDK. Values determine whether the interaction triggered an event from the Message Center (`ua_mcrap`), a landing page (`ua_landing_page`), an interactive notification (`ua_interactive_notification`), or a button tap (`ua_button_tap`). Button tap events with custom names are in the format `ua_button_tap-`. For example, for a button action with custom name `Cat socks55`, the event name is `ua_button_tap-Cat socks55`. See [Buttons and images: App](/docs/guides/messaging/editors/interactive/actions/#buttons-and-images-app) in *Actions in the Interactive editor*. Possible values: `ua_mcrap`, `ua_landing_page`, `ua_interactive_notification`, `ua_button_tap`, `ua_button_tap-` - **`last_delivered`** `object` Identifies the last push notification the audience received before the event. Absent if the last push occurred more than 12 hours ago. **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`time`** `string` The UTC time when the push occurred. - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`name`** `string` **REQUIRED** A plain-text name given to the event. Example: `purchased` - **`properties`** `object` Supports up to 100 key/value pairs that describe Custom Event properties. If the event has no custom properties, this field is absent. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source`** `string` **REQUIRED** The event source. `SDK` indicates an event sent from the Airship SDK. `API` indicates an event created by request against the [Custom Events API](/docs/developer/rest-api/ua/operations/custom-events). Possible values: `SDK`, `API` - **`transaction`** `string` If the event is one in a series representing a single transaction, use the value in this field to tie events together. Example: `886f53d4-3e0f-46d7-930e-c2792dac6e0a` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> The push that caused the Custom Event. Absent if a causal relationship to a push cannot be established. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`value`** `number` Populated if the event is associated with a count or amount. Airship treats this field as a representation of money. The `value` field respects six digits of precision to the right of the decimal point. Example: `120.49` - **`device`** `object` **REQUIRED** Device information related to the event. Either the `channel` or `named_user_id` is required. The `named_user_id` is required for Custom Events sent via the API, else `channel` is required. **OBJECT PROPERTIES** - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`device_type`** `string` **REQUIRED** The type of device the event was generated from. Possible values: `OPEN`, `WEB`, `ANDROID`, `IOS`, `AMAZON`, `EMAIL`, `SMS` - **`named_user_id`** `string` The Named User identifier for a device. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example Custom Event (entire payload on Android channel)* ```json { "id": "4f42e8d0-a010-11ee-ae53-000000a91ace", "offset": "1009810398823", "occurred": "2023-12-21T14:50:35.077Z", "processed": "2023-12-21T14:50:40.843Z", "device": { "android_channel": "ac1960b9-24b6-4851-b907-b9e64f071890", "channel": "ac1960b9-24b6-4851-b907-b9e64f071890", "device_type": "ANDROID", "named_user_id": "c2cbc6e5145763ec58a4d85dfa4323aacc40afea", "attributes": { "locale_variant": "", "device_model": "M2101K9G", "app_version": "18.4.2", "app_package_name": "com.company_name.app_name", "iana_timezone": "Europe/Paris", "push_opt_in": "true", "locale_country_code": "FR", "device_os": "12", "locale_timezone": "3600", "locale_language_code": "fr", "background_push_enabled": "true", "ua_sdk_version": "16.9.2" } }, "body": { "name": "purchased", "value": 239.85, "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a", "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234", "interaction_type": "url", "properties": { "description": "Sneaker purchase", "brand": "Victory Sneakers", "colors": [ "red", "blue" ], "items": [ { "text": "New Line Sneakers", "price": "$ 79.95" }, { "text": "Old Line Sneakers", "price": "$ 79.95" }, { "text": "Blue Line Sneakers", "price": "$ 79.95" } ], "name": "Hugh Manbeing", "userLocation": { "state": "CO", "zip": "80202" } } }, "session_id": "adc0e12e-dfe8-4375-8121-5b21dbab87f4", "source": "SDK", "type": "CUSTOM" } ``` *Example Custom Event from API (shoe sale)* ```json { "name" : "shoe-purchase", "value" : 239.85, "source": "api", "transaction" : "Selling all the shoes", "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e", "properties": { "description": "Sneaker purchase", "brand": "Victory Sneakers", "colors": ["red","blue"], "items": [ { "text": "New Line Sneakers", "price": "$ 79.95" }, { "text": "Old Line Sneakers", "price": "$ 79.95" }, { "text": "Blue Line Sneakers", "price": "$ 79.95" } ], "name": "Hugh Manbeing", "userLocation": { "state": "CO", "zip": "80202" } } } ``` *Example Custom Event from SDK (shoe sale)* ```json { "name" : "shoe-purchase", "value" : 60.000000, "source": "sdk", "interaction_type" : "Landing Page", "interaction_id" : "d01d0380-da2e-11e3-8519-90e2ba299b38", "customer_id" : "George@example.com", "transaction" : "Selling all the shoes", "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e", "last_delivered": { "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828" }, "triggering_push": { "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06", "group_id": "8ea2abd6-dbc7-475a-9c57-fb31c7e2999b" }, "properties": { "coolest-identifier": "123-cool-cat-321", "ltv": false, "category": "womens_shoes", "id": 1267, "description": "plaid canvas", "brand": "hipster", "new_item": true } } ``` --- ## Feature Flag interaction event {#feature-flag-interaction} Occurs when a user interacts with a tracked flagged feature. See [Feature Flags](/docs/guides/experimentation/feature-flags/#interaction-events). The events have a flag ID and flag name, which identify which flagged feature a user interacted with. They also have a boolean `eligible` field, which indicates whether or not the user was in the Feature Flag audience and had access to the feature. [Jump to examples ↓](#feature-flag-interaction-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`eligible`** `boolean` **REQUIRED** Indicates whether or not the user was in the Feature Flag audience and had access to the feature. `true` means the user was in the Feature Flag audience and had access to the feature. - **`flag_id`** `string` **REQUIRED** A UUID that is associated with a feature flag. - **`flag_name`** `string` **REQUIRED** The name of a feature flag. - **`variant_id`** `string` The UUID of the A/B test variant, if available. - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - [Web device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#webdevices) Information about web users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `FEATURE_FLAG_INTERACTION` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example Feature Flag interaction event* ```json { "id":"c3d0543b-c8cd-4eaa-8fda-5dbfa70257ae", "offset":"1000197715722", "occurred":"2023-09-15T19:12:56.000Z", "processed":"2023-09-21T23:02:39.419Z", "device": { "channel":"8c36e8c7-5a73-47c0-9716-99fd3d4197d5", "device_type":"WEB" }, "body": { "flag_id":"27f26d85-0550-4df5-85f0-7022fa7a5925", "flag_name":"rad_flag_name", "eligible":true }, "type":"FEATURE_FLAG_INTERACTION" } ``` --- ## First open {#first-open} This event occurs when a user first registers a channel in your app. This event fires only once per user, when a channel is first registered. Channel registration most commonly occurs immediately after the first app open but can happen at other times as well, for example, if channel registration was delayed. The [open](#open) event fires on every app open, including the first. [Jump to examples ↓](#first-open-examples) - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - [Web device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#webdevices) Information about web users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `FIRST_OPEN` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example first open event* ```json { "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS", }, "id": "00000169-4a14-67b2-1ddd-d9e733622c3a", "occurred": "2019-03-04T19:00:45.106Z", "offset": "1000001260057", "processed": "2019-03-04T19:00:47.094Z", "type": "FIRST_OPEN" } ``` --- ## First opt-in {#first-opt-in} This event appears in the stream when a channel is first opted in. This event is specific to email (commercial), SMS, and open channels. [Jump to examples ↓](#first-opt-in-examples) - **`device`** `object` **REQUIRED** **One of:** - [Device information for SMS and email]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#sms_email_devices) Information about the SMS or email device related to an event. - [Open channel device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#opendevices) Information about open channel users. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `FIRST_OPT_IN` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example first opt-in event* ```json { "device": { "channel": "820e4493-e4c9-4577-99bc-a98180599f73", "delivery_address": "new.user@urbanairship.com", "device_type": "EMAIL" }, "id": "00000169-4a14-67b2-1ddd-d9e733622c3a", "occurred": "2019-03-04T19:00:45.106Z", "offset": "1000001260057", "processed": "2019-03-04T19:00:47.094Z", "type": "FIRST_OPT_IN" } ``` --- ## In-app button tap {#in-app-button-tap} Occurs when a button is tapped within a Scene. [Jump to examples ↓](#in-app-button-tap-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app button tap was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`button_id`** `string` A unique identifier for the button. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`locale`** `string` Optional string that defines the country and language this in-app-automation was localized as by remote-config-api. `country` - (String) An ISO 3166-1 country code, set by device settings. `language` - (String) The ISO 639-1 two-letter language code reflecting the language the phone is set to. - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` An ISO 8601 date-time indicating when the payload defining the in-app message was sent to the device. May be absent. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Appears if the user began the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_BUTTON_TAP` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app button tap event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "a9a5912c-2526-4383-b516-711c58aff900", "group_id": "a9a5912c-2526-4383-b516-711c58aff900", "session_id": "94e8caed-9b82-4166-b585-a01eed933855", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "context": { "reporting_context": { "content_types": [ "survey" ] }, "state": { "form": { "form_identifier": "870db95f-3715-4c98-8047-2871c175d003", "submitted": true, "type": "nps", "response_type": "nps" }, "pager": { "identifier": "9e051354-185b-4d4d-888a-885def2e6b7a", "page_identifier": "32f4fc47-74ee-41c6-8e16-c9e0aa364101", "page_index": 1, "page_count": 2, "completed": true } } }, "button_id": "dismiss_button" }, "type": "IN_APP_BUTTON_TAP" } ``` --- ## In-app experiences {#in-app-experiences} Events that occur related to the display and completion behavior of a Scene. These events are derived from source events generated by the SDK, so a single user action may generate two events: one for the SDK event, one representing the user action as it relates to their actual activity within the app or website. [Jump to examples ↓](#in-app-experiences-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app message was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`event_name`** `string` The name of the event. Possible values: `scene_displayed`, `scene_completed`, `scene_incomplete`, `survey_displayed`, `survey_submitted`, `survey_not_submitted` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`survey_type`** `string` Only present for survey events. Possible values: `nps`, `user_feedback` - **`time_sent`** `string` An ISO 8601 date-time, in UTC, when the event occurred. May be absent. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Present if the user started the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_EXPERIENCES` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app experiences event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "event_name": "scene_displayed", "time_sent": "2022-03-11T08:40:56.592Z", "session_id": "20162c5f-36c8-1808-6fc6-8eb836d7f7f2", "push_id": "2e12bc7b-04f2-3487-1480-44269b04c131", "group_id": "2e12bc7b-04f2-3487-1480-44269b04c131", "triggering_push": { "push_id": "5cc872d5-708d-dffb-0959-991b014dcd2d", "time": "2022-03-11T08:40:56.692Z", "campaigns": { "categories": [ "welcome_series" ] } } }, "type": "IN_APP_EXPERIENCES" } ``` --- ## In-app form display {#in-app-form-display} Occurs when a survey form in a Scene is displayed. [Jump to examples ↓](#in-app-form-display-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app form was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`forms`** `object` **OBJECT PROPERTIES** - **`form_id`** `string` The identifier of the form controller (required). Format: `uuid` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` An ISO 8601 date-time indicating when the payload defining the in-app message was sent to the device. May be absent. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Present if the user started the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`type`** `string` Required for this type, the value is always `DISPLAY`. Possible values: `DISPLAY` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_FORM_DISPLAY` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app form display event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "56d72d43-5567-4c94-887a-05b46ca9ef3e", "group_id": "56d72d43-5567-4c94-887a-05b46ca9ef3e", "session_id": "1347589f-0608-4198-b170-bfb46271877a", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "context": { "reporting_context": { "content_types": [ "survey" ] }, "state": { "form": { "form_identifier": "434b918f-6a00-496f-963c-f54923a67abf", "submitted": false, "type": "nps", "response_type": "nps" } } }, "type": "DISPLAY", "forms": [ { "form_id": "434b918f-6a00-496f-963c-f54923a67abf" } ] }, "type": "IN_APP_FORM_DISPLAY" } ``` --- ## In-app form result {#in-app-form-result} Occurs when a survey form in a Scene is submitted. [Jump to examples ↓](#in-app-form-result-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app form was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`forms`** `object` **OBJECT PROPERTIES** - **`form_id`** `string` The identifier of the form controller (required). Format: `uuid` - **`nps`** `object` **OBJECT PROPERTIES** - **`audience_category`** `string` **REQUIRED** The NPS category. Possible values: `PROMOTER`, `PASSIVE`, `DETRACTOR` - **`question_id`** `string` **REQUIRED** The question identifier. Format: `uuid` - **`score`** `number` **REQUIRED** A number between 0 and 10. - **`response_type`** `string` The survey response type. Possible values: `nps`, `user_feedback` - **`responses`** `object` **OBJECT PROPERTIES** - **`question_id`** `string` **REQUIRED** The question identifier. Format: `uuid` - **`type`** `string` **REQUIRED** The question type. Possible values: `single_choice`, `multiple_choice`, `text_input`, `email_input` - **`value`** `object` **REQUIRED** The choice type identifier for `single_choice` or `multiple_choice` questions, or user-provided text for `text_input` or `email_input` fields. - **`type`** `string` The form type. Possible values: `nps`, `form` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` An ISO 8601 date-time indicating when the payload defining the in-app message was sent to the device. May be absent. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Present if the user started the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`type`** `string` Required for this type, the value is always `RESULT`. Possible values: `RESULT` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_FORM_RESULT` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app form result event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "683b395d-7abf-40f9-be49-4b64debfbd22", "group_id": "683b395d-7abf-40f9-be49-4b64debfbd22", "session_id": "d05323b3-8176-406d-aff5-5194341f4a5c", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "context": { "reporting_context": { "content_types": [ "survey" ] }, "state": { "form": { "form_identifier": "316e8ed4-277e-408b-9c47-a6bd7a4251c5", "submitted": false, "type": "nps", "response_type": "nps" } } }, "type": "RESULT", "forms": [ { "form_id": "316e8ed4-277e-408b-9c47-a6bd7a4251c5", "type": "nps", "response_type": "nps", "nps": { "question_id": "b6563a26-a927-4ff2-af8a-08d94d8b84a3", "score": 9, "audience_category": "PROMOTER" }, "responses": [ { "question_id": "b6563a26-a927-4ff2-af8a-08d94d8b84a3", "type": "score", "value": "9" }, { "question_id": "c867cf61-398f-443c-b991-443fa8aff4b9", "type": "text_input", "value": "Hello, world" } ] } ] }, "type": "IN_APP_FORM_RESULT" } ``` --- ## In-app message control {#in-app-message-control} Occurs when an In-App Automation or Scene is not delivered because the targeted user's contact or Channel ID was part of a control group for a [Holdout Experiment](/docs/guides/experimentation/holdout-experiments/). [Jump to examples ↓](#in-app-message-control-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app message was created by the application logic, not the Airship system. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` The date-time when the in-app message payload was sent to the device. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Appears if the user began the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`type`** `string` Indicates that the in-app message was never delivered because the user was part of an experiment control group. `CONTROL` indicates that the message was not displayed because the channel or contact was hashed into the experiment control group. Possible values: `CONTROL` - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_MESSAGE_CONTROL` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app message control event* ```json { "id": "e9e281d0-2b39-11ee-ac42-00000a91ace1", "offset": "1000194023208", "occurred": "2023-07-25T22:22:40.262Z", "processed": "2023-07-25T22:23:43.464Z", "device": { "ios_channel": "414a7c7c-c3c5-4a9f-b1de-ebd5a85104e0", "channel": "414a7c7c-c3c5-4a9f-b1de-ebd5a85104e0", "device_type": "IOS", "attributes": { "locale_variant": "", "device_model": "arm64", "app_version": "1.0", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "17.0", "locale_timezone": "-25200", "locale_language_code": "en", "background_push_enabled": "true", "ua_sdk_version": "17.1.0" } }, "body": { "push_id": "6fc3b3a7-d860-4acd-b80d-82af02b5b0fa", "group_id": "6fc3b3a7-d860-4acd-b80d-82af02b5b0fa", "session_id": "f31c3769-8517-402a-8ae6-cdb323f5ec22", "context": { "reporting_context": { "content_types": [ "scene" ] } }, "type": "CONTROL" }, "type": "IN_APP_MESSAGE_CONTROL" } ``` --- ## In-app message display {#in-app-message-display} Occurs when an In-App Automation or Scene is displayed to a user. Because the event pertains to a specific device, the device information object will be populated. [Jump to examples ↓](#in-app-message-display-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app message was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Appears if the user began the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_MESSAGE_DISPLAY` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app message display event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "68be9eba-3f3e-4763-bbd1-c921a164af1b", "group_id": "49e59f68-d58c-4a2f-86ab-112f52e3c5d2", "variant_id": 5, "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e", "triggering_push": { "push_id": "18c0f649-2330-4fb0-a9fa-ad029f5f4e0e", "group_id": "c4c89025-0d25-434c-8040-283990585f01", "campaigns": { "categories": [ "welcome_series" ] } } }, "type": "IN_APP_MESSAGE_DISPLAY" } ``` *Example in-app message display event with context* ```json { "id": "c7b97941-5d1d-11ee-b7be-00000a91ace6", "offset": "1004335885834", "occurred": "2023-09-27T10:08:14.965Z", "processed": "2023-09-27T10:08:18.230Z", "device": { "android_channel": "3e75f0be-f312-413f-90c0-81d628410514", "channel": "3e75f0be-f312-413f-90c0-81d628410514", "device_type": "ANDROID", "named_user_id": "exampleuser", "attributes": { "locale_variant": "", "device_model": "SM-G981B", "app_version": "13.13.3", "app_package_name": "com.company_name.app_name", "iana_timezone": "Europe/Paris", "push_opt_in": "true", "locale_country_code": "FR", "device_os": "13", "locale_timezone": "7200", "locale_language_code": "fr", "background_push_enabled": "true", "ua_sdk_version": "16.4.0" } }, "body": { "push_id": "0390bd82-c28f-44cb-98d9-3f9b7eef939d", "group_id": "0390bd82-c28f-44cb-98d9-3f9b7eef939d", "campaigns": { "categories": [ "WELCOME_SERIES" ] }, "context": { "reporting_context": { "content_types": [ "scene" ] } }, "session_id": "6e11b019-4da0-4c66-8063-92ec2ce4ee36" }, "type": "IN_APP_MESSAGE_DISPLAY" } ``` --- ## In-app message exclusion {#in-app-message-exclusion} Occurs when an In-App Automation or Scene is not displayed on a device because the user was banned. See [Ban Lists](/docs/guides/audience/segmentation/ban-lists/). [Jump to examples ↓](#in-app-message-exclusion-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app message was created by the application logic, not the Airship system. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` The date-time when the in-app message payload was sent to the device. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Appears if the user began the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`type`** `string` Indicates that the in-app message was not displayed on a device because the channel or Named User was excluded from the push. The only possible value is `AUDIENCE_CHECK_EXCLUDED`, which indicates that the message was not displayed because the channel or Named User is on a project's [Ban List](/docs/guides/audience/segmentation/ban-lists/). This is also reported when a 400- or 500-level error resolving the user's status on a Ban List occurs. Possible values: `AUDIENCE_CHECK_EXCLUDED` - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_MESSAGE_EXCLUSION` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app message exclusion event* ```json { "id": "7fff2560-1d33-11ef-b484-0000a91acec5", "offset":"1000215341033", "occurred":"2024-05-28T20:47:20.183Z", "processed":"2024-05-28T20:47:31.090Z", "device": { "android_channel": "88663749-a19d-4daf-8d4c-09fc4cf03a12", "channel":"87663620-a99d-4daf-8f4c-88fc4cf03af4", "device_type": "ANDROID", "named_user_id": "cool_named_user", "attributes": { "locale_variant": "", "device_model": "DE2123", "app_version": "2024-05-25T040548", "app_package_name": "com.package.example", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "120", "locale_timezone": "-27000", "locale_language_code": "en", "background_push_enabled": "false", "ua_sdk_version":"18.0.0" } }, "body": { "push_id": "be711edb-d16d-465e-8091-a831041e2e53", "group_id":"be711edb-d16d-465e-8091-a831041e2e53", "session_id":"e8e72fa2-bfbc-405d-af85-8b428c8e38d9", "context": { }, "type":"AUDIENCE_CHECK_EXCLUDED" }, "type":"IN_APP_MESSAGE_EXCLUSION" } ``` --- ## In-app message expiration {#in-app-message-expiration} Occurs when a new In-App Automation or Scene message has taken the place of another message, a message has passed its expiration, or because displaying the message in-app would be redundant. This event type may be latent. It is not emitted until the app becomes active. [Jump to examples ↓](#in-app-message-expiration-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app message was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`replacing_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> An associated push object for the in-app message that replaced the message. Present if `type` is `REPLACED`. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_expired`** `string` The date-time when the message was set to expire. - **`time_sent`** `string` The date-time when the in-app message payload was sent to the device. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Appears if the user began the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`type`** `string` Indicates how the in-app message expired. * `REPLACED`: The in-app message was replaced by a more current one. If type is `REPLACED`, the `replacing_push` key will be present. * `EXPIRED`: The in-app message exceeded its expiration date. If type is `EXPIRED`, then the `time` key will be present. * `ALREADY_DISPLAYED`: The message was opened directly (either from the lock screen or notification center). The Airship SDK will NOT display it again in the app, because the user is guaranteed to have seen it. Possible values: `REPLACED`, `EXPIRED`, `ALREADY_DISPLAYED` - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_MESSAGE_EXPIRATION` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app message expiration event* ```json { "id": "910fea50-5d42-1159-b702-024288f4e1d3", "offset": "1000022468589", "occurred": "2019-04-03T18:59:02.246Z", "processed": "2019-04-03T19:10:26.301Z", "device": { "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "device_type": "ANDROID", "identifiers": { "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914", "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19", "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a" }, "attributes": { "locale_variant": "", "app_version": "dev", "device_model": "Android SDK built for x86", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "9", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "9.7.0", "location_permission": "NOT_ALLOWED" } }, "body": { "push_id": "a1fe5f2a-1d51-4f3a-a77b-35018031741d", "session_id": "3514bd74-bfa8-149e-9c12-a44794994ca8", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "type": "EXPIRED", "time_expired": "1970-01-01T00:00:00.000Z" }, "type": "IN_APP_MESSAGE_EXPIRATION" } ``` --- ## In-app message resolution {#in-app-message-resolution} Occurs when an In-App Automation or Scene is cleared from the display, either by user action or timeout. Because this event pertains to an individual device, the device information object will be present. [Jump to examples ↓](#in-app-message-resolution-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app message was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`button_description`** `string` The title of the button the user interacted with. Present if `type` is set to `BUTTON_CLICK`. - **`button_group`** `string` A category associated with the in-app message button. It may be [predefined](/docs/reference/messages/built-in-interactive-notifications/) or [custom defined](/docs/developer/sdk-integration/mobile/push/getting-started/), or blank if there is no association with a category. - **`button_id`** `string` A unique identifier for the button. Present if `type` is set to `BUTTON_CLICK`. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`duration`** `integer` The number of milliseconds that the user was on the screen. Format: `milliseconds` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` The date-time when the in-app message payload was sent to the device. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Appears if the user began the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`type`** `string` Indicates how the in-app message was resolved. * `BUTTON_CLICK`: The user clicked/tapped a button in the message. This type is accompanied by additional fields. * `MESSAGE_CLICK`: The user clicked/tapped a part of the message, but not a button. * `TIMED_OUT`: The user ignored the notification, and it dismissed itself after an interval of time. * `USER_DISMISSED`: The user clicked/tapped `X` to close the message or closed it using the swipe gesture. Possible values: `BUTTON_CLICK`, `MESSAGE_CLICK`, `TIMED_OUT`, `USER_DISMISSED` - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_MESSAGE_RESOLUTION` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app message resolution event* ```json { "id": "910fea50-5d42-1159-b702-024288f4e1d3", "offset": "1000022468589", "occurred": "2019-04-03T18:59:02.246Z", "processed": "2019-04-03T19:10:26.301Z", "device": { "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "device_type": "ANDROID", "identifiers": { "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914", "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19", "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a" }, "attributes": { "locale_variant": "", "app_version": "dev", "device_model": "Android SDK built for x86", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "9", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "9.7.0", "location_permission": "NOT_ALLOWED" } }, "body": { "push_id": "86ee0a6e-a46a-4bbe-a3d1-804891baaee4", "group_id": "68991b8d-0d6b-4e05-bc62-2cdec2085c18", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "time_sent": "2019-03-03T19:10:26.301Z", "type": "BUTTON_CLICK", "button_id": "yes", "button_group": "", "button_description": "Yes", "duration": 10000000000 }, "type": "IN_APP_MESSAGE_RESOLUTION" } ``` *Example in-app message resolution event with context* ```json { "id": "a0bc5c50-6d34-11ee-95dc-0000a91aced1", "offset": "1064988067725", "occurred": "2023-10-17T21:32:01.243Z", "processed": "2023-10-17T21:32:10.638Z", "device": { "ios_channel": "870c200f-d0e7-4e45-bd99-5b290c80b6a7", "channel": "870c200f-d0e7-4e45-bd99-5b290c80b6a7", "device_type": "IOS", "named_user_id": "exampleuser", "attributes": { "locale_variant": "", "device_model": "iPhone15,2", "app_version": "15.8.1", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/New_York", "push_opt_in": "false", "locale_country_code": "US", "device_os": "16.6.1", "locale_timezone": "-14400", "locale_language_code": "en", "background_push_enabled": "true", "ua_sdk_version": "16.12.0" } }, "body": { "push_id": "4015241b-2e71-43d8-85a0-cd500e97c15d", "group_id": "4015241b-2e71-43d8-85a0-cd500e97c15d", "campaigns": { "categories": [ "OfferLevel45", "VIP_OFFER" ] }, "context": { "reporting_context": { "content_types": [ "scene" ] } }, "session_id": "832e65de-453e-426d-a4a3-bd70ab0f827e", "type": "USER_DISMISSED", "duration": 2503 }, "type": "IN_APP_MESSAGE_RESOLUTION" } ``` --- ## In-app page swipe {#in-app-page-swipe} Occurs when a user swipes to the next or previous page (screen) in a pager (specific to Scenes). [Jump to examples ↓](#in-app-page-swipe-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app pager was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`from_page_index`** `number` Is the previous page index. - **`from_pager_identifier`** `string` Is the previous page identifier. Format: `uuid` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`locale`** `string` Optional string that defines the country and language this in-app-automation was localized as by remote-config-api. `country` - (String) An ISO 3166-1 country code, set by device settings. `language` - (String) The ISO 639-1 two-letter language code reflecting the language the phone is set to. - **`pager_identifier`** `string` Is the pager controller identifier. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` An ISO 8601 date-time indicating when the payload defining the in-app pager was sent to the device. May be absent. - **`to_page_identifier`** `string` Is the current page identifier. Format: `uuid` - **`to_page_index`** `number` Is the current page index. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Present if the user started the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_PAGE_SWIPE` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app page swipe event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "91baacc8-1ebf-411d-a77a-ee036c44e7ce", "group_id": "91baacc8-1ebf-411d-a77a-ee036c44e7ce", "session_id": "a135087c-ba97-4b87-ac1d-a216f2cccb7c", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "context": { "reporting_context": { "content_types": [ "scene" ] }, "state": { "pager": { "identifier": "302e80f2-1f9d-4e0d-890d-ff54196189d9", "page_identifier": "c3c6fe17-1c47-4f52-bff9-f95ed8a14072", "page_index": 1, "page_count": 3, "completed": true } } }, "pager_identifier": "302e80f2-1f9d-4e0d-890d-ff54196189d9", "from_page_identifier": "c3c6fe17-1c47-4f52-bff9-f95ed8a14072", "from_page_index": 1, "to_page_identifier": "2ecb1788-30b9-4d8f-a267-38f687fc6e8b", "to_page_index": 0 }, "type": "IN_APP_PAGE_SWIPE" } ``` --- ## In-app page view {#in-app-page-view} Occurs when a page (screen) is displayed within a pager (specific to Scenes). [Jump to examples ↓](#in-app-page-view-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app pager was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`completed`** `boolean` True if the user reached the end of the pager. - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`locale`** `string` Optional string that defines the country and language this in-app-automation was localized as by remote-config-api. `country` - (String) An ISO 3166-1 country code, set by device settings. `language` - (String) The ISO 639-1 two-letter language code reflecting the language the phone is set to. - **`page_count`** `number` Total number of pages. - **`page_identifier`** `string` The current page identifier. Format: `uuid` - **`page_index`** `number` Is the current pager index. - **`pager_identifier`** `string` Is the pager controller identifier. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` An ISO 8601 date-time indicating when the payload defining the in-app message was sent to the device. May be absent. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Present if the user started the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`viewed_count`** `number` Number of times the current page has been viewed. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_PAGE_VIEW` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app page view event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "d2482092-a0f5-4ec0-bf0a-f17a1657d1b0", "group_id": "d2482092-a0f5-4ec0-bf0a-f17a1657d1b0", "session_id": "65be61ee-dc60-47ec-b9d3-ebc469e0523b", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "context": { "reporting_context": { "content_types": [ "scene" ] }, "state": { "pager": { "identifier": "f4d3d085-010b-4c2b-9e4d-574112b892ed", "page_identifier": "e55e6d8e-f04d-43f1-939c-822a1dd5a5e3", "page_index": 0, "page_count": 1, "completed": true } } }, "pager_identifier": "f4d3d085-010b-4c2b-9e4d-574112b892ed", "page_identifier": "e55e6d8e-f04d-43f1-939c-822a1dd5a5e3", "page_index": 0, "page_count": 1, "viewed_count": 1, "completed": true }, "type": "IN_APP_PAGE_VIEW" } ``` --- ## In-app pager completed {#in-app-pager-completed} Occurs when the last page (screen) of a pager is viewed for the first time (specific to Scenes). [Jump to examples ↓](#in-app-pager-completed-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app pager was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`locale`** `string` Optional string that defines the country and language this in-app-automation was localized as by remote-config-api. `country` - (String) An ISO 3166-1 country code, set by device settings. `language` - (String) The ISO 639-1 two-letter language code reflecting the language the phone is set to. - **`page_count`** `number` Total number of pages. - **`page_identifier`** `string` The current page identifier. Format: `uuid` - **`page_index`** `number` Is the current pager index. - **`pager_identifier`** `string` Is the pager controller identifier. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` An ISO 8601 date-time indicating when the payload defining the in-app message was sent to the device. May be absent. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Present if the user started the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_PAGER_COMPLETED` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app pager completed event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "a9a5912c-2526-4383-b516-711c58aff900", "group_id": "a9a5912c-2526-4383-b516-711c58aff900", "session_id": "94e8caed-9b82-4166-b585-a01eed933855", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "context": { "reporting_context": { "content_types": [ "survey" ] }, "state": { "form": { "form_identifier": "870db95f-3715-4c98-8047-2871c175d003", "submitted": true, "type": "nps", "response_type": "nps" }, "pager": { "identifier": "9e051354-185b-4d4d-888a-885def2e6b7a", "page_identifier": "32f4fc47-74ee-41c6-8e16-c9e0aa364101", "page_index": 1, "page_count": 2, "completed": true } } }, "pager_identifier": "9e051354-185b-4d4d-888a-885def2e6b7a", "page_identifier": "32f4fc47-74ee-41c6-8e16-c9e0aa364101", "page_index": 1, "page_count": 2 }, "type": "IN_APP_PAGER_COMPLETED" } ``` --- ## In-app pager summary {#in-app-pager-summary} Describes the full path a user took within a pager (specific to Scenes), including the order of pages (screens) visited and time spent per page. [Jump to examples ↓](#in-app-pager-summary-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`app_defined_id`** `string` An identifier defined by the application if the in-app pager was created by the application logic, not Airship. If this field is present, the event body will not contain `push_id`, `group_id`, `campaigns`, `variant_id`, or `triggering_push` fields. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`completed`** `boolean` True if the user reached the end of the pager. - **`context`** `object` <[In-app context]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#in_app_context)> The context provides the view state when a button, pager, or form interaction occurs. - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`locale`** `string` Optional string that defines the country and language this in-app-automation was localized as by remote-config-api. `country` - (String) An ISO 3166-1 country code, set by device settings. `language` - (String) The ISO 639-1 two-letter language code reflecting the language the phone is set to. - **`page_count`** `number` Total number of pages. - **`page_identifier`** `string` The current page identifier. Format: `uuid` - **`pager_identifier`** `string` Is the pager controller identifier. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`time_sent`** `string` An ISO 8601 date-time indicating when the payload defining the in-app message was sent to the device. May be absent. - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> Optional. Present if the user started the current session by opening a push notification. It does not describe the campaign for this message, but refers to another campaign that can be attributed to this event. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`viewed_pages`** `object` **OBJECT PROPERTIES** - **`display_time_ms`** `number` Is how long the page was displayed in milliseconds. Format: `milliseconds` - **`page_identifier`** `string` The current page identifier. Format: `uuid` - **`page_index`** `number` The current page index. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `IN_APP_PAGER_SUMMARY` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app pager summary event* ```json { "id": "51dd7c1c-5621-11e9-9601-0242539d70ef", "offset": "1000022467557", "occurred": "2019-03-29T21:42:21.245Z", "processed": "2019-04-03T15:10:23.828Z", "device": { "ios_channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "channel": "a61448e1-be63-43ee-84eb-19446ba743f0", "device_type": "IOS", "named_user_id": "cooluser", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B147E0CE-272E-4047-A79C-30D02A2F213D", "GA_CID": "a61448e1-be63-43ee-84eb-19446ba743f0", "com.urbanairship.idfa": "A76E6F83-4F4A-47E2-BFDD-72BED91D2D1F", "com.urbanairship.vendor": "ED496B1A-43F1-45A9-A7C1-80125DE8A5B1" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone7,2", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "11.4", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "push_id": "898c0cde-02d8-4674-8c3a-91183aab8b7b", "group_id": "898c0cde-02d8-4674-8c3a-91183aab8b7b", "session_id": "393ae595-bb43-48a2-9878-996e11581754", "triggering_push": { "push_id": "a183f051-7d69-11ed-86d9-0242dc3f670b", "group_id": "8e7cfac3-cfd3-4f4f-a9a1-d766de9b063a", "campaigns": { "categories": [ "welcome_series" ] } }, "context": { "reporting_context": { "content_types": [ "scene" ] }, "state": { "pager": { "identifier": "7cb3bd21-060c-46d6-9e88-fb0b5376897e", "page_identifier": "7888b6dd-0a33-420d-a596-1342dca84fcf", "page_index": 0, "page_count": 1, "completed": false } } }, "pager_identifier": "7cb3bd21-060c-46d6-9e88-fb0b5376897e", "page_count": 1, "completed": false, "viewed_pages": [ { "page_identifier": "7888b6dd-0a33-420d-a596-1342dca84fcf", "page_index": 0, "display_time_ms": 33019 } ] }, "type": "IN_APP_PAGER_SUMMARY" } ``` --- ## Label event {#label-event} Occurs when you update a Scene screen name. [Jump to examples ↓](#label-event-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`labels`** `array[object]` **REQUIRED** Page list - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, and `body` values but different `offset` and `processed` values. Use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `LABEL_EVENT` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example label event* ```json { "id":"00000199-2eb3-7fdc-b598-bf7930422ef4", "offset":"1000232372984", "occurred":"2025-09-09T13:38:59.676Z", "processed":"2025-09-09T13:38:59.808Z", "body":{ "push_id":"f9dde97e-e0f7-47f8-928b-08ebd761a1ea", "labels":[ { "id":"81f5e794-9a81-418a-b625-6affd0f99f34", "label":"Screen 1" }, { "id":"8011912d-26bf-4163-b545-e047165cf0a9", "label":"Screen 2" }, { "id":"3142620e-844e-461e-bc4f-4a706d2bcbe2", "label":"Screen 3" } ] }, "type":"LABEL_EVENT" } ``` --- ## Location {#location} An event declaring the device to be at a particular latitude and longitude. [Jump to examples ↓](#location-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`foreground`** `boolean` **REQUIRED** If true, the application was foregrounded when the event occurred. - **`latitude`** `string` **REQUIRED** The latitude where the event occurred. - **`longitude`** `string` **REQUIRED** The longitude where the event occurred. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `LOCATION` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example location event* ```json { "id": "910fea50-5d42-1159-b702-024288f4e1d3", "offset": "1000022468589", "occurred": "2019-04-03T18:59:02.246Z", "processed": "2019-04-03T19:10:26.301Z", "device": { "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "device_type": "ANDROID", "identifiers": { "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914", "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19", "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a" }, "attributes": { "locale_variant": "", "app_version": "dev", "device_model": "Android SDK built for x86", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "9", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "9.7.0", "location_permission": "ALWAYS_ALLOWED" } }, "body": { "latitude": "51.5033630", "longitude": "-0.1276250", "foreground": true, "session_id": "ecd3741d-92c4-469b-b42c-888e40a121d3" }, "type": "LOCATION" } ``` --- ## Mobile originated event {#mobile-originated} Represents a message action that originated from a user — like an inbound SMS or email. [Jump to examples ↓](#mobile-originated-examples) - **`body`** `object` <[Mobile-originated SMS event]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#mobile_originated_sms)> **REQUIRED** An event that occurs when a user sends a message from an SMS device, i.e., the message originates from a mobile device and not from the server (Airship). This event contains context related to the message's origin, the incoming message itself, and Airship's response to the origin. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `MOBILE_ORIGINATED` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example mobile-originated SMS event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "mobile_originated_sms", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "inbound_message": "join", "outbound_message": "Thanks for joining!", "keyword": "join" } }, "type": "MOBILE_ORIGINATED" } ``` --- ## Open {#open} Occurs when a user opens your app. This event fires every time a user opens your app, including the first time. See also the [first open](#first-open) event. [Jump to examples ↓](#open-examples) - **`body`** `object` **OBJECT PROPERTIES** - **`last_delivered`** `object` Identifies the last push notification the audience received before the event. Absent if the last push occurred more than 12 hours ago. **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`time`** `string` The UTC time when the push occurred. - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> An associated push object, establishing a causal relationship between a push and the Open event. Absent if a causal relationship to a push cannot be established. The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> Information about app users generated by the SDK. - **`id`** `string` Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` Possible values: `OPEN` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example open event* ```json { "id": "910fea50-5d42-1159-b702-024288f4e1d3", "offset": "1000022468589", "occurred": "2019-04-03T18:59:02.246Z", "processed": "2019-04-03T19:10:26.301Z", "device": { "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "device_type": "ANDROID", "identifiers": { "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914", "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19", "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a" }, "attributes": { "locale_variant": "", "app_version": "1037.04c13d-master", "device_model": "Nokia 6.1", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "9", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "9.7.0", "location_permission": "ALWAYS_ALLOWED" } }, "user": { "contact_id": "982B35f2-0375-6384-893e-a19b5cd5R771" }, "body": { "last_delivered": { "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828", "time": "2015-07-30T21:03:37.631Z" }, "triggering_push": { "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06", "group_id": "8ea2abd6-dbc7-475a-9c57-fb31c7e2999b", "variant_id": 1 }, "session_id": "ad4ad05a-17f4-4eab-9c6f-d3f7fbf3cc25" }, "type": "OPEN" } ``` --- ## Push body {#push-body} Occurs when you initiate a push, automation, or sequence. Airship fulfills delivery over a time interval with a number of child pushes, each with a unique Push ID and a common Group ID. There is no guarantee that push body events (defined in Push Body Event) for the child pushes fulfilling a group will appear in the stream. **Note:** When you start, pause, or publish a sequence, Airship emits a `push_body` event for the sequence itself, and each message contained within the sequence (i.e., messages +1). After you start a sequence, Airship does not issue subsequent `push_body` events for the sequence unless you pause or publish changes to the sequence. [Jump to examples ↓](#push-body-examples) - **`body`** `object` **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`payload`** `string` **REQUIRED** The specification of the push as sent via the API, a Base64 encoded JSON value. - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`resource`** `string` **REQUIRED** Describes the type of push, helping you interpret the JSON response. Values pertain to the push `type`. Possible values: `PIPELINES`, `SCHEDULES`, `PUSH`, `EXPERIMENTS`, `IN_APP_AUTOMATION` - **`trimmed`** `boolean` **REQUIRED** If true, the push payload was trimmed from the event body. - **`id`** `string` Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` Possible values: `PUSH_BODY` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example push body event* ```json { "id": "910fea50-5d42-1159-b702-024288f4e1d3", "offset": "1000022468589", "occurred": "2019-04-03T18:59:02.246Z", "processed": "2019-04-03T19:10:26.301Z", "body": { "push_id": "233f8109-bf56-4d95-a8bf-6f28e9d270a4", "campaigns": { "categories": [ "hello", "numberwang", "first message" ] }, "resource": "PUSH", "trimmed": false, "payload": "eyJkZXZpY2VfdHlwZXMiOiBbImFuZHJvaWQiLCAiaW9zIl0sICJub3RpZmljYXRpb24iOiB7ImFuZHJvaWQiOiB7fSwgImlvcyI6IHsiYmFkZ2UiOiAiKzEifSwgImFsZXJ0IjogIklUIFdJTEwgV09SSyEifSwgImF1ZGllbmNlIjogImFsbCJ9" }, "type": "PUSH_BODY" } ``` --- ## Region event {#region} Region events are emitted when a device enters or exits a geofence or the range of any of a set of bluetooth beacons. Region events require a Gimbal integration. Events for Gimbal customers include the Gimbal application instance identifier as `com.urbanairship.gimbal.aii` within the `identifiers` object. [Jump to examples ↓](#region-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`action`** `string` **REQUIRED** Indicates whether the event was the result of a user entering or exiting the region. Possible values: `enter`, `exit` - **`name`** `string` A friendly name for the event; may be retrieved from a third-party. - **`region_id`** `string` **REQUIRED** The identifier for the region in Airship. Format: `uuid` - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`source_info`** `object` **REQUIRED** Information about the source application that generated the event. **OBJECT PROPERTIES** - **`region_id`** `string` The unique region identifier from the originating system. - **`source`** `string` Identifies the system that the event originated from. Example: `Gimbal` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `REGION` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example region event* ```json { "id": "910fea50-5d42-1159-b702-024288f4e1d3", "offset": "1000022468589", "occurred": "2019-04-03T18:59:02.246Z", "processed": "2019-04-03T19:10:26.301Z", "device": { "android_channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "channel": "364a4e3f-170a-4f26-b0a1-11b280377dfe", "device_type": "ANDROID", "identifiers": { "com.urbanairship.gimbal.aii": "2471037d-71d8-4229-a40f-df719f1af914", "session_id": "54204a73-7a95-4ffc-8051-bf230d086e19", "GA_CID": "90d56c80-f31f-49fd-87b0-20deb3d2602a" }, "attributes": { "locale_variant": "", "app_version": "dev", "device_model": "Android SDK built for x86", "app_package_name": "com.company_name.app_name", "iana_timezone": "America/Los_Angeles", "push_opt_in": "true", "locale_country_code": "US", "device_os": "9", "locale_timezone": "-25200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "9.7.0", "location_permission": "ALWAYS_ALLOWED" } }, "body":{ "action": "enter", "region_id": "fb542343-9a43-450a-be7f-43bed95057ff", "session_id": "0a50fdb9-dfa9-4e0e-8373-4f0c5c7137c7", "name": "Coolest Place", "source_info": { "source": "Gimbal", "region_id": "a vendor identifier" } }, "type": "REGION" } ``` --- ## Rich control {#rich-control} Occurs when a Message Center message is not delivered to a user because they are in a control group for a [Sequence A/B test](/docs/guides/experimentation/a-b-tests/sequences/) or [Holdout Experiment](/docs/guides/experimentation/holdout-experiments/). [Jump to examples ↓](#rich-control-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`experiment_id`** `string` ID for the requested experiment. Format: `uuid` - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `RICH_CONTROL` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example event body - message not delivered due to user being in a control group* ```json { "id" : "e97ef291-eb48-6614-a9f4-9138244a9144", "offset" : "-1099401623", "occurred" : "2024-11-05T23:47:55.473Z", "processed" : "2024-11-05T23:47:55.473Z", "device" : { "ios_channel" : "564f958c-806f-bdaf-340b-1a25867d1c6a", "channel" : "564f958c-806f-bdaf-340b-1a25867d1c6a", "device_type" : "IOS" }, "user": { "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "mini_me" }, "body" : { "push_id" : "62fd4bac-a85a-0e18-00b4-9e59339bece5", "group_id" : "da16d1c2-7d8f-9ade-ff14-05ce696ba042" }, "type" : "RICH_CONTROL" } ``` --- ## Rich delete {#rich-delete} Occurs when a user deletes a Message Center message from their inbox. [Jump to examples ↓](#rich-delete-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `RICH_DELETE` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example event body - indicates the `push_id` that was deleted* ```json { "id": "ca2948b0-56ea-11e9-88dc-a142740a77e1", "offset": "1000022469540", "occurred": "2019-04-04T15:03:22.545Z", "processed": "2019-04-04T15:12:54.657Z", "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS", "named_user_id": "coolusername", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "837645C4-BD17-455C-96A3-999E1290EFA7", "GA_CID": "d12b5b66-d0c6-40f6-923f-ea039e3e8297", "com.urbanairship.idfa": "9610438A-6AEF-4113-BB99-2F64CB56ED2F", "com.urbanairship.vendor": "F2519C6C-A724-4343-80C7-1F1E42C53DFF" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone8,1", "app_package_name": "com.company_name.app_name", "iana_timezone": "Europe/London", "push_opt_in": "true", "locale_country_code": "GB", "device_os": "12.1.4", "locale_timezone": "3600", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "FOREGROUND_ALLOWED" } }, "user": { "named_user_id": "coolusername", "contact_id": "982B35f2-0375-6384-893e-a19b5cd5R771" }, "body": { "push_id": "1bf2A1a1-4069-11e9-abf1-024297609801" }, "type": "RICH_DELETE" } ``` --- ## Rich delivery {#rich-delivery} Occurs when a Message Center message is delivered to a user's inbox. Even though rich push deliveries may or may not cause an alert on the user's lock screen, they are always associated with a push identifier in the Airship system. [Jump to examples ↓](#rich-delivery-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `RICH_DELIVERY` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example event body — indicates the `push_id` that reached the user* ```json { "id": "83848900-54ac-11e9-a132-024278224c1c", "offset": "1000022466003", "occurred": "2019-04-01T18:32:32.912Z", "processed": "2019-04-01T18:32:33.031Z", "device": { "android_channel": "1de67612-94bc-4d02-85b0-37ede154a9d7", "channel": "1de67612-94bc-4d02-85b0-37ede154a9d7", "device_type": "ANDROID" }, "user": { "contact_id": "982B35f2-0375-6384-893e-a19b5cd5R771" }, "body": { "push_id": "1a7d774c-1659-4104-b594-2f7ec739c92d" }, "type": "RICH_DELIVERY" } ``` --- ## Rich read {#rich-read} Occurs when a user reads a Message Center message in their inbox. [Jump to examples ↓](#rich-read-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` A unique identifier for a push operation. Format: `uuid` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `RICH_READ` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example event body — indicates the `push_id` that the user read* ```json { "id": "ca2948b0-56ea-11e9-88dc-a142740a77e1", "offset": "1000022469540", "occurred": "2019-04-04T15:03:22.545Z", "processed": "2019-04-04T15:12:54.657Z", "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS", "named_user_id": "coolusername", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "837645C4-BD17-455C-96A3-999E1290EFA7", "GA_CID": "d12b5b66-d0c6-40f6-923f-ea039e3e8297", "com.urbanairship.idfa": "9610438A-6AEF-4113-BB99-2F64CB56ED2F", "com.urbanairship.vendor": "F2519C6C-A724-4343-80C7-1F1E42C53DFF" }, "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone8,1", "app_package_name": "com.company_name.app_name", "iana_timezone": "Europe/London", "push_opt_in": "true", "locale_country_code": "GB", "device_os": "12.1.4", "locale_timezone": "3600", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "FOREGROUND_ALLOWED" } }, "user": { "named_user_id": "coolusername", "contact_id": "982B35f2-0375-6384-893e-a19b5cd5R771" }, "body": { "push_id": "1bf2A1a1-4069-11e9-abf1-024297609801", "time": "2019-03-04T15:12:54.657Z" }, "type": "RICH_READ" } ``` --- ## Screen viewed {#screen-viewed} Occurs when a user has finished viewing a screen. It is up to you to instrument your application with names for each screen. Doing so will allow you to determine the user's path by filtering on the fields in the table below. [Jump to examples ↓](#screen-viewed-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`duration`** `integer` The number of milliseconds that the user was on the screen. Format: `milliseconds` - **`previous_screen`** `string` The name assigned to the screen the user was on prior to the `viewed_screen`. - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`viewed_screen`** `string` The name assigned to the screen that the user left. - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `SCREEN_VIEWED` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example screen viewed event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "ios_channel": "c1ca5af6-b014-46f9-8566-33f5f52c7b19", "channel": "c9cb18f7-b814-40f9-8566-33f5f52c7c48", "device_type": "IOS", "identifiers": { "com.urbanairship.limited_ad_tracking_enabled": "true", "session_id": "B1E00276-98BE-4B38-9077-FB2E90EFBE1B", "GA_CID": "1fa021e7-8298-4f92-bee0-07cb95eecfdd", "com.urbanairship.idfa": "1821a235-CD43-4ED8-8633-3BD3B991FA25", "com.urbanairship.vendor": "164d552C-F5F0-4C83-B529-321667C8E48A" }, "attributes": { "locale_variant": "", "app_version": "550", "device_model": "iPhone9,1", "app_package_name": "com.company_name.app_name", "iana_timezone": "Europe/Berlin", "push_opt_in": "true", "locale_country_code": "US", "device_os": "12.2", "locale_timezone": "7200", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.2", "location_permission": "FOREGROUND_ALLOWED" } }, "body": { "duration": 13933, "viewed_screen": "home", "previous_screen": "message_center", "session_id": "a26102f9-7fb2-451d-a65c-56e9394cf726" }, "type": "SCREEN_VIEWED" } ``` --- ## Send {#send} Occurs whenever a push notification is sent to a device identified in the audience selector of a message. [Jump to examples ↓](#send-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`alerting`** `boolean` If true, the send event was alerting. Alerting send event has notification text, badge, or sound. - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`click_tracking`** `boolean` If true, email click events will be reported. Only HTTP and HTTPS links are tracked. - **`context`** `object` An object that establishes a relationship between a push and the origin of the message. Only messages triggered by a Custom Event will include the context. **OBJECT PROPERTIES** - **`event_uuid`** `string` **REQUIRED** The ID of the Custom Event which triggered the send. Format: `uuid` - **`interaction_id`** `string` If `interaction_id` was set on the Custom Event body, it will be populated here. - **`transaction`** `string` If `transaction` was set on the Custom Event body, it will be populated here. - **`triggered_by`** `string` **REQUIRED** The triggering event type. Possible values: `custom_event` - **`experiment_id`** `string` The unique identifier for the Message A/B test or Holdout Experiment. Format: `uuid` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`open_tracking`** `boolean` If true, email open events will be reported. - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - [Web device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#webdevices) Information about web users generated by the SDK. - [Device information for SMS and email]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#sms_email_devices) Information about the SMS or email device related to an event. - [Open channel device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#opendevices) Information about open channel users. - **`experiments`** `object` An object listing the details of the [Message A/B test](/docs/guides/experimentation/a-b-tests/messages) or [Holdout Experiment](/docs/guides/experimentation/holdout-experiments), if the send includes either. **OBJECT PROPERTIES** - **`experiment_id`** `string` The unique identifier for the Message A/B test or Holdout Experiment. Format: `uuid` - **`type`** `string` The type of experiment. `GLOBAL` is for A/B tests, `EXP_GROUP` is for Holdout Experiments. Possible values: `EXP_GROUP`, `GLOBAL` - **`variant_id`** `string` For A/B tests, the string ID of the message variant. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `SEND` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example send event* ```json { "id": "ca2948b0-56ea-11e9-88dc-a142740a77e1", "offset": "1000022469540", "occurred": "2019-04-04T15:03:22.545Z", "processed": "2019-04-04T15:12:54.657Z", "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS", "named_user_id": "coolusername", "attributes": { "locale_variant": "", "app_version": "542", "device_model": "iPhone8,1", "app_package_name": "com.company_name.app_name", "iana_timezone": "Europe/London", "push_opt_in": "true", "locale_country_code": "GB", "device_os": "12.1.4", "locale_timezone": "3600", "locale_language_code": "en", "location_enabled": "false", "background_push_enabled": "true", "ua_sdk_version": "10.2.0", "location_permission": "FOREGROUND_ALLOWED" } }, "user": { "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "coolusername" }, "body": { "variant_id": 1, "push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e", "alerting": true, "campaigns": { "categories": [ "hello", "numberwang", "first message" ] }, "context": { "triggered_by": "custom_event", "event_uuid": "03669090-f934-45e2-a443-c75f6304ae6c", "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a", "interaction_id": "hello" } }, "type": "SEND" } ``` --- ## Send aborted {#send-aborted} Occurs when a push is dropped from our system before delivery is attempted. This can happen: * When using [External Data Feeds](/docs/guides/personalization/sources/external-data-feeds/) to personalize a message and an error was encountered or the feed returned a non-successful response * When a [Message Limit](/docs/guides/messaging/project/config/message-limits/) is met * When a [Ban List](/docs/guides/audience/segmentation/ban-lists/) webhook issues a `drop` response for a user Device information for the device that did not receive the push is included with `SEND_ABORTED` events. [Jump to examples ↓](#send-aborted-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`reason`** `string` **REQUIRED** Describes the reason this push was aborted. * `FEED_BANNED_RESPONSE`: The response from the endpoint indicated a channel was banned. See [Ban Lists](/docs/guides/audience/segmentation/ban-lists/). * `FEED_REQUEST_REJECTED`: The request to the specified server was rejected. Occurs when a 4xx HTTP response code is returned when Airship calls the webhook. * `FEED_RESOLVE_FAILURE`: The URI of the feed could not be resolved. * `FREQUENCY_LIMIT_FAILURE`: A [Message Limit](/docs/guides/messaging/project/config/message-limits/) retrieval failed. * `FREQUENCY_LIMIT_REACHED`: A [Message Limit](/docs/guides/messaging/project/config/message-limits/) was exceeded. * `UNKNOWN`: The error occurred due to another problem. Possible values: `FEED_BANNED_RESPONSE`, `FEED_REQUEST_REJECTED`, `FEED_RESOLVE_FAILURE`, `FREQUENCY_LIMIT_FAILURE`, `FREQUENCY_LIMIT_REACHED`, `UNKNOWN` - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `SEND_ABORTED` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example send aborted event* ```json { "id": "fc06bf54-619b-4fda-9345-d8f9f8e891ef", "occurred": "2021-02-26T20:50:21.12Z", "offset": "1000001215643", "processed": "2021-02-26T20:50:49.64Z", "type": "SEND_ABORTED", "device": { "android_channel": "e664fb42-d1a7-4956-9907-88c49394ae70", "channel": "e664fb42-d1a7-4956-9907-88c49394ae70", "device_type": "ANDROID", }, "body": { "push_id": "26ea5408-a1ec-4771-b4f0-e86d45c03f8a", "group_id": "3795a26d-2d74-462b-b228-ca3ed31ef7b1", "reason": "FEED_RESOLVE_FAILURE" } } ``` *Example send aborted event due to Ban List* ```json { "id": "fc06bf54-619b-4fda-9345-d8f9f8e891ef", "occurred": "2021-02-26T20:50:21.12Z", "offset": "1000001215643", "processed": "2021-02-26T20:50:49.64Z", "type": "SEND_ABORTED", "device": { "android_channel": "e664fb42-d1a7-4956-9907-88c49394ae70", "channel": "e664fb42-d1a7-4956-9907-88c49394ae70", "device_type": "ANDROID", }, "body": { "push_id": "26ea5408-a1ec-4771-b4f0-e86d45c03f8a", "group_id": "3795a26d-2d74-462b-b228-ca3ed31ef7b1", "reason": "FEED_BANNED_RESPONSE" } } ``` --- ## Send rejected {#send-rejected} Occurs when a push fails during communication with a third party, like APNs or GCM. This typically indicates that the user has uninstalled the app or otherwise invalidated the last-registered credentials stored in Airship. The event contains the rejected push and the group, variant, or campaigns the push belonged to. Device information for the device that did not receive the push is included with `SEND_REJECTED` events. [Jump to examples ↓](#send-rejected-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`status`** `string` The status of the message. Possible values: `BadDeviceToken`, `Unauthorized`, `InvalidPackageName`, `InvalidParameters`, `Unavailable`, `MessageTooBig`, `InvalidTtl`, `InvalidDataKey`, `MissingRegistration`, `Uninstalled` - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`device`** `object` <[App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices)> **REQUIRED** Information about app users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `SEND_REJECTED` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example send rejected event body* ```json { "id": "00000169-4a14-67b2-1ddd-d9e733622c3a", "occurred": "2019-03-04T19:00:45.106Z", "offset": "1000001260057", "processed": "2019-03-04T19:00:47.094Z", "type": "SEND_REJECTED", "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS", }, "body": { "variant_id": 1, "push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e", "status": "BadDeviceToken", "campaigns" : { "categories" : ["hello", "first message"] } } } ``` --- ## Short link click event {#short-link-click} Occurs when a user taps or "clicks" an Airship-shortened link in an SMS or MMS message. [Jump to examples ↓](#short-link-click-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`properties`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`original_url`** `string` **REQUIRED** The URL represented by the Airship-shortened link. - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`device`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`attributes`** `object` **OBJECT PROPERTIES** - **`web_user_agent_string`** `string` Describes the web user agent for the audience member who used the link. - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The MSISDN of the audience member who clicked the link. - **`device_type`** `string` **REQUIRED** Possible values: `SMS` - **`identifiers`** `object` **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender of the message. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `SHORT_LINK_CLICK` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example short_link_click event* ```json { "id": "31549b7d-a435-4b04-abca-69bfd4fb6aaa", "offset": "1000005313850", "occurred": "2019-07-10T23:18:57.465Z", "processed": "2019-07-10T23:18:58.148Z", "device": { "channel": "ec71312b-42e4-4bcd-b742-581a84941793", "device_type": "SMS", "delivery_address": "15551234567", "identifiers": { "sender": "15558647425" }, "attributes": { "web_user_agent_string": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/75.0.3770.100 Safari\/537.36" } }, "body": { "push_id": "f4b4201a-70e2-4a8d-bc8f-f35ddfa7d0e7", "group_id": "47f01bbf-2efa-4743-acd8-fd1023a36744", "properties": { "original_url": "api/connect#schemas-short_link_click" } }, "type": "SHORT_LINK_CLICK" } ``` --- ## Subscription event {#subscription} `SUBSCRIPTION` events reflect changes to users' subscription preferences — reflected in opt_in and opt_out values. These events help you track a user's subscription status in the system and the total number of subscribers. {{< note >}} These events appear in the stream whenever a user changes their opted_in or opted_out dates, which may not be meaningful in all cases; a user may opt into an email list on which they're already a member. {{< /note >}} [Jump to examples ↓](#subscription-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Determines the source of the subscription event. `registration` and `create_and_send` events result in changes to `opted_in` dates; all other event types contain `opted_out` dates. * `registration`: Represents a change to a user's `commercial_opted_in`, `transactional_opted_in`, `click_tracking_opted_in`, or `open_tracking_opted_in` dates. * `create_and_send`: A user's opted_in status changed as a result of a [Create and Send](/docs/guides/audience/segmentation/bulk-sending/) event. * `bounce`: Subscription status changed as a result of a bounce event. * `list_unsubscribe`: The user clicked the `unsubscribe` button in their email client. * `link_unsubscribe`: The user clicked an `unsubscribe` hyperlink in an email. * `spam_complaint`: The user classified an email as spam. * `out_of_band`: A bounce occurred after the recipient MTA accepted an email. Possible values: `registration`, `create_and_send`, `bounce`, `list_unsubscribe`, `link_unsubscribe`, `spam_complaint`, `out_of_band` - **`identifiers`** `object` **REQUIRED** Contains address information specific to the `channel_id` specified in the event. **OBJECT PROPERTIES** - **`address`** `string` The email address representing the change. - **`subscription_lists`** `object` Changes to a device or user's subscription list membership. **OBJECT PROPERTIES** - **`canceled`** `array[string]` An array of subscription list IDs which were canceled. Present only when a cancellation occurred. - **`enrolled`** `array[string]` An array of subscription list IDs which were enrolled. Present only when an enrollment occurred. - **`scope`** `string` The scope at which the operation was performed; only present on events which target a Named User. Possible values: `app`, `web`, `email`, `sms` - **`properties`** `object` **OBJECT PROPERTIES** - **`click_tracking_opted_in`** `string` Format: `date-time` - **`click_tracking_opted_out`** `string` Format: `date-time` - **`commercial_opted_in`** `string` Format: `date-time` - **`commercial_opted_out`** `string` Format: `date-time` - **`open_tracking_opted_in`** `string` Format: `date-time` - **`open_tracking_opted_out`** `string` Format: `date-time` - **`transactional_opted_in`** `string` Format: `date-time` - **`transactional_opted_out`** `string` Format: `date-time` - **`device`** `object` **REQUIRED** Holds information about the email `device` (an individual email channel) the event occurred against. **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` **REQUIRED** The email address of the channel the event occurred against. - **`device_type`** `string` **REQUIRED** Email compliance events use the `EMAIL` device type. Possible values: `EMAIL` - **`named_user`** `string` The Named User that the channel is associated with; appears only if the channel is associated with a Named User. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `SUBSCRIPTION` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example subscription event* ```json { "id": "62f3b7ac-4048-4f22-a0b5-22c01ef172a9", "offset": "1000022265027", "occurred": "2019-04-01T13:00:23.186Z", "processed": "2019-04-01T13:00:23.456Z", "device": { "channel": "6b46c724-494b-4491-9fe7-1b903d266110", "device_type": "EMAIL", "delivery_address": "user+43679@urbanairship.com.sink.sparkpostmail.com" }, "body": { "event_type":"registration", "identifiers": { "address":"new.subscription@example.com" }, "properties":{ "commercial_opted_in":"2019-01-04T20:56:00.000Z", "transactional_opted_in":"2019-01-04T20:56:00.000Z", "click_tracking_opted_out":"2019-01-04T20:56:00.000Z", "open_tracking_opted_out":"2019-01-04T20:56:00.000Z" } }, "type": "SUBSCRIPTION" } ``` --- ## Subscription list event {#subscription-list} Occurs when subscription list enrollment changes for a device or user. [Jump to examples ↓](#subscription-list-examples) - **`body`** `object` **REQUIRED** Changes to a device or user's subscription list membership. **OBJECT PROPERTIES** - **`canceled`** `array[string]` An array of subscription list IDs which were canceled. Present only when a cancellation occurred. - **`enrolled`** `array[string]` An array of subscription list IDs which were enrolled. Present only when an enrollment occurred. - **`scope`** `string` The scope at which the operation was performed; only present on events which target a Named User. Possible values: `app`, `web`, `email`, `sms` - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - **Web device information without `attributes`** `object` Information about web users in tag change events. - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`device_type`** `string` **REQUIRED** The platform that the channel is on. Possible values: `WEB` - **`named_user_id`** `string` The Named User identifier for the device. - [Device information for SMS and email]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#sms_email_devices) Information about the SMS or email device related to an event. - [Open channel device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#opendevices) Information about open channel users. - [Named User]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#nameduser) User information for events which occur at the user level. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `SUBSCRIPTION_LIST` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example Subscription List event* ```json { "id": "62f3b7ac-4048-4f22-a0b5-22c01ef172a9", "offset": "1000022265027", "occurred": "2019-04-01T13:00:23.186Z", "processed": "2019-04-01T13:00:23.456Z", "device": { "channel": "6b46c724-494b-4491-9fe7-1b903d266110", "device_type": "EMAIL", "delivery_address": "user+43679@urbanairship.com.sink.sparkpostmail.com" }, "user": { "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "mini_me" }, "body": { "enrolled": ["cool_deals"] }, "type": "SUBSCRIPTION_LIST" } ``` --- ## Tag change {#tag-change} Occurs when tags change for a device. [Jump to examples ↓](#tag-change-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`add`** `object` Tag group/tag pairs added to the device. Each tag group is an array containing one or more tags within this object. - **`current`** `object` The total set/state of tag group/tag pairs associated with the device after the tag change. Each tag group is an array containing one or more tags within this object. - **`remove`** `object` Tag group/tag pairs removed from the device. Each tag group is an array containing one or more tags within this object. - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - **Web device information without `attributes`** `object` Information about web users in tag change events. - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`device_type`** `string` **REQUIRED** The platform that the channel is on. Possible values: `WEB` - **`named_user_id`** `string` The Named User identifier for the device. - [Device information for SMS and email]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#sms_email_devices) Information about the SMS or email device related to an event. - [Open channel device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#opendevices) Information about open channel users. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `TAG_CHANGE` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example tag change event* ```json { "id": "00000169-4a14-67b2-1ddd-d9e733622c3a", "occurred": "2019-03-04T19:00:45.106Z", "offset": "1000001260057", "processed": "2019-03-04T19:00:47.094Z", "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS", }, "user": { "contact_id": "6b5ca2a2-c1f1-4119-9617-2d5bff0db09d", "named_user_id": "mini_me" }, "body":{ "add": { "crm": [ "partner", "active" ], "loyalty": [ "silver_member" ] }, "remove": { "device": [ "shoe_buyer" ] }, "current": { "crm": [ "partner", "active", "new_user" ], "loyalty": [ "silver_member", "special_offers" ], "device": [ "san_francisco", "sports" ] } }, "type": "TAG_CHANGE" } ``` --- ## Uninstall {#uninstall} Occurs when a user uninstalls an Airship-integrated app in response to a push. [Jump to examples ↓](#uninstall-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`decay`** `boolean` **REQUIRED** If true, Airship recorded an uninstall event due to user inactivity. - **`device`** `object` **REQUIRED** **One of:** - [App device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#appdevices) Information about app users generated by the SDK. - [Web device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#webdevices) Information about web users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `UNINSTALL` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example uninstall event* ```json { "id": "00000169-4a14-67b2-1ddd-d9e733622c3a", "occurred": "2019-03-04T19:00:45.106Z", "offset": "1000001260057", "processed": "2019-03-04T19:00:47.094Z", "type": "UNINSTALL", "device": { "ios_channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "channel": "1ef235f0-03d5-1384-893e-a19b5cd0d110", "device_type": "IOS", }, "body":{ "decay": false }, "type": "UNINSTALL" } ``` --- ## Web click event {#web-click} Occurs when a user interacts with a web notification, e.g., clicked or tapped it. Web Click events have a device attribute on the event indicating the channel that was the target of the notification. The body of a Web Click Event is an associated push object. [Jump to examples ↓](#web-click-examples) - **`body`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> **REQUIRED** The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` **REQUIRED** Information about web users generated by the SDK. **OBJECT PROPERTIES** - **`attributes`** `object` **OBJECT PROPERTIES** - **`iana_timezone`** `string` The time zone of the device. - **`push_opt_in`** `string` **REQUIRED** Indicates whether or not the device is opted into push notifications. - **`ua_sdk_version`** `string` **REQUIRED** The version of the Airship SDK used in the app. - **`web_browser_name`** `string` **REQUIRED** The name of the browser running the SDK. - **`web_browser_type`** `string` **REQUIRED** Indicates whether the browser was running on a desktop or mobile device. - **`web_browser_version`** `string` **REQUIRED** The version of the browser. - **`web_user_agent_string`** `string` **REQUIRED** The user agent reported by the browser. - **`channel`** `string` **REQUIRED** The unique, platform-agnostic channel identifier for a device. - **`device_type`** `string` **REQUIRED** The platform that the channel is on. Possible values: `WEB` - **`named_user_id`** `string` The Named User identifier for the device. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `WEB_CLICK` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example web click event* ```json { "id": "c91efbfa-14b1-401a-9002-54730b5cdcda", "offset": "1000024775634", "occurred": "2019-04-05T20:11:36.696Z", "processed": "2019-04-05T20:11:37.179Z", "device": { "channel": "bd054c5b-d614-46a1-a843-6ca330c66489", "device_type": "WEB", "attributes": { "web_browser_type": "desktop", "push_opt_in": "true", "iana_timezone": "America/Los_Angeles", "locale_country_code": "US", "locale_timezone": "-25200", "web_browser_version": "chrome-73", "locale_language_code": "en", "web_browser_name": "chrome", "ua_sdk_version": "1.1.0", "web_user_agent_string": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36" } }, "body": { "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06" }, "type": "WEB_CLICK" } ``` --- ## Web session event {#web-session} Occurs when an opted in user begins interacting with a website. Web Session events have a device attribute, indicating the channel associated with the user. [Jump to examples ↓](#web-session-examples) - **`body`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`last_delivered`** `object` Identifies the last push notification the audience received before the event. Absent if the last push occurred more than 12 hours ago. **OBJECT PROPERTIES** - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`time`** `string` The UTC time when the push occurred. - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). - **`session_id`** `string` Represents the "session" of user activity. Absent if the application was initialized while backgrounded. Format: `uuid` - **`triggering_push`** `object` <[Associated push]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#associatedpush)> The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. - **`device`** `object` <[Web device information]({{< ref "/developer/rest-api/connect/schemas/device-information/" >}}#webdevices)> **REQUIRED** Information about web users generated by the SDK. - **`id`** `string` **REQUIRED** Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` **REQUIRED** When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` **REQUIRED** When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` **REQUIRED** Possible values: `WEB_SESSION` - **`user`** `object` <[User]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#user)> The current state of the user when the event is emitted, including the contact ID and an optional named user ID. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example web session event* ```json { "id": "c91efbfa-14b1-401a-9002-54730b5cdcda", "offset": "1000024775634", "occurred": "2019-04-05T20:11:36.696Z", "processed": "2019-04-05T20:11:37.179Z", "device": { "channel": "bd054c5b-d614-46a1-a843-6ca330c66489", "device_type": "WEB", "attributes": { "web_browser_type": "desktop", "push_opt_in": "true", "iana_timezone": "America/Los_Angeles", "locale_country_code": "US", "locale_timezone": "-25200", "web_browser_version": "chrome-73", "locale_language_code": "en", "web_browser_name": "chrome", "ua_sdk_version": "1.1.0", "web_user_agent_string": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36" } }, "body": { "session_id": "e8350094-dd62-4d36-a7a0-f1b0a221de93", "last_delivered": { "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06" } }, "type": "WEB_SESSION" } ``` --- # JSON Predicates > Provides a flexible language for expressing custom filtering of your event stream. ## Array matcher {#array-matcher} Determines if an array contains an object that matches another criteria. [Jump to examples ↓](#array-matcher-examples) **One of:** - **`array_contains`** `object` The JSON Predicate. - **`array_contains`** `object` The JSON Predicate. - **`index`** `number` The specified element in the array. Format: `integer` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example find only push body objects with the campaign category "spring_sale"* ```json { "filters": { "types": ["PUSH_BODY"], "predicates": { "key": "categories", "scope": ["body", "campaigns"], "value": { "array_contains": { "value": {"equals": "spring_sale"} } } } } } ``` --- ## Equals matcher {#equals-matcher} Determines if the value matches exactly. [Jump to examples ↓](#equals-matcher-examples) - **`equals`** `object` **One of:** - `boolean` - `number` - `string` - `array` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example find SMS delivery errors with equals matcher* ```json { "filters": [ { "device_types": ["sms"], "types": ["CUSTOM"], "predicates": [ { "and": [ { "key": "interaction_type", "scope": ["body"], "value": {"equals": "delivery_report"} }, { "not": { "key": "name", "scope": ["body"], "value": {"equals": "delivered"} } } ] } ] } ] } ``` --- ## JSON Predicate {#json-predicate} [Standard request filters](/docs/developer/rest-api/connect/schemas/others/#eventsrequestfilters) check specific, predefined fields in your events and remove any events that don't match the criteria for that field. For example, the `device_types` filter always checks the `device_type` sub-field of the device object. In contrast, you can use JSON Predicates to examine any part of an event, providing more flexibility than the standard filters. You can also combine multiple JSON Predicate objects to create complex filtering logic for your event stream. The simplest JSON Predicate examines a single key and provides a `matcher` object that can be applied to the value at that key. To filter a stream for only [Open events](/docs/developer/rest-api/connect/schemas/events/#open), you could use the standard filter `types`: `filters:{"types": ["OPEN"]}`. However, to achieve this with a JSON Predicate, you would use `filters:{"predicates":{"key":"type", "value": {"equals": "OPEN"}}}`. This checks the value of the top-level key `type` to see if it's exactly "OPEN". It also serves as a foundational step for constructing more intricate filters. To filter for only Android events, you could use the `device_type` filter, but a JSON Predicate allows for more complex combinations later. Since the device type key doesn't appear at the top level of the event, you'll need to provide a scope, like this `filters:{"predicates":{"scope":["device"], "key":"device_type", "value": {"equals": "ANDROID"}}}`. This configuration targets the `device_type` key within the `device` object, checking if its value is "ANDROID". You can combine the two filters to see only Opens from Android devices: `filters:{"predicates":{"and":[ {"scope":["device"], "key":"device_type", "value": {"equals": "ANDROID"}}, {"key":"type", "value": {"equals": "OPEN"}} ]}}` We also have matchers other than `equals`. Numeric `at_least` and `at_most` can be combined to create ranges. `version_matches` uses [Ivy syntax](https://ant.apache.org/ivy/history/2.1.0/settings/version-matchers.html) to match version numbers. `is_present` determines if there's any value at a given key. `array_contains` can be combined with another predicate to determine if an array contains an object that matches another criteria. [Jump to examples ↓](#json-predicate-examples) **One of:** - **And** `object` - **`and`** `array` <[JSON Predicate]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#json_predicate)> - **Or** `object` - **`or`** `array` <[JSON Predicate]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#json_predicate)> - **Not** `object` - **`not`** `object` The JSON Predicate. - **Value** `object` - **`key`** `string` **REQUIRED** The name of the value being matched. - **`scope`** `object` The path into a JSON object. **One of:** - `string` - `array` - **`value`** `object` **REQUIRED** The value you are filtering for in the JSON Predicate. **One of:** - [Array matcher]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#array_matcher) Determines if an array contains an object that matches another criteria. - [Equals matcher]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#equals_matcher) Determines if the value matches exactly. - [Numeric matcher]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#numeric_matcher) Determines if a number matches or is within range of the criteria. - [Presence matcher]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#presence_matcher) Determines if there is any value for a given key. - [Version matcher]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#version_matcher) Determines if version numbers match. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example JSON Predicate to filter the stream to only Android Open events* ```json { "filters": { "predicates": { "and": [ { "scope": ["device"], "key": "device_type", "value": {"equals": "ANDROID"} }, { "key": "type", "value": {"equals": "OPEN"} } ] } } } ``` --- ## Numeric matcher {#numeric-matcher} Determines if a number matches or is within range of the criteria. [Jump to examples ↓](#numeric-matcher-examples) **One of:** - **`at_least`** `number` - **`at_most`** `number` - **`at_least`** `number` - **`at_most`** `number` **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example find custom events with name "purchase" and a "value" of at least 100* ```json { "filters": [ { "types": ["CUSTOM"], "predicates": [ { "and": [ { "key": "value", "scope": ["body"], "value": {"at_least": 100} }, { "key": "name", "scope": ["body"], "value": {"equals": "purchase"} } ] } ] } ] } ``` --- ## Presence matcher {#presence-matcher} Determines if there is any value for a given key. [Jump to examples ↓](#presence-matcher-examples) - **`is_present`** `boolean` If `true`, the value should be present. If `false`, the value should not be present. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example find only direct open events* ```json { "filters": { "types": ["OPEN"], "predicates": { "key": "triggering_push", "scope": ["body"], "value": {"is_present": true} } } } ``` --- ## Version matcher {#version-matcher} Determines if version numbers match. [Jump to examples ↓](#version-matcher-examples) - **`version_matches`** `string` The version number string to be matched. Format strings using [Ivy syntax](https://ant.apache.org/ivy/history/2.1.0/settings/version-matchers.html). **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example find custom events of type "purchase" performed by Android users on app versions between 18.4.1 and 19.2.3* ```json { "filters": [ { "device_types": ["android"], "types": ["CUSTOM"], "predicates": [ { "and": [ { "key": "app_version", "scope": ["device", "attributes"], "value": {"version_matches": "[18.4.1,19.2.3]"} }, { "key": "name", "scope": ["body"], "value": {"equals": "purchase"} } ] } ] } ] } ``` --- # SMS compliance events > Contains event body information specific to SMS compliance events. ## SMS API initiated opt-in event {#api-initiate-opt-in} Occurs when an SMS user is registered via the [SMS Channel Registration API](/docs/developer/rest-api/ua/#operation-api-channels-sms-post) without an `opted_in` value — indicating that the user has initiated, but not completed, the registration process. While this event contains a `channel_id`, you cannot send messages to this channel until the associated user completes the opt-in process (indicated by a `mobile_opt_in` event). [Jump to examples ↓](#api-initiate-opt-in-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Indicates a registration was started via the Airship API without an opt-in date, and a message was sent to the end user with instructions on how to opt in. Possible values: `api_initiate_opt_in` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS API-initiated opt-in event* ```json { "id": "a11d6d6b-bdd1-4f3d-97d3-591993945425", "offset": "1000005312986", "occurred": "2019-07-10T17:11:48.923Z", "processed": "2019-07-10T17:11:49.151Z", "device": { "channel": "35eb0446-0c75-44ec-ba9e-81d7250e0e06", "device_type": "SMS" }, "body": { "event_type": "api_initiate_opt_in", "identifiers": { "sender": "18338647425", "msisdn": "15035508427" } }, "type": "COMPLIANCE" } ``` --- ## SMS carrier deactivation event {#carrier-deactivation} Occurs when an MSISDN is deactivated by a carrier. This event type does not contain additional `properties`. [Jump to examples ↓](#carrier-deactivation-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** The carrier deactivated the address. Possible values: `carrier_deactivation` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS carrier_deactivation event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "carrier_deactivation", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" } }, "type": "COMPLIANCE" } ``` --- ## SMS Create and Send event {#smscreateandsend} An event that occurs for SMS channels used as a part of a [Create and Send](/docs/guides/audience/segmentation/bulk-sending/). [Jump to examples ↓](#smscreateandsend-examples) - **`body`** `object` **REQUIRED** Contains the event subtype and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Possible values: `create_and_send` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Properties for an SMS [Create and Send](/docs/guides/audience/segmentation/bulk-sending/) event. **OBJECT PROPERTIES** - **`channel_registered`** `boolean` **REQUIRED** If true, a new channel was created to represent the identifiers in the event. If false, the address was already registered to Airship. - **`opted_in`** `string` The date-and-time when the `msisdn` opted into messages from the `sender`. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS Create and Send event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "create_and_send", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "opted_in": "2018-12-03T19:31:10.000Z", "channel_registered": "true" } }, "type": "COMPLIANCE" } ``` --- ## SMS custom keyword response event {#custom-keyword-response} Occurs when a mobile-originated keyword is matched, and elicits a custom response. [Jump to examples ↓](#custom-keyword-response-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Occurs when a mobile-originated keyword generates a custom response. Possible values: `custom_keyword_response` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`inbound_message`** `string` The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the `keyword` if present. - **`outbound_message`** `string` The message you sent to the user represented in the event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS custom keyword response event* ```json { "id": "34464823-b48c-4ed3-8849-03933f29d057", "offset": "1000005313855", "occurred": "2019-07-11T00:24:39.203Z", "processed": "2019-07-11T00:24:40.128Z", "device": { "channel": "ec71312b-42e4-4bcd-b742-581a84941793", "device_type": "SMS", "delivery_address": "15035508427", "identifiers": { "sender": "18338647425" } }, "body": { "event_type": "custom_keyword_response", "identifiers": { "sender": "18338647425", "msisdn": "15035508427" }, "properties": { "inbound_message": "coupon", "outbound_message": "Thanks! Here is your coupon! https:\/\/wallet-api.urbanairship.com\/v1\/pass\/adaptive\/M1kTVOcyXm" } }, "type": "COMPLIANCE" } ``` --- ## SMS mobile create channel event {#mobile-create-channel} If a channel does not exist for the MSISDN/sender combination and your account is configured to create a channel if none exists in such instances, we will emit this event. The resulting channel will necessarily be opted out, awaiting an opt-in action by the user. [Jump to examples ↓](#mobile-create-channel-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Indicates that a channel for the `sms` event type was created. Possible values: `mobile_create_channel` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`opted_in`** `string` The date and time when the channel was registered. - **`registration_type`** `string` Indicates that the channel was registered with Airship. Possible values: `create` - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS mobile_create_channel event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "mobile_create_channel", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "inbound_message": "JOIN", "outbound_message": "Your order number is #123456789. Text 'JOIN' to learn about new offers from us.", "keyword": "JOIN" } }, "type": "COMPLIANCE" } ``` --- ## SMS mobile keyword matched event {#mobile-keyword-matched} Occurs when a mobile-originated message contains a recognized keyword. [Jump to examples ↓](#mobile-keyword-matched-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Occurs when a mobile-originated event contains a recognized keyword. Possible values: `mobile_keyword_matched` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`inbound_message`** `string` The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the `keyword` if present. - **`keyword`** `string` Indicates that a mobile-originated message contained a recognized keyword. - **`outbound_message`** `string` The message you sent to the user represented in the event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS mobile_keyword_matched event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "mobile_keyword_matched", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "inbound_message": "join", "outbound_message": "Wanna join the club?", "keyword": "JOIN" } }, "type": "COMPLIANCE" } ``` --- ## SMS mobile keyword unmatched event {#mobile-keyword-unmatched} Occurs when a mobile-originated message *does not* contain a recognized keyword. [Jump to examples ↓](#mobile-keyword-unmatched-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Occurs when a mobile-originated event does not contain a recognized keyword. Possible values: `mobile_keyword_unmatched` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`inbound_message`** `string` The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the `keyword` if present. - **`outbound_message`** `string` The message you sent to the user represented in the event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS mobile_keyword_unmatched event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "mobile_keyword_unmatched", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "inbound_message": "@%#!&@&#", "outbound_message": "Wanna join the club?" } }, "type": "COMPLIANCE" } ``` --- ## SMS mobile opt in event {#mobile-opt-in} Occurs when a user opts in to text messages via a keyword. [Jump to examples ↓](#mobile-opt-in-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Indicates that the event represents a newly registered address. Possible values: `mobile_opt_in` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`inbound_message`** `string` The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the `keyword` if present. - **`keyword`** `string` The keyword the user sent to opt in. - **`outbound_message`** `string` The message you sent to the user represented in the event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS mobile_opt_in event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "mobile_opt_in", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "inbound_message": "y", "outbound_message": "Do you want to get text alerts from us?", "keyword": "Y" } }, "type": "COMPLIANCE" } ``` --- ## SMS mobile opt out event {#mobile-opt-out} Occurs when a user sends a MO message that matches a keyword with an opt-out action. If present, this event would supplant a `mobile_keyword_matched` event. [Jump to examples ↓](#mobile-opt-out-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** The event represents a user who opted out of notifications. Possible values: `mobile_opt_out` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`inbound_message`** `string` The body of the inbound (to Airship) text message. This is the message a user sent to opt into or out of messages. This text corresponds to the `keyword` if present. - **`keyword`** `string` Indicates that the user responded to opt out of messages. The enumerated values represent default keywords, but any custom keywords that you configure to allow mobile opt-outs can also appear here. Possible values: `STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT`, `ARRET` - **`outbound_message`** `string` The message you sent to the user represented in the event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS mobile_opt_out event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663" }, "body": { "event_type": "mobile_opt_out", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "inbound_message": "STOP", "outbound_message": "Text STOP to opt out of text messages from us.", "keyword": "STOP" } }, "type": "COMPLIANCE" } ``` --- ## SMS mobile terminated message event {#mobile-terminated-message} Occurs when Airship sends an SMS message to a user. The message represented by this event could be a response to an individual mobile-originated (MO) message, or a message initiated from the Airship UI/API. [Jump to examples ↓](#mobile-terminated-message-examples) - **`body`** `object` **REQUIRED** Contains the Compliance event subtype and properties specific to the event subtype. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Airship has emitted a mobile-terminated message. Possible values: `mobile_terminated_message` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS mobile_terminated_message event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS" }, "body": { "event_type": "mobile_terminated_message", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" } }, "type": "COMPLIANCE" } ``` --- ## SMS opted out event {#opted-out} Occurs when a user is opted out of an SMS audience via the Airship API, i.e., not via an opt-out keyword. This event type does not contain additional `properties`. [Jump to examples ↓](#opted-out-examples) **All of:** - **`device`** `object` Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. - **`id`** `string` Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same `id`, `type`, `occurred`, `device`, and `body` values but different `offset` and `processed` values. You should use the `id` to deduplicate. - **`occurred`** `string` When the event occurred. - **`offset`** `string` **REQUIRED** An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason. - **`processed`** `string` When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed. - **`type`** `string` Compliance events are the only types of events returned by this event stream. Possible values: `COMPLIANCE` - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** The address opted out of notifications. Possible values: `opted_out` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS opted_out event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663", "identifiers": { "sender": "15558675309" } }, "body": { "event_type": "opted_out", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" } }, "type": "COMPLIANCE" } ``` --- ## SMS registration event {#smsregistered} Occurs when a user opts in to receive SMS messages from you, via a call to the [SMS registration API](/docs/developer/rest-api/ua/#operation-api-channels-sms-post). [Jump to examples ↓](#smsregistered-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Indicates that the event represents a newly registered address. Possible values: `registration` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`opted_in`** `string` **REQUIRED** The ISO 8601 date-time (UTC) when the channel opted-in to notifications. - **`registration_type`** `string` **REQUIRED** Indicates whether the channel was created or updated. Possible values: `create`, `update` - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS registration event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS" }, "body": { "event_type": "registration", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "opted_in": "2018-12-03T19:31:10.000Z", "registration_type": "create" } }, "type": "COMPLIANCE" } ``` --- ## SMS uninstalled event {#sms-uninstalled} Occurs when the [SMS uninstall API](/docs/developer/rest-api/ua/#operation-api-channels-sms-uninstall-post) is called. [Jump to examples ↓](#sms-uninstalled-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** The address was uninstalled. Possible values: `uninstall` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS uninstalled event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663", "identifiers": { "sender": "15558675309" } }, "body": { "event_type": "uninstall", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" } }, "type": "COMPLIANCE" } ``` --- ## SMS update event {#smsupdated} When an SMS event update occurs. [Jump to examples ↓](#smsupdated-examples) - **`body`** `object` **REQUIRED** Contains the event subtype, identifiers, and additional properties about the event. **OBJECT PROPERTIES** - **`event_type`** `string` **REQUIRED** Indicates that the event represents a newly registered address. Possible values: `registration` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains properties specific to the `event_type`. **OBJECT PROPERTIES** - **`opted_in`** `string` **REQUIRED** The ISO 8601 date-time (UTC) when the channel opted-in to notifications. - **`registration_type`** `string` **REQUIRED** Indicates the channel was updated. Possible values: `update` - **`device`** `object` **REQUIRED** Holds information about an SMS `device` (an individual SMS channel). **OBJECT PROPERTIES** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`delivery_address`** `string` The phone number for the channel. Format: `msisdn` - **`device_type`** `string` **REQUIRED** SMS compliance events use the `SMS` device type. Possible values: `SMS` - **`identifiers`** `object` If present, the `identifiers` object holds the value for the `sender` property. **OBJECT PROPERTIES** - **`sender`** `string` **REQUIRED** The sender that the `delivery_address` received a message from. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example SMS update event* ```json { "id": "a7086338-0473-46fe-8d9b-cb61305c3c0d", "offset": "1000000701505", "occurred": "2018-12-03T19:31:10.000Z", "processed": "2018-12-03T19:31:11.302Z", "device": { "channel": "a828de17-b315-4e80-9d2d-35a906afeacf", "device_type": "SMS", "delivery_address": "15558968663", "identifiers": { "sender": "15558675309" } }, "body": { "event_type": "registration", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "registration_type": "update" } }, "type": "COMPLIANCE" } ``` --- # User information > Contains information about the user that is associated with a given event. ## Contact {#contact} Contact information associated with the device at the time the event occurs. - **`contact_id`** `string` **REQUIRED** The Contact identifier for the device. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- ## User {#user} The current state of the user when the event is emitted, including the contact ID and an optional named user ID. - **`contact_id`** `string` The Contact identifier for the device. - **`named_user_id`** `string` The Named User identifier for the device. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- # Additional Schemas > Schemas that are not grouped by a specific tag. These include core data objects and shared schemas used across multiple operations. ## Associated push {#associatedpush} The specific `push_id` and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation. An associated push object may specify a `time`, if the push was a singular operation sent at a defined time. Otherwise, the object will include a `group_id` if the push was sent at a relative time (`best_time` or `local_time`) an automation pipeline, or another operation resulting in multiple `push_id`s. [Jump to examples ↓](#associatedpush-examples) - **`campaigns`** `object` An object listing the campaigns a push specification is associated with. The campaigns object includes an array of categories that must have between 1 and 10 elements, each of which is a string with a 64-byte and -character limit. **OBJECT PROPERTIES** - **`categories`** `array[string]` - **`group_id`** `string` Identifies a push specification delivered over an interval of time, e.g., multiple push_ids as part of the fulfillment of an automation pipeline or a push-to-local-time specification. Format: `uuid` - **`push_id`** `string` **REQUIRED** A unique identifier for a push operation. Format: `uuid` - **`time`** `string` The UTC time when the push occurred. - **`variant_id`** `integer` The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment). **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Push sent to an audience at a defined date-time* ```json { "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828", "time": "2015-07-30T21:03:37.631Z" } ``` --- ## Compliance request {#compliancerequest} A request for compliance events is much like a request to `/api/events`, but has a limited scope. - **`filters`** `array` <[Compliance request filters]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#compliancerequestfilters)> An array of filter objects defining the events you want to appear in the event stream. - **`resume_offset`** `string` The offset where the stream should begin. The offset is an identifier relevant only to the data stream. The first event in the stream will be the next element satisfying the filter and subset conditions with an offset field greater than this value. Only specify `resume_offset` if `start` is absent. - **`start`** `string` Specifies that the stream should start at the beginning or the end of the application's data window. Only specify `start` if `resume_offset` is absent. Possible values: `EARLIEST`, `LATEST` - **`subset`** `object` <[Request subset]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#subset)> Use subsets to return a proportion of the event stream and not all events meeting your other criteria. The `subset` object defines the proportion of the event stream that you want to return. **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) --- ## Compliance request filters {#compliancerequestfilters} [Jump to examples ↓](#compliancerequestfilters-examples) - **`device_types`** `array[string]` Returns events pertaining to devices on the specified platforms. Possible values: `email`, `sms` - **`latency`** `integer` The number of milliseconds between the current time and when the events you want to return occurred. If an event occurred more than `latency` milliseconds ago, it is filtered out of the event stream. Format: `milliseconds` **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) **Examples** *Example compliance request filter* ```json { "device_types": ["email"], "latency": 120000, } ``` --- ## Events request {#eventsrequest} The request body defines the events you want to return in the event stream. You can define position, subset and filter specifications in each request submitted to the stream. Filters are positive statements about what events the client should return. The subset specification returns a representative portion of the stream. - **`filters`** `array` <[Request filters]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#eventsrequestfilters)> An array of filter objects defining the events you want to see in the event stream. A filter object defines a function that either passes or fails an event. Events are included in the response if they pass any of the functions defined by the objects in the array. - **`resume_offset`** `string` The offset where the stream should begin. The offset is an identifier relevant only to Real-Time Data Streaming. The first event in the stream will be the next element satisfying the filter and subset conditions with an offset field greater than this value. Only specify `resume_offset` if `start` is absent. - **`start`** `string` Specifies that the stream should start at the beginning or the end of the application's data window. Only specify `start` if `resume_offset` is absent. Possible values: `EARLIEST`, `LATEST` - **`subset`** `object` <[Request subset]({{< ref "/developer/rest-api/connect/schemas/others/" >}}#subset)> Use subsets to return a proportion of the event stream and not all events meeting your other criteria. The `subset` object defines the proportion of the event stream that you want to return. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) --- ## In-app context {#in-app-context} The context provides the view state when a button, pager, or form interaction occurs. [Jump to examples ↓](#in-app-context-examples) - **`reporting_context`** `object` Describes the content types of the in-app automation. Can be expanded to provide any data for reporting. **OBJECT PROPERTIES** - **`content_types`** `array[string]` Possible values: `scene`, `survey` - **`state`** `object` Can contain the current view state of pager and form. **OBJECT PROPERTIES** - **`form`** `object` **OBJECT PROPERTIES** - **`form_identifier`** `string` **REQUIRED** Is the form controller identifier. Format: `uuid` - **`response_type`** `string` The type survey response type. Possible values: `nps`, `user_feedback` - **`submitted`** `boolean` **REQUIRED** True if the form has been submitted. - **`type`** `string` The form type. Possible values: `nps`, `form` - **`pager`** `object` **OBJECT PROPERTIES** - **`completed`** `boolean` True if the user reached the end of the pager. - **`identifier`** `string` **REQUIRED** Is the pager controller identifier. Format: `uuid` - **`page_count`** `number` **REQUIRED** Total number of pages. - **`page_identifier`** `string` **REQUIRED** The current page identifier. Format: `uuid` - **`page_index`** `number` **REQUIRED** Is the current pager index. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example in-app context* ```json { "reporting_context": { "content_types": [ "survey" ] }, "state": { "form": { "form_identifier": "870db95f-3715-4c98-8047-2871c175d003", "submitted": false, "type": "nps", "response_type": "nps" }, "pager": { "identifier": "9e051354-185b-4d4d-888a-885def2e6b7a", "page_identifier": "992e5540-7144-474c-b666-2671814b3b19", "page_index": 0, "page_count": 2, "completed": false } } ``` --- ## Mobile-originated SMS event {#mobile-originated-sms} An event that occurs when a user sends a message from an SMS device, i.e., the message originates from a mobile device and not from the server (Airship). This event contains context related to the message's origin, the incoming message itself, and Airship's response to the origin. [Jump to examples ↓](#mobile-originated-sms-examples) - **`event_type`** `string` **REQUIRED** The specific `MOBILE_ORIGINATED` event that occurred. Possible values: `mobile_originated_sms` - **`identifiers`** `object` **REQUIRED** Contains the sender and MSISDN for the event. **OBJECT PROPERTIES** - **`msisdn`** `string` **REQUIRED** The phone number of the user involved in the compliance event. - **`sender`** `string` **REQUIRED** The phone number or short code of the sender involved in the compliance event. - **`properties`** `object` **REQUIRED** Contains the mobile-originated message itself and the response to the message. **OBJECT PROPERTIES** - **`inbound_message`** `string` **REQUIRED** The contents of the message received from an SMS device. - **`keyword`** `string` The specific keyword used in the inbound message, if recognized; the keyword in the `inbound_message` determines the `outbound_message` sent to the device. If a keyword could not be matched in the `inbound_message`, this field is absent. - **`outbound_message`** `string` **REQUIRED** The response sent to the SMS device, based on the inbound message and keyword. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example mobile_originated_sms event body* ```json { "event_type": "mobile_originated_sms", "identifiers": { "sender": "15558675309", "msisdn": "15558968663" }, "properties": { "inbound_message": "join", "outbound_message": "Thanks for joining!", "keyword": "join" } } ``` --- ## Request filters {#eventsrequestfilters} An array of filter objects defining the events you want to see in the event stream. A filter object defines a function that either passes or fails an event. Events are included in the response if they pass any of the functions defined by the objects in the array. [Jump to examples ↓](#eventsrequestfilters-examples) - **`device_types`** `array[string]` Returns events pertaining to devices on the specified platforms. Possible values: `android`, `ios`, `amazon`, `web`, `email`, `sms`, `open` - **`devices`** `array` Limits the stream to events relating to specific device attributes. **Any of:** - **`channel`** `string` The unique, platform-agnostic channel identifier for a device. - **`named_user_id`** `string` The Named User for a device. The event stream will return events pertaining to the Named User. - **`latency`** `integer` The number of milliseconds between the current time and when the events you want to return occurred. If an event occurred more than `latency` milliseconds ago, it is filtered out of the event stream. Format: `milliseconds` - **`notifications`** `object` Limits the stream to events related to one or more specific pushes. This allows you to easily track the events generated by a given push or pipeline. In this object, you should only specify one of `push_id` or `group_id`. Child pushes may be included in the returned stream. If they are, they will have a Group ID relating them back to the push to local time or automation specification that spawned them. **One of:** - **Push ID** `object` - **`push_id`** `string` The push you want to return events for. - **Group ID** `object` - **`group_id`** `string` The group you want to return events for. - **`predicates`** `array[object]` <[JSON Predicate]({{< ref "/developer/rest-api/connect/schemas/json-predicates/" >}}#json_predicate)> Limits events to a subset of the event payload. - **`types`** `array[string]` Specifies the [event](/docs/developer/rest-api/connect/schemas/events/) types you want to return in the event stream. Possible values: `ATTRIBUTE_OPERATION`, `CLOSE`, `COMPLIANCE`, `CONTACT_CHANGE`, `CONTROL`, `CUSTOM`, `FEATURE_FLAG_INTERACTION`, `FIRST_OPEN`, `FIRST_OPT_IN`, `IN_APP_BUTTON_TAP`, `IN_APP_EXPERIENCES`, `IN_APP_FORM_DISPLAY`, `IN_APP_FORM_RESULT`, `IN_APP_MESSAGE_CONTROL`, `IN_APP_MESSAGE_DISPLAY`, `IN_APP_MESSAGE_EXCLUSION`, `IN_APP_MESSAGE_EXPIRATION`, `IN_APP_MESSAGE_RESOLUTION`, `IN_APP_PAGE_SWIPE`, `IN_APP_PAGE_VIEW`, `IN_APP_PAGER_COMPLETED`, `IN_APP_PAGER_SUMMARY`, `LABEL_EVENT`, `LOCATION`, `MOBILE_ORIGINATED`, `OPEN`, `PUSH_BODY`, `REGION`, `RICH_CONTROL`, `RICH_DELETE`, `RICH_DELIVERY`, `RICH_READ`, `SCREEN_VIEWED`, `SEND`, `SEND_ABORTED`, `SEND_REJECTED`, `SHORT_LINK_CLICK`, `SUBSCRIPTION`, `SUBSCRIPTION_LIST`, `TAG_CHANGE`, `UNINSTALL`, `WEB_CLICK`, `WEB_SESSION` - **`users`** `array` Limits the stream to events relating to specific users. **Any of:** - [Contact]({{< ref "/developer/rest-api/connect/schemas/user-information/" >}}#contact) Contact information associated with the device at the time the event occurs. - **`named_user_id`** `string` The Named User for a user object. The event stream will return events pertaining to the Named User. **Used in:** - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Example filter* ```json { "device_types": ["ios"], "latency": 120000, "notifications": {"push_id": "fae0658c-930e-4f66-bc78-80f46222bc8c"}, "types": ["OPEN", "SEND"], "devices": [{"named_user_id": "VIP Customer"}] } ``` ```json { "device_types": ["ios"], "latency": 120000, "notifications": {"push_id": "af03151e-5ad5-4e30-bbd2-bda28312b3c7"}, "types": ["RICH_READ"], "users": [{"named_user_id": "best_customer"}] } ``` ```json { "device_types": ["ios"], "latency": 300, "notifications": {"push_id": "6626393d-5d42-4de5-a31d-e24e819876ac"}, "types": ["CLOSE"], "users": [{"contact_id": "982B35f2-0375-6384-893e-a19b5cd5R771"}] } ``` *Example Predicate filter* ```json { "predicates": [ { "and": [ { "key": "type", "value": { "equals": "CUSTOM" } }, { "scope": "body", "key": "name", "value": { "equals": "initial_open" } } ] } ] } ``` --- ## Request subset {#subset} Use subsets to return a proportion of the event stream and not all events meeting your other criteria. The `subset` object defines the proportion of the event stream that you want to return. [Jump to examples ↓](#subset-examples) - **`count`** `integer` Required when the `type` is `PARTITION`. The value is the number of partitions you want to divide the event stream into. - **`proportion`** `number` Required when the `type` is `SAMPLE`. Specifies the percentage of events that will appear in the response, chosen randomly. Min: 0, Max: 1 Format: `float` - **`selection`** `integer` Required when the `type` is `PARTITION`. The value is the partition that you want to return in the response. Must be less than `count`. - **`type`** `string` The type of partition. * `SAMPLE` returns a random sample of events; the sample `proportion` determines the fraction of total events that Real-Time Data Streaming returns. * `PARTITION` segments the event stream into a number of partitions (determined by `count`) and returns a single partition in the event stream (determined by `selection`). Possible values: `SAMPLE`, `PARTITION` **Used in:** - [Open a compliance event stream]({{< ref "/developer/rest-api/connect/operations/compliance-event-stream/" >}}#opencomplianceeventstream) - [Open an event stream]({{< ref "/developer/rest-api/connect/operations/event-stream/" >}}#openeventstream) **Examples** *Subset `SAMPLE`* ```json { "type": "SAMPLE", "proportion": 0.1 } ``` *Subset `PARTITION`* ```json { "type": "PARTITION", "count": 10, "selection": 0 } ``` --- ## Server Libraries Server libraries for using the Real-Time Data Streaming API. # RTDS Java Library > Java library for using the Airship Real-Time Data Streaming API.## Resources * [Github Repo](https://github.com/urbanairship/connect-java-library/) * [Maven Central](https://mvnrepository.com/artifact/com.urbanairship/connect-client) * [RTDS API Reference](https://www.airship.com/docs/developer/rest-api/connect/) ## Installation Add the library using Maven by adding the following lines to your pom.xml: ```xml com.urbanairship connect-client VERSION ``` The client library provides all the components you need to consume a mobile event stream. ### Max strength encryption policy RTDS requests with this client may experience SSL handshake failures unless using the **Java Cryptography Extension (JCE) Unlimited Strength** package cipher suite. If you encounter a generic connection failure `java.lang.RuntimeException`, the max strength encryption policy might be the culprit, and you should ensure this JCE Unlimited Strength package is installed on your system. Use the package that corresponds to your JRE version: - [JCE Unlimited Strength Jurisdiction Policy Files 7](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html) - [JCE Unlimited Strength Jurisdiction Policy Files 8](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html) **These files are not required for JRE 9 or for JRE 8u151 or newer.** ## Getting started The following sections provide information for setting up, consuming, and filtering the stream, ### Setting up the stream To set up the stream for consumption, first set the `Creds`, and then create a `StreamQueryDescriptor` and use the descriptor to create a `Stream`. **Configure the stream** ```java Creds creds = Creds.newBuilder() .setAppKey("key") .setToken("token") .build(); StreamQueryDescriptor descriptor = StreamQueryDescriptor.newBuilder() .setCreds(creds) .build(); ``` ### Consuming the stream After the steam is configured, it can be consumed. **Example stream that disconnects after 60 seconds** ```java final Stream stream = new Stream(descriptor, Optional.absent()); final ScheduledExecutorService scheduledExecutorService = Executors.newScheduledThreadPool(1); Runnable stopConsuming = new Runnable() { public void run() { try { stream.close(); } catch (Exception e) { e.printStackTrace(); } finally { scheduledExecutorService.shutdown(); } } }; scheduledExecutorService.schedule(stopConsuming, 60, TimeUnit.SECONDS); while (stream.hasNext()) { String event = stream.next(); System.out.println("Event: " + event); } ``` ### Filtering the stream The following shows various filters and stream customizations: **Filters and customization example** ```java Optional startPosition = Optional.fromNullable(StartPosition.relative(StartPosition.RelativePosition.EARLIEST)); DeviceFilter device1 = new DeviceFilter(DeviceFilterType.ANDROID_CHANNEL, "152d00c3-c49c-4172-88ce-539c511cf346"); DeviceFilter device2 = new DeviceFilter(DeviceFilterType.IOS_CHANNEL, "67fa2bad-9e83-4259-b925-bc08c184f72e"); DeviceFilter device3 = new DeviceFilter(DeviceFilterType.NAMED_USER_ID, "cool_user"); NotificationFilter notification = new NotificationFilter(NotificationFilter.Type.GROUP_ID, "58179035-dd1f-4b04-b023-5035c6335786"); Filter filter = Filter.newBuilder() .setLatency(20000000) .addDevices(device1, device2, device3) .addDeviceTypes(DeviceType.ANDROID, DeviceType.IOS) .addNotifications(notification) .addEventTypes("OPEN") .build(); Subset subset = Subset.createSampleSubset(0.3f); StreamQueryDescriptor descriptor = StreamQueryDescriptor.newBuilder() .setCreds(creds) .addFilters(filter) .setSubset(subset) .build(); final Stream stream = new Stream(descriptor, startPosition); ``` `Filter`, `Subset`, and `DeviceFilter` can also be applied to a stream to retrieve whatever information wanted. # RTDS Node Library > Node library for using the Airship Real-Time Data Streaming API.## Resources * [GitHub Repo](https://github.com/urbanairship/node-connect-client) * [Node Package Manager (npm)](https://www.npmjs.com/package/urban-airship-connect) ## Installation Install using `npm`: ```bash npm install urban-airship-connect ``` ## Example usage **Basic usage example** ```javascript var connect = require('urban-airship-connect') var connectStream = connect('appKey', 'authToken') connectStream.on('data', function (data) { // will be called with each event }) // write to the stream to set filters/offset/start connectStream.write({start: 'LATEST'}) ``` # RTDS Python Library > Python library for using the Airship Real-Time Data Streaming API.## Resources * [Github Repo](https://github.com/urbanairship/connect-python-library) * [Python Package Index (PyPI)](https://pypi.python.org/pypi/uaconnect) * [RTDS API Reference](https://www.airship.com/docs/developer/rest-api/connect/) ## Installation Install using `pip`: ```bash pip install uaconnect ``` ## Usage The following sections describe various usage information for the [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds) (RTDS) API. ### RTDS Event Consumer To consume standard events from the RTDS API, instantiate an ``EventConsumer`` object with the application key, access token, and an [offset recorder](#offset-recorders). You can then open the connection and start reading events. **Create an event consumer** ```python >>> import uaconnect >>> consumer = uaconnect.EventConsumer( ... app_key='application_key', ... access_token='access_token', ... recorder=uaconnect.FileRecorder('.offset')) >>> consumer.connect() >>> for event in consumer.read(): ... if event is None: ... continue >>> print("Got event: {}".format(event)) >>> consumer.ack(event) ``` ### RTDS Compliance Event Consumer To consume [compliance events](https://www.airship.com/docs/developer/rest-api/connect/operations/compliance-event-stream/) from the RTDS API, instantiate a ``ComplianceConsumer`` object with the application key, master secret and an offset recorder. You can then open the connection and start reading events. **Create a compliance event consumer** ```python >>> import uaconnect >>> consumer = uaconnect.EventConsumer( ... app_key='application_key', ... master_secret='master_secret', ... recorder=uaconnect.FileRecorder('.offset')) >>> consumer.connect() >>> for event in consumer.read(): ... if event is None: ... continue >>> print("Got event: {}".format(event)) >>> consumer.ack(event) ``` ### Alternate Data Center Support When instantiating an ``EventConsumer`` or ``ComplianceConsumer``, you can pass the optional `url` argument to explicitly specify the data center your project is located in. Possible values are `US`, `EU`, or an arbitrary base URL in the form of `http://domain.xyz/`. The library will build the URL path properly from there. If no `url` is specified, `US` is used. **EU example** ```python >>> import uaconnect >>> consumer = uaconnect.EventConsumer( ... app_key='application_key', ... master_secret='master_secret', ... url='EU', ... recorder=uaconnect.FileRecorder('.offset')) ``` ### Offset Recorders Offset recorders inherit from the abstract base class `uaconnect.Recorder`, implementing `read_offset` and `write_offset` methods. One recorder is included in the library, `FileRecorder`, which stores the offset on disk. In the `uaconnect.ext.redisrecorder` package there is an example implementation of using a Redis instance to store the offset. `ack` calls should be placed depending on whether in a failure scenario your app wishes to possibly replay an already handled event or risk dropping one. For the latter, call ``ack`` as soon as the event is read. For the former, call `ack` only after the event has been fully handled. ### Advanced Options When Connecting Airship Real-Time Data Streaming supports a variety of options when connecting to make sure that you're only consuming the data that you want. `uaconnect` makes it easy to use these connection parameters and filters. #### Specifying Offsets One of the advantages of RTDS is that you can resume from a specific place in the stream. This is done by specifying the ``offset`` that's associated with the event. While ``uaconnect`` automatically tracks offsets for you with ``uaconnect.FileRecorder``, you can also explicitly set an offset. **Set a particular offset** ```python >>> import uaconnect >>> recorder = uaconnect.FileRecorder(".offset") # or wherever you would like the file to exist >>> recorder.write_offset("8865499359") # a randomly chosen offset >>> recorder.read_offset() '8865499359' ``` An alternative here is to just write the offset explicitly into the file or whatever `Recorder` subclass you're using to track offsets. **Check the offset** ```bash cat .offset 886549935 ``` Now, the next time you connect, it will pick up from that last offset. If you'd like to manually set the offset for a connection to a known value instead of the recorder's offset, set `resume_offset` like so: **Resume from a particular offset** ```python >>> consumer.connect(resume_offset='123456789') ``` #### Using filters Filters are a powerful way of filtering what specific information you'd like to see from the RTDS stream. You can filter by event type, device type, latency on an event, or even specific devices or notifications. Here's a brief example on how to use filters with `uaconnect`: **Filter example** ```python >>> import uaconnect >>> consumer = uaconnect.EventConsumer( ... app_key='application_key', ... access_token='access_token', ... recorder=uaconnect.FileRecorder('.offset') ... ) >>> f = uaconnect.Filter() >>> f.types("PUSH_BODY", "SEND") # only receive PUSH_BODY and SEND events. >>> consumer.add_filter(f) >>> consumer.connect() ```