Connect API Reference

Scroll down for code samples, example requests and responses.

Urban Airship Connect 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.

The stream of events is delivered over HTTP. In order to consume the events, you must issue a request which includes the authentication, a starting point for the stream, and optional filter and subset specifications.

The event data is delivered as newline-delimited JSON, with each event on its own line. 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 Connect, Urban Airship stores 7 days or 100GB worth of data, whichever comes first.

Base URL

Authentication

  • HTTP Authentication

    bearer
    The authorization header containing your Bearer token, which can be obtained from Urban Airship. Tokens may be revoked at will.

Event Stream

Connect has a single endpoint, opening an event stream to your filter specifications.

Open an Event Stream

Connect Request

POST /api/events/ HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <appkey>
Content-length: 923
Accept: application/vnd.urbanairship+x-ndjson; version=3

{
   "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"
   }
}

Example Response

Status: 200
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"}}
POST /api/events

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, Connect will never end the response without some external reason.

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, then simply omit the attribute. If an unexpected attribute appears on an event, a status code 400 response will be returned.

Security:

Request Parameters

  • X-UA-Appkey header

    StringRequired

    The App Key for the app you want to return events from.

    The application key.

  • Content-length header

    IntegerRequired

    The size of the request.

Request Body

application/json

Type: Object

The request body defines the events you want to return in the even stream. You define a 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 permits clients to process a representative portion of the stream.

  • filters

    Request FiltersOptional

    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

    StringOptional

    The offset at which to start streaming. The offset is an identifier relevant only to Connect. The first element in the returned stream will be the next element satisfying the filter and subset conditions with an offset field greater than resume_offset. Only specify resume_offset if start is absent.

  • start

    StringOptional

    Specifies that the stream should start at the beginning or the end of the application’s data window. Only specify one of 'resume_offset' and 'start.'

    Possible values: EARLIEST, LATEST.

  • subset

    Request SubsetOptional

    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.

Response

  • 200 OK

    Everything is OK. The resulting response is an event stream meeting request criteria.

    Response Body

    application/vnd.urbanairship+x-ndjson; version=3

    Type: Response Event Stream

    The response to a successful HTTP request is an unending stream of newline delimited JSON. 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, Connect will continue to write to it. 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 on 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.

  • 402 Payment Required

    Like other UA applications, Connect supports a limited number of simultaneous connections. If you exceed this number, you may recieve this response.

  • 404 Not Found

    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.

Data Formats

Event Body

Most event types have specific information about the event included in the body object. The following schemas represent the different types of events described by the body object.

Close Event

Example Close Event

{
   "session_id": "fdc88529-bb09-4cee-b3ba-0f60ee5e33a1"
}

Type: Object

An event generated whenever a user closes the app. Because close events pertain to a particular device, the Device Information field will also be present. Note that close events are often latent, as they may not be delivered over the network until the next time the mobile application activates.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

Control Event

Example Control Event

{
  "push_id": "c91d9e1b-605f-4bad-a45d-cdf3e6e0773f",
  "group_id": "3eec7de4-4b19-436e-ad15-88278f9ddb82"
}

Type: Object

Occurs when a device was excluded from a push because it was arbitrarily selected to form part of the control group in an experiment (A/B Test). The behavior of users of the device serves as an indication of what would have happened without any intervention at all.

  • campaigns

    ObjectOptional

    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.

    • categories

      Array<String>Optional
  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

Custom Event

Example Custom Event (Shoe Sale)

{
   "name": "shoe-purchase",
   "value": 60.000000,
   "interaction_type": "Landing Page",
   "interaction_id": "d01d0380-da2e-11e3-8519-90e2ba299b38",
   "customer_id": "George@hotmail.com",
   "transaction": "Selling all the shoes",
   "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": {
      "custom_value": "value_123",
      "ltv": false,
      "category": "womens_shoes",
      "id": 1267,
      "description": "plaid canvas",
      "brand": "hipster",
      "new_item": true
   },
   "source": "SDK"
}

Type: Object

An event body representing custom events that are either emmitted from the UA SDK or submitted via our Custom Events API. If the source of the custom event is SDK, a Device Information attribute will be present on the parent object.

  • customer_id

    StringOptional

    An external customer-side id, such as an email address. Absent if empty.

  • interaction_id

    StringOptional

    An Urban Airship identifier uniquely identifying the interaction. May be absent.

  • interaction_type

    StringOptional

    The type of interaction as set by the UA SDK. Values determine whether the interaction triggered an event from the message center (ua_mcrap), a landing page (ua_landing_page), or an interactive notification (ua_interactive_notification).

    Possible values: ua_mcrap, ua_landing_page, ua_interactive_notification.

  • last_delivered

    Associated PushOptional

    Identifies last push the device received before firing this custom event. Absent if the last push occurred more than thirty days ago.

  • name

    StringOptional

    A plain-text name given to the event.

    Pattern: ^[a-z0-9_\-]+$.

  • properties

    ObjectOptional

    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

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

  • source

    StringOptional

    The event source. SDK indicates an event sent from the UA SDK. API indicates an event created by request against the [Server Side Custom Events API]{{< relref "api/ua/#server-side-custom-events" >}}.

    Possible values: SDK, API.

  • transaction

    StringOptional

    If the event is one in a series representing a single transaction, use the value in this field to tie events together.

  • triggering_push

    Associated PushOptional

    The push that caused the custom event. Absent if a causal relationship to a push cannot be established.

  • value

    NumberOptional

    Populated if the event is associated with a count or amount. Urban Airship treats this field as a representation of money. The value field respects six digits of precision to the right of the decimal point.

In-App Message Display Event

Example In-App Message Display Event

{
   "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"
   }
}

Example In-App Message Display Event Defined by App

{
   "app_defined_id": "avocado",
   "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e",
}

Type: Object

Occurs when an in-app message is displayed to a user. Because the event pertains to a specific device, the device information object will be populated.

  • app_defined_id

    StringOptional

    An identifier defined by the application if the In-App Message was created by the application logic, not the UA system. If this field is present, the event body will not contain push_id, group_id, variant_id, or triggering_push fields.

  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

  • triggering_push

    Associated PushOptional

    Appears if the user begain the current session by opening a push notification.

  • variant_id

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

In-App Message Expiration Event

Example In-App Message Expiration Event

{
   "push_id": "2f1e5e0c-cff4-4979-b032-fc83f59a1c5c",
   "time_sent": "2015-08-12T11:06:33.937Z",
   "type": "EXPIRED",
   "time_expired": "2015-08-12T19:06:33.937Z"
}

Example In-App Message Expiration Event

{
   "app_defined_id": "avocado",
   "type": "EXPIRED",
   "time_expired": "2015-08-12T19:06:33.937Z"
}

Type: Object

Occurs when a new 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.

  • app_defined_id

    StringOptional

    An identifier defined by the application if the In-App Message was created by the application logic, not the UA system. If this field is present, the event body will not contain push_id, group_id, variant_id, or triggering_push fields.

  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • replacing_push

    Associated PushOptional

    An Associated Push object for the In-App Message that replaced the message. Present if type is REPLACED.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

  • time_expired

    StringOptional

    The date-time when the message was set to expire.

    Format: date-time.

  • time_sent

    StringOptional

    The date-time when the in-app message payload was sent to the device.

    Format: date-time.

  • triggering_push

    Associated PushOptional

    Appears if the user begain the current session by opening a push notification.

  • type

    StringOptional

    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 it’s 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 Urban 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

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

In-App Message Resolution Event

Example In-App Message Resolution Event

{
   "push_id": "86ee0a6e-a46a-4bbe-a3d1-804891baaee4",
   "group_id": "68991b8d-0d6b-4e05-bc62-2cdec2085c18",
   "time_sent": "2015-08-12T11:06:33.937Z",
   "type": "BUTTON_CLICK",
   "button_id": "yes",
   "button_description": "Yes",
   "button_group": "ua_yes_no_background",
   "duration": 10000000000
}

Example In-App Message Resolution Event Defined by App

{
   "app_defined_id": "avocado",
   "type": "BUTTON_CLICK",
   "button_id": "yes",
   "button_description": "Yes",
   "button_group": "ua_yes_no_background",
   "session_id": "cfe467a6-ca70-40dd-8c1f-07b2f644935e",
   "duration": 10000000000
}

Type: Object

Occurs when an In-App Message was cleared from the display, either by timeout or user action. Because this event pertains to an individual device, the device information object will be present.

  • app_defined_id

    StringOptional

    An identifier defined by the application if the In-App Message was created by the application logic, not the UA system. If this field is present, the event body will not contain push_id, group_id, variant_id, or triggering_push fields.

  • button_description

    StringOptional

    The title of the button the user interacted with. Present if type is set to BUTTON_CLICK.

  • button_group

    StringOptional

    A category associated with the message. Present if type is set to BUTTON_CLICK.

  • button_id

    StringOptional

    A unique identifier for the button. Present if type is set to BUTTON_CLICK.

  • duration

    IntegerOptional

    The number of milliseconds that the user was on the screen.

  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

  • time_sent

    StringOptional

    The date-time when the in-app message payload was sent to the device.

    Format: date-time.

  • triggering_push

    Associated PushOptional

    Appears if the user begain the current session by opening a push notification.

  • type

    StringOptional

    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

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

Location Event

Example Response

{
   "latitude": "51.5033630",
   "longitude": "-0.1276250",
   "foreground": true,
   "session_id": "ecd3741d-92c4-469b-b42c-888e40a121d3"
}

Type: Object

An event declaring the device to be at a particular latitude and longitude.

  • foreground

    BooleanOptional

    If true, the application was foregrounded when the event occured.

  • latitude

    StringOptional

    The latitude where the event occurred.

  • longitude

    StringOptional

    The longitude where the event occurred.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

Open Event

Example Open Event

{
   "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: Object

Occurs when a user opens an application. The open event is specific to a device, so the Device Information field will be populated.

  • last_delivered

    Associated PushOptional

    An associated push object, specifying the last push the device received before firing the Open event. Absent if the last push occurred more than thirty days ago.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

  • triggering_push

    Associated PushOptional

    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.

Push Body

Example Push Body Event

{
   "push_id": "233f8109-bf56-4d95-a8bf-6f28e9d270a4",
   "campaigns": {
      "categories": [
         "hello",
         "numberwang",
         "first message"
      ]
   },
   "trimmed": false,
   "payload": "eyJkZXZpY2VfdHlwZXMiOiBbImFuZHJvaWQiLCAiaW9zIl0sICJub3RpZmljYXRpb24iOiB7ImFuZHJvaWQiOiB7fSwgImlvcyI6IHsiYmFkZ2UiOiAiKzEifSwgImFsZXJ0IjogIklUIFdJTEwgV09SSyEifSwgImF1ZGllbmNlIjogImFsbCJ9"
}

Type: Object

Event body specific to a push. Because push events pertain to many devices, the device key-value pair will be absent. Urban 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.

  • campaigns

    ObjectOptional

    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.

    • categories

      Array<String>Optional
  • group_id

    StringOptional

    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

    StringOptional

    The specification of the push as sent via the API, a Base64 encoded JSON value.

  • push_id

    StringRequired

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • resource

    StringOptional

    Describes the type of push, helping you interpret the JSON response. Values pertain to the push "type".

    Possible values: PIPELINES, SCHEDULES, PUSH, EXPERIMENTS.

  • trimmed

    BooleanOptional

    If true, the push payload was trimmed from the event body.

Region Event

Example Region Event

{
   "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: Object

Region Events are emitted when a device enters or exits a geofence or the range of any of a set of bluetooth beacons. We currently only expose region events for customers using our Gimbal integration. Events for Gimbal customers include the Gimbal application instance identifer as com.urbanairship.gimbal.aii within the identifiers object. See Device Information to learn about identifiers.

  • action

    StringOptional

    Indicates whether the event was the result of a user entering or exiting the region.

    Possible values: enter, exit.

  • name

    StringOptional

    A friendly name for the event; may be retrieved from a third-party.

  • region_id

    StringOptional

    The identifier for the region in Urban Airship.

    Format: uuid.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

  • source_info

    ObjectOptional

    Information about the source application that generated the event.

    • region_id

      StringOptional

      The unique region identifier from the originating system.

    • source

      StringOptional

      Identifies the system that the event originated from.

Rich Delete Event

Example Event Body - Indicates the push_id That Was Deleted

{
  "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828",
  "time": "2015-07-30T21:03:37.631Z"
}

Type: Object

Occurs when a user delets a rich push message from their inbox.

  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • variant_id

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

Rich Delivery Event

Example Event Body — Indicates the push_id That Reached the User

{
  "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828",
  "time": "2015-07-30T21:03:37.631Z"
}

Type: Object

An event generated when a rich push message has been delivered to a device’s Message Center. This a device-specific event, so the Device Information field will be populated.

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 Urban Airship system. The push identifier is the primary identifier for events associated with a rich push.

  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • variant_id

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

Rich Read Event

Example Event Body — Indicates the push_id That the User Read

{
  "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828",
  "time": "2015-07-30T21:03:37.631Z"
}

Type: Object

Occurs when a rich push message in an inbox is read by a user. This a device specific event, so the Device Information field will be populated.

  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • variant_id

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

Screen Viewed Event

Type: Object

A Screen Viewed event indicates that 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 deterimine the user’s path by filtering on the fields in the table below.

  • duration

    IntegerOptional

    The number of milliseconds that the user was on the screen.

  • previous_screen

    StringOptional

    The name assigned to the screen the user was on prior to the viewed_screen.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

  • viewed_screen

    StringOptional

    The name assigned to the screen that the user left.

Send Event

Example Send Event

{
   "variant_id": 1,
   "push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e",
   "alerting": true,
   "campaigns": {
      "categories": [
         "hello",
         "numberwang",
         "first message"
      ]
   }
}

Type: Object

Occurs for each notification sent to a device identified in the audience selection of a push. Send events map a device to a push, so the Device Information field will be present in the parent object.

  • alerting

    BooleanOptional

    If true, the send event was alerting. Alerting send event has notification text, badge, or sound.

  • campaigns

    ObjectOptional

    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.

    • categories

      Array<String>Optional
  • group_id

    StringOptional

    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

    StringOptional

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • variant_id

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

Tag Change Event

Example Tag Change Event

{
   "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: Object

Occurs when tags change for a device. Because tag changes are related to a device, they will have a device field. Predictive Churn Tags and Device Property Tags are set automatically by Urban Airship. Read more in our Tag Groups Walkthrough.

  • add

    ObjectOptional

    Tag group/tag pairs added to the device. Each tag group is an array containing one or more tags within this object.

  • current

    ObjectOptional

    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

    ObjectOptional

    Tag group/tag pairs removed from the device. Each tag group is an array containing one or more tags within this object.

Uninstall Event

Example Uninstall Event

{
   "decay": false
}

Type: Object

Occurs when a push provider notifies Urban Airship that the application has been uninstalled in response to a push or user inactivity. Uninstall events pertain to a particular device, so the Device Information field will be populated.

  • decay

    BooleanOptional

    If true, Urban Airship recorded an uninstall event due to user inactivity.

Web Click Event

Example Web Click Event

{
    "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06"
}

Type: Associated Push

Occurs when user interacts with a web notification, e.g. clicked on 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

Example Web Session Event

{
    "session_id": "e8350094-dd62-4d36-a7a0-f1b0a221de93",
    "last_delivered": {
        "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06"
    }
}

Type: Object

Occurs when an opted in user begins interacting with a website. Web Session events have a device attribute, indicating which channel is associated with the user.

  • last_delivered

    Associated PushOptional

    identifies the last web notification delivered to the channel associated with the user who started the session. We will not include web notifications older than 30 days.

  • session_id

    StringOptional

    Represents the “session” of user activity. Absent if the application was initialized while backgrounded.

    Format: uuid.

Associated Push

Push Sent to an Audience at a Defined date-time

{
  "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828",
  "time": "2015-07-30T21:03:37.631Z"
}

Push Event Fullfilled at a Relative Time (local/best-time) or as a Part of a Grouped Operation

{
  "push_id": "6e3339ce-529c-42e4-a2f6-7546f81c9828",
  "time": "2015-07-30T21:03:37.631Z"
}

Type: Object

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

  • campaigns

    ObjectOptional

    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.

    • categories

      Array<String>Optional
  • group_id

    StringOptional

    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

    StringRequired

    A unique identifier for a push operation. Present if the push body defines a push scheduled for a single point in time.

    Format: uuid.

  • time

    StringOptional

    The UTC time when the push occured.

    Format: date-time.

  • variant_id

    StringOptional

    The ID of the variant that a push is associated with, if the push was a part of an A/B test (experiment).

    Format: uuid.

Device Information

Example Device Information Object

{
    "channel": "a6b392d6-3b0d-4c00-98ef-5cb91d51268a",
    "device_type": "IOS",
    "named_user_id": "Albert",
    "identifiers": {
      "com.urbanairship.idfa": "9D55CAC8-79E3-4567-8A99-8465B7A12868",
      "com.urbanairship.gimbal.aii": "c5720f06-516a-4b91-b7bb-53523fc43a3d",
      "cid": 123554,
      "com.urbanairship.limited_ad_tracking_enabled": "false"
    },
    "attributes": {
      "package_name": "com.company_name.app_name",
      "version": "1.0.0",
      "ua_library": "7.0.2"
    }
  }

Type: Object

Information about the device related to an event is defined in this object. Not every event has device information associated with it. If an event is not associated with device information, this object is absent.

  • attributes

    ObjectOptional

    Optional information about the device, app, and/or browser pertaining to the event.

    • app_package_name

      StringOptional

      A unique identifier for the app name.

    • app_version

      StringOptional

      The version of the app.

    • background_push_enabled

      StringOptional

      Indicates whether or not the device has background push notifications enabled.

    • carrier

      StringOptional

      The wireless carrier used by the device.

    • connection_type

      StringOptional

      The internet connection type used by the device.

      Possible values: WIFI, CELL, WIMAX, NONE.

    • device_model

      StringOptional

      The device model.

    • device_os

      StringOptional

      The device operating system.

    • iana_timezone

      StringOptional

      The time zone of the device.

    • locale_country_code

      StringOptional

      The ISO-3166-1 country code as defined in device settings.

    • locale_language_code

      StringOptional

      The ISO-639-1 two-letter language code reflecting the language that the device is set to.

    • locale_timezone

      StringOptional

      The device's timezone offset in seconds from UTC.

    • locale_variant

      StringOptional

      The language variant

    • location_enabled

      StringOptional

      Indicates whether or not the device has location services enabled.

    • location_permission

      StringOptional

      • 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

      StringOptional

      Indicates whether or not the device is opted into push notifications.

    • ua_sdk_version

      StringOptional

      The version of the Urban Airship SDK used in the app.

    • web_browser_name

      StringOptional

      The name of the browser running the SDK.

    • web_browser_type

      StringOptional

      Indicates whether the browser was running on a desktop or mobile device.

    • web_browser_version

      StringOptional

      The version of the browser.

    • web_user_agent_string

      StringOptional

      The user agent reported by the browser.

  • channel

    StringOptional

    the channel identifier

  • device_type

    StringOptional

    The platform that the channel is on.

    Possible values: IOS, ANDROID, WEB, EMAIL, AMAZON, OPEN.

  • identifiers

    ObjectOptional

    Contains identifiers specified by the app.

    • com.urbanairship.aaid

      StringOptional

      Android/Amazon ad identifier

      Format: uuid.

    • com.urbanairship.gimbal.aii

      StringOptional

      Gimbal application instance identifier

      Format: uuid.

    • com.urbanairship.idfa

      StringOptional

      Apple ad identifier

      Format: uuid.

    • com.urbanairship.limited_ad_tracking_enabled

      BooleanOptional

      If true, the user has enabled limited ad tracking.

    • com.urbanairship.vendor

      StringOptional

      Apple vendor identifier

      Format: uuid.

  • named_user_id

    StringOptional

    the named user identifier for the device.

  • open_platform_name

    StringOptional

    If device_type is set to OPEN, this field shows the full name of the platform.

Response Event Stream

Example Response Object

{
   "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
   }
}

Type: Object

The response to a successful HTTP request is an unending stream of newline delimited JSON. 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, Connect will continue to write to it. 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 on 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.

  • associatedPush

    Associated PushOptional

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

  • body

    ObjectOptional

    Most event types have type specific information included in the body. For some events, like First Open, all relevant information relevant occurs outside the body. For these event types, the body object is absent.

      One of:
    • Type: Push Body

      Event body specific to a push. Because push events pertain to many devices, the device key-value pair will be absent. Urban 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.

    • Type: Open Event

      Occurs when a user opens an application. The open event is specific to a device, so the Device Information field will be populated.

    • Type: Send Event

      Occurs for each notification sent to a device identified in the audience selection of a push. Send events map a device to a push, so the Device Information field will be present in the parent object.

    • Type: Control Event

      Occurs when a device was excluded from a push because it was arbitrarily selected to form part of the control group in an experiment (A/B Test). The behavior of users of the device serves as an indication of what would have happened without any intervention at all.

    • Type: Close Event

      An event generated whenever a user closes the app. Because close events pertain to a particular device, the Device Information field will also be present. Note that close events are often latent, as they may not be delivered over the network until the next time the mobile application activates.

    • Type: Rich Delivery Event

      An event generated when a rich push message has been delivered to a device’s Message Center. This a device-specific event, so the Device Information field will be populated.

      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 Urban Airship system. The push identifier is the primary identifier for events associated with a rich push.

    • Type: Rich Read Event

      Occurs when a rich push message in an inbox is read by a user. This a device specific event, so the Device Information field will be populated.

    • Type: Rich Delete Event

      Occurs when a user delets a rich push message from their inbox.

    • Type: Custom Event

      An event body representing custom events that are either emmitted from the UA SDK or submitted via our Custom Events API. If the source of the custom event is SDK, a Device Information attribute will be present on the parent object.

    • Type: Location Event

      An event declaring the device to be at a particular latitude and longitude.

    • Type: Tag Change Event

      Occurs when tags change for a device. Because tag changes are related to a device, they will have a device field. Predictive Churn Tags and Device Property Tags are set automatically by Urban Airship. Read more in our Tag Groups Walkthrough.

    • Type: Uninstall Event

      Occurs when a push provider notifies Urban Airship that the application has been uninstalled in response to a push or user inactivity. Uninstall events pertain to a particular device, so the Device Information field will be populated.

    • Type: Region Event

      Region Events are emitted when a device enters or exits a geofence or the range of any of a set of bluetooth beacons. We currently only expose region events for customers using our Gimbal integration. Events for Gimbal customers include the Gimbal application instance identifer as com.urbanairship.gimbal.aii within the identifiers object. See Device Information to learn about identifiers.

    • Type: Screen Viewed Event

      A Screen Viewed event indicates that 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 deterimine the user’s path by filtering on the fields in the table below.

    • Type: In-App Message Display Event

      Occurs when an in-app message is displayed to a user. Because the event pertains to a specific device, the device information object will be populated.

    • Type: In-App Message Resolution Event

      Occurs when an In-App Message was cleared from the display, either by timeout or user action. Because this event pertains to an individual device, the device information object will be present.

    • Type: In-App Message Resolution Event

      Occurs when an In-App Message was cleared from the display, either by timeout or user action. Because this event pertains to an individual device, the device information object will be present.

    • Type: Web Click Event

      Occurs when user interacts with a web notification, e.g. clicked on 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.

    • Type: Web Session Event

      Occurs when an opted in user begins interacting with a website. Web Session events have a device attribute, indicating which channel is associated with the user.

  • device

    Device InformationOptional

    Information about the device related to an event is defined in this object. Not every event has device information associated with it. If an event is not associated with device information, this object is absent.

  • id

    StringOptional

    Uniquely identifies an event. Connect 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

    StringOptional

    When the event occurred.

    Format: date-time.

  • offset

    StringOptional

    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

    StringOptional

    When the event was ingested by the Connect. There may be some latency between when the event occurred, and when it was processed.

    Format: date-time.

  • type

    StringOptional

    The type of event. This fields defines what the event means, whether the device and body key/value pairs will be present, and which attributes to expect in the body if it is present.

Request Filters

Device Filter

{
   "devices": [
       {
           "channel": "195adec2-fa70-4e62-b978-78ede2827597"
       },
       {
           "named_user_id": "George"
       }
   ]
}

Example Notification Filter - Include All Events Pertaining to a Push ID

{"push_id": "0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e"}

Example Notification Filter - Include All Events Pertaining to a Pipeline or PLT Push (Defined by Group ID)

{"group_id": "b7f7c9e0-64d6-4f44-9d74-d32ef5437ccf"}

Type: Array<Object>

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.

  • Type: Object

    • device_types

      Array<String>Optional

      Returns events pertaining to devices on the specified platform(s).

      Possible values: android, ios, amazon, web, email.

    • devices

      Array<Object>Optional

      Limits the stream to events relating to specific device attributes.

        • Any of:
        • Type: Object

          • channel

            StringOptional

            The unique, platform-agnostic channel identifier for a device. The event stream will return events pertaining to this device.

        • Type: Object

          • named_user_id

            StringOptional

            The named user for a device. The event stream will return events pertaining to the named user.

    • latency

      IntegerOptional

      The number of milliseconds between the current time and when the event(s) you want to return occured. If an event occurred more than latency milliseconds ago, it is filtered out of the event stream.

      Format: milliseconds.

    • notifications

      ObjectOptional

      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 PLT or automation specification that spawned them.

        One of:
      • Type: Object

        • push_id

          StringOptional

          The push you want to return events for.

      • Type: Object

        • group_id

          StringOptional

          The group you want to return events for.

    • types

      Array<String>Optional

      Specifies the event types you want to return in the event stream.

      Possible values: PUSH_BODY, OPEN, SEND, CONTROL, CLOSE, RICH_DELIVERY, RICH_READ, RICH_DELETE, CUSTOM, LOCATION, TAG_CHANGE, UNINSTALL, FIRST_OPEN, REGION, SCREEN_VIEWED, IN_APP_MESSAGE_DISPLAY, IN_APP_MESSAGE_RESOLUTION, IN_APP_MESSAGE_EXPIRATION, WEB_CLICK, WEB_SESSION.

Request Subset

Subset SAMPLE

{
  "type": "SAMPLE",
  "proportion": 0.1
}

Subset PARTITION

{
  "type": "PARTITION",
  "count": 10,
  "selection": 0
}

Type: Object

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.

  • count

    IntegerOptional

    Required when the type is PARTITION. The value is the number of partitions you want to devide the event stream into.

  • proportion

    NumberOptional

    Required when the type is SAMPLE. Specifies the percentage of events that will appear in the response, chosen randomly.

    Format: float. Max: 1.

  • selection

    IntegerOptional

    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

    StringOptional

    The type of partition, SAMPLE or PARTITION. * SAMPLE returns a random sample of events; the sample proportion determines the fraction of total events that Connect 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.