map-o file-code-o arrow-directionplatform-webreach-project-type-boarding-passreach-project-type-couponreach-project-type-event-ticketreach-project-type-genericreach-project-type-gift-cardreach-project-type-loyalty-cardreach-project-type-member-card pictures more_vert chain keyboard_arrow_down keyboard_arrow_right

Connect API Reference

Overview

Urban Airship Connect exposes a stream of events describing a user’s experience within a mobile application. Events reflect user action, automated device responses to their environment (e.g. encountering a beacon), and experience-changing actions initiated by application owners, such as sending a push notification.

The stream of events is delivered over HTTP. The consumer issues a request which includes the authentication, a starting point for the stream, and optional filter and subset specifications. The event data itself 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 application authorized to use Connect, UA stores 7 days or 100GB worth of data, whichever comes first.

Open Stream

Example Request:

POST /api/events/ HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <appkey>
Accept: application/vnd.urbanairship+x-ndjson; version=3
Content-length: 923
{
    "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": "1245",
    "subset": {
        "proportion": 0.3,
        "type": "SAMPLE"
    }
}
POST /api/events

Creates a new stream. 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.

Unlike our other APIs, a request to /api/events/ returns a stream of data, where each line is a JSON object.

In order to make a successful request against the Connect API, specify the following HTTP headers:

Request Headers

Authorization: Bearer <token>
Connect uses bearer HTTP authentication. The token is distributed by Urban Airship, and may be revoked at will. You must include an X-UA-Appkey header in order to authenticate.
X-UA-Appkey
Your application key.
Content-Length
The length of the incoming request.
Accept
The accept header should be set to application/vnd.urbanairship+x-ndjson; version=3; for a response in newline-delimited JSON format. No other formats are supported.

The above request specifies that the response should include events which start at the offset 1245 and which pass a coin flip that had a 30% chance of success, and which pass any of the following filters:

  • The event pertains to a device of the Android or Amazon platforms; and the device has channel identifiers matching 5b389366-7caf-43e2-a19c-6159c7ea9936, c8044c8a-d5fa-4e58-91d4-54d0f70b7409 or the device is mapped to the named user “George”; and the event is no older than twenty thousand seconds.

  • The event pertains to an automation or PLT push with a group identifier of a30abf06-7878-4096-9535-b50ac0ad6e8e, and was of the type “OPEN”

The request body defines which events to include in the returned stream. Users 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. Both define boolean conditions under which stream elements should be included.

In the request specification, JSON collection types have semantic meaning.

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

The request body has the following attributes:

JSON Parameters

resume_offset

(String) The offset at which to start streaming. The offset is an integer 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

(String) One of “EARLIEST” or “LATEST”. 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.

subset

(Object) Subset operations on the returned stream. Currently supports partitioning the stream or sampling from it. See Subsets.

filters

(Array of objects) An array of JSON objects defining whether to include an event based on its contents. See Filters.

You may specify one of resume_offset or start. If neither is specified, we default to a start value of “LATEST”. You may specify the subset attribute and the filters attributes. If both subset and filters are present, we first apply the filter specification, and then apply the subset specification to any event passing filters. See Filters and Subsets for more detail on these fields.

Filters

Example:

The following filter selects for events which match all of the following criteria:

  • Relate to an iOS devices.
  • Occurred in the last two minutes.
  • pertain to the push identified by “fae0658c-930e-4f66-bc78-80f46222bc8c”
  • Are of the “OPEN” or “SEND” type.
  • Match the named user: “Coolest User Ever.”
{
   "device_types": ["ios"],
   "latency": 120000,
   "notifications": {"push_id": "fae0658c-930e-4f66-bc78-80f46222bc8c"},
   "types": ["OPEN", "SEND"],
   "devices": [{"named_user_id": "Coolest User Ever."}]
}

You may want only want to know about events that match a certain criteria, which you can specify via an array of filter objects. A filter object defines a function which 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.

A filter object is a JSON object with at least one of the following attributes:

JSON Parameters

device_types

An array of devices types. Events pertaining to devices on any platform in the device types array will be included in the response. Valid array elements are: "ios", "android", "amazon"

notifications

An object. Specifies that events relating to a particular push should be included in the response. See Notifications Filter Attribute for more information.

devices

An array of objects. Indicates that events should be included in the response stream only if they relate to a device selected by any of the objects in the array. See Device Filter Attribute for more information.

types

An array of string event types. See Event Body for a description of the events returned for each type. The possible event types are: "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"

latency

An integer. The number of milliseconds between the current time and when the event occurred. If an event occurred more than latency milliseconds ago, it will not be included in the stream.

Notifications Filter Attribute

Examples:

Include all events pertaining to the push identified by 0c173744-dd35-4b5e-9f7f-2b7e0ce0e36e".

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

Include all events pertaining to the group (meaning automation pipeline or PLT push) defined by the group identifier b7f7c9e0-64d6-4f44-9d74-d32ef5437ccf

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

An array of notification objects.

A notification object limits the stream to events related to a single push. This would allow a customer to easily track the events generated by a given push or pipeline.

A notification object has one of the following attributes:

push_id
Indicates that those events associated with a Push ID should be included in the stream. Must specify at least one of group_id and push_id
group_id

Indicates that those events associated with a Group ID should be included in the stream.

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 which spawned them.

You should only specify one of push_id and group_id.

Device Filter Attribute

Examples:

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

An array of device objects. Device objects filter for events pertaining to particular devices.

Device objects have one or more of the following attributes:

named_user_id
(string) The named user identifier for the device.
channel
(string) The unique channel identifier for the device; platform agnostic.

Channel fields prepended with a platform-specific identifier, e.g., ios_channel, android_channel, amazon_channel will appear in your stream if specified. These keys are provided for backward compatibility and are deprecated in favor of channel.

The devices filter does not work with the custom identifiers listed under the "identifiers" key (see the Device Information section for details).

Subsets

An example SAMPLE subset specification:

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

This specifies the following filtering procedure: Pick a random float between 0 and 1. If the number is less than 0.1, write the event to the response stream.

An example PARTITION specification:

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

This specifies the following procedure: Partition the stream deterministically into ten partitions, and include those events which fall into the first partition. Streams can contain an extremely large amount of data. You may want a representative sample of the data, or you may wish to partition the data across multiple connections for distributed processing.

The subset specification defines pseudo-random or arbitrary selections of events in the stream.

The subset specification is a JSON object with the following attributes:

type
The type of partition. Currently supports two values “SAMPLE” and “PARTITION”. If “SAMPLE” is specified, a subset of the stream is randomly selected to return.
proportion
float between 0 and 1. Required if “type” is “SAMPLE”. Specifies what fraction of events should be written to the response, chosen randomly.
count
integer, required if “type” is “PARTITION”. Specifies how many partitions the stream should be divided into.
selection
integer, less than count. Required if “type” is “PARTITION”. Specifies which partition of the stream should be written to the response.


If there is a mismatch between the type and the other properties, a 400 response will be returned.

Response

The response to the HTTP a successful http request is an unending stream of newline delimited JSON. Each non-empty line in the response represents a single event.

Example Response:

Content-Type: application/vnd.urbanairship+ndjson; version=3;
Status: 200
Content-encoding: gzip

{"id" : "ff76bb85-74bc-4511-a3bf-11b6117784db", "type": "UNINSTALL", "offset": 1235, "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": 521035,"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"}}
{"id" : "ff76bb85-74bc-4511-a3bf-11b6117784db", "type": "UNINSTALL", "offset": 1235, "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"}}
...

This response body is of arbitrarily large size – so long as the connection is open, Connect will continue to write to it. It may write a new line character to the response to prevent the connection from idling. If you receive no data or new line characters for ninety seconds, close the connection and reconnect.

Urban Airship will occasionally add:

  • New properties to existing objects
  • New event types, which will be JSON objects with new values for the type field

You should be tolerant of these types of changes.

Status Codes

The connect API uses the following response status codes in specific ways:

Response Codes

200 OK
If everything is okay and an event stream follows.
307 TEMPORARY REDIRECT

The server may respond with this status code, and a "Set-Cookie: <stream leader hostname>". The client should then retry the POST with the additional header "Cookie: <stream leader hostname>". If you are still having trouble, see our getting started guide for more details.

402 PAYMENT REQUIRED

Each application has a limited number of simultaneous connections. If this number is exceeded, a 402 response code may be returned.

404 NOT FOUND

We have no data for the specified App key, because we have yet to ingress or generate any data for your app.

Stream Object

Each non-empty line in the response is a JsonObject which has the following attributes:

As an example of the fields defined on a stream object, let’s take a closer look at the second object from response example above:

{
   "id": "8e50350e-dd9f-41af-b98e-b0e5d4b27dea",
   "type": "SEND",
   "offset": 521035,
   "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"
   }
}
  • id (String) Uniquely identifies the event. Connect will occasionally send duplicate events. Duplicates events will have the same id, type, occurred, device, and body values. but will have different offsets and could have different processed fields. Clients should use the id field to deduplicate.
  • type (String) The type of the event. This fields defines what the event means, whether the device and body key/value pairs will be present, and which attributes to expect on the body if it is present. In the example to the right, the “type” field tells us that the JSON object represents a Send Event.

    As we make additional information available via Connect, undocumented events will appear in the stream. You should not build infrastructure atop undocumented events until they have been documented. Contact Support with any questions.

  • occurred An ISO 8601 datetime, in UTC, when the event occurred.
  • processed An ISO 8601 datetime, in UTC, when the event was ingested by the Connect system. There may be lag between when the event occurred, and when it was processed.
  • offset A numerical identifier of a location in the stream. Used to resume the stream after severing a connection. If a new connection is made with the offset value, the stream will resume with the next element in the stream. Clients should store this value for the case that the connection is severed.

    The same event may appear in the stream more than once with different offsets. You are responsible for de-duplicating events with the “id” field, if uniqueness is required for your application.

  • body See Event Body.
  • device See Device Information.

Device Information

{
  "channel": "a6b392d6-3b0d-4c00-98ef-5cb91d51268a",
  "device_type": "IOS",
  "named_user_id": "Albert",
  "identifiers": {
    "com.urbanairship.idfa": "9D55CAC8-79E3-4567-8A99-8465B7A12868",
    "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"
  }
}

Information pertaining to the device related to an event is defined under the “device” key in each response item.

Not every event has device information associated with it, e.g., a push event). For such events, the “device” key-value pair will be absent.

Device entries have one of following attributes:

channel
(String) The ID of the channel.
device_type
(String) The platform which the channel defines.
At present, this will be one of IOS, ANDROID, or AMAZON.

Although these fields do not appear in the examples, if the platform is one of IOS, ANDROID, or AMAZON, then the device objects will include one of ios_channel, android_channel or amazon_channel, in addition to a channel for a given channel ID.


The platform-specific keys are deprecated and provided for backward compatibility. You should use the platform-agnostic key channel in your integrations.


Device entries optionally have the following fields:

named_user_id
(String) The named user identifier for a device.
identifiers

(Object) A JSON object with identifiers specified by the app.

  • com.urbanairship.idfa

    (String) Apple ad identifier
  • com.urbanairship.aaid

    (String) Android/Amazon ad identifier
  • com.urbanairship.vendor

    (String) Apple vendor ID
  • com.urbanairship.limited_ad_tracking_enabled

    (Boolean) Represents whether user has enabled limited ad tracking or not.
attributes

(Object) A JSON object with the following fields, each of which is optional.

  • app_package_name

    (String) A unique identifier for the app name. For example,
  • "com.company_name.app_name".

  • app_version

    (String) Indicates the version of the application, e.g., "1.0.0".
  • ua_sdk_version

    (String) Indicates the version of the Urban Airship SDK used in building the application. For example, "7.0.2".
  • device_model

    (String) Indicates the device model.
  • device_os

    (String) Indicates the device os.
  • carrier

    (String) Indicates which carrier is used by the device.
  • iana_timezone

    (String) IANA timezone data.
  • push_opt_in

    (String) Indicates whether the device is opted-in to push.
  • background_push_enabled

    (String) Indicates whether the device has background push enabled.
  • location_enabled

    (String) Indicates whether the device has location services enabled.

Suppose an event was related to a push specification received by the Urban Airship API at 9pm UTC on July 30th, 2015, and identified by 6e3339ce-529c-42e4-a2f6-7546f81c9828. The push specification defines that delivery should be accomplished at a single point in time. The associated push would be specified by the following object:

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

Suppose that an event was related to a push specification, identified by c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06, which fulfills the push-to-local-time or automation pipeline identified by 8ea2abd6-dbc7-475a-9c57-fb31c7e2999b. The associated push would be specified by the following object:

{
  "push_id": "c2f6c5c5-f353-49c0-b5f7-6e87cf9b1a06",
  "group_id": "8ea2abd6-dbc7-475a-9c57-fb31c7e2999b"
}

Some events can be associated with the fulfillment of a push specification. We include these associations in Connect events via an associated push object, which provides identifying information about the push associated with the event. The object has the following keys:

push_id
A Push ID. push_id is a required field on associated push objects.
group_id
A Group ID. group_id is present, along with push_id, if the even occurred as part of the fulfillment of a group.
variant_id
A Variant ID. variant_id is present, along with push_id, if the event was related to the fulfillment of an experiment (A/B Test).
time
An ISO 8601 datetime, in UTC, when the push occurred. May be absent.

There is no guarantee that the push body defining the push described by the Associated Push object appear in the stream prior to the events it is related to.

Additional information about the associated push is available on other event types in Connect, or via other Urban Airship API resources.

Event Body

Most values of event types have type specific information included in the body. Some have no information that is not encoded in the parent object. For such events the body field will be blank.

Clients should be tolerant of unexpected types. As new data becomes available in the Urban Airship system, new event-type-and-body pairs will appear in the stream without warning.

Push Body Event

{
  "push_id": "233f8109-bf56-4d95-a8bf-6f28e9d270a4",
  "trimmed": false,
  "resource": "PUSH",
  "payload": "eyJkZXZpY2VfdHlwZXMiOiBbImFuZHJvaWQiLCAiaW9zIl0sICJub3RpZmljYXRpb24iOiB7ImFuZHJvaWQiOiB7fSwgImlvcyI6IHsiYmFkZ2UiOiAiKzEifSwgImFsZXJ0IjogIklUIFdJTEwgV09SSyEifSwgImF1ZGllbmNlIjogImFsbCJ9"
}

When the user initiates a push via the API or Composer, a PUSH_BODY event is emitted. The body will be a JSON object with the following attributes:

push_id
See Push ID. Present if the push body defines a push scheduled for a single point in time.
group_id
An optional identifier of the group this push is associated with. See Group ID.
trimmed
false|true: Indicates whether the push payload was trimmed from the event body or not.
payload
The specification of the push as sent via the API, a Base64 encoded JSON value.
resource

A string hinting how consumers should interpret the payload JSON. Possible values are:

  • "PIPELINES"

    The payload defines an Automated Message
  • "SCHEDULES"

    The payload defines a Scheduled Message, including local time delivery.
  • "PUSH"

    The payload defines a Push Notification which was delivered as soon as possible.
  • "EXPERIMENTS"

    The payload defines an A/B Test. Note that experiments may be scheduled or immediate.


Because push events pertain to many devices, the device key-value pair will be absent.

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

An "OPEN" event occurs whenever an end user opens an application.

The open event is specific to a device, so the Device Information field will be populated.

last_delivered
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.
triggering_push
An Associated Push object, establishing a causal relationship between a push and the Open event. Absent if no causal relationship to a push can be established.
session_id
An identifier for the “session” of user activity. This key will be absent if the application was initialized while backgrounded.

Send Event

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

A send event is emitted 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.

Each send event has the following attributes in its “body” object:

push_id
Identifies the push that is fulfilled by the send. Every send event has a push_id. See Push ID.
group_id
If the send event fulfills a push that is part of a group, then it will have a group_id field. See Group ID.
variant_id
Only present if the notification was sent as part of an experiment. See Variant ID.

Control Event

Example:

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

Control Events only occur when using our /api/experiments endpoint. See A/B Tests for details.

A control event indicates that a device was excluded from a push because it was arbitrarily selected to form part of the control group in the experiment. The behavior of users of the device serves as an indication of what would have happened without any intervention at all.

Control events contain Device Information.

push_id
Represents the push for which this device was excluded
group_id
Present if the push triggering the delivery of the push message was associated with a group. See Group ID.

Close Event

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

Each time a user closes the application, a close event is emitted. Because close events pertain to a particular device, the Device Information field will 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
An identifier for the “session” of user activity. This key will be absent if the application was closed while backgrounded.

Rich Delivery Event

A RICH_DELIVERY event indicates that a rich push message has been delivered to to a device’s Message Center. This a device specific event, so the Device Information field will be populated.

RICH_DELIVERY events have the following fields:

push_id
The Push ID which triggered the delivery of the rich push message to the user’s Message Center.

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
Present if the push triggering the delivery of the rich push message was associated with a group. See Group ID.
variant_id
Only present if the notification was sent as part of an experiment. See Variant ID.

Rich Read Event

A RICH_READ event indicates that a rich push message in an inbox was read by a user. This a device specific event, so the Device Information field will be populated.

RICH_READ event bodies have the following fields:

push_id
The Push ID which triggered the delivery of the rich push message to the user’s Message Center.
group_id
Present if the push triggering the delivery of the rich push message was associated with a group. See Group ID.
variant_id
Only present if the notification was sent as part of an experiment. See Variant ID.

Rich Delete Event

A RICH_DELETE event indicates that a rich push message was deleted from a user’s inbox.

RICH_DELETE event bodies are Associated Push objects.

push_id
The Push ID which triggered the delivery of the rich push message to the user’s Message Center.
group_id
Present if the push triggering the delivery of the rich push message was associated with a group. See Group ID.
variant_id
Only present if the notification was sent as part of an experiment. See Variant ID.

Custom Event

A custom event involving the sale of shoes might look like:

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

A CUSTOM event tracks user behavior.

Custom events are always fired from or pertain to devices, so the Device Information attribute will be present on the parent object.

name
The name of the user defined event
value
The value of units associated with the custom event. May be absent.

This value may not be representable as a 64-bit floating-point number.

transaction
A string set by the customer to wrap a sequence of interactions. May be absent.
customer_id
Customer-side id, such as an email address. May be absent.
interaction_id
An Urban Airship identifier uniquely identifying the interaction. May be absent.
interaction_type

The type of interaction. There are several interaction types that are set by the UA SDK:

  • ua_mcrap

    The event was triggered from the Urban Airship message center.
  • ua_landing_page

    The event was triggered from a landing page.
  • ua_interactive_notification

    The event was triggered from an interactive notification.

Any other value results from customer-implemented application code. May be absent.

last_delivered
An Associated Push object, specifying the last push the device received before firing this custom event. Absent if the last push occurred more than thirty days ago.
triggering_push
An Associated Push object, establishing a causal relationship between a push and the custom event. Absent if no causal relationship to a push can be established.
properties
A JSON object containing key/value pairs that define event-specific information. May be absent.
session_id
An identifier for the “session” of user activity. May be absent.
source

Required. This field takes one of the following values:

Location Event

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

An event which declares the device to be at a particular latitude and longitude when it occurred.

latitude
the latitude where the event occurred
longitude
the longitude where the event occurred
foreground
A boolean indicating whether the application was foregrounded when the event fired.
session_id
An optional unique identifier for the session, if the location event was fired while the application was open.


Location events have a device field.

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

Tag Change events indicate a change in the tags associated with a device.

add
An object mapping tag groups to tags. The set of tag group/tag pairs in this object define the tags added to the device.
remove
An object mapping tag groups to tags. The set of tag group/tag pairs in this object define the tags removed from the device.
current
An object mapping tag groups to tags. The set of tag group/tag pairs in this object define the current state of the device AFTER the mutation has taken effect.


Because tag changes are related to a device, they will have a device field.

Uninstall Event

Uninstall events are emitted when a push provider notifies Urban Airship that the application has been un-installed in response to a push.

Uninstall events pertain to a particular device, so the Device Information field will be populated.

Uninstall events contain no additional information, apart from device information, so the “body” key will be absent.

First Open Event

"FIRST_OPEN" This event appears in the stream when the application installation registers itself with Urban Airship.

First Open events pertain to a particular device, so the Device Information field will be populated.

The body attribute is absent for first open events.

Region Event

Region Event Body Example:

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

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.

Region event bodies have the following fields:

action
One of "exit" or "enter", indicating whether the event indicates the device has left or entered the region.
region_id
A string uniquely identifying the region in the Urban Airship system.
session_id
A unique identifier for the device session during which the event was fired. May be absent.
name
A human-readable name for the event. May be retrieved from a third party.
source_info

Because Gimbal is just one possible provider of this information, region event bodies contain a source_info field for provider specifics, with the following fields:

  • source

    A string identifying the system originating the event.
  • region_id

    The unique region identifier for the provider’s system.

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.

See iOS Screen Tracking and Android Screen Tracking for details on instrumenting your app for screen_viewed

The occurred time on the wrapping event object is the time the user started viewing the screen.

The event has the following fields:

duration
The number of milliseconds for which the user was on the screen.
viewed_screen
The developer-assigned name for the screen the user just left.
previous_screen
The developer assigned name for the screen the user visited BEFORE the screen they just left.
session_id
An identifier for the “session” of user activity. This key will be absent if the application was initialized while backgrounded.

In-App Message Display Event

Example In-App message display object:

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

When an In-App Message is displayed to a user, Connect will include an IN_APP_MESSAGE_DISPLAY type event. Since the event pertains to a specific device, the device information object will be populated.

The event will have the following fields:

push_id
A Push ID for the push which delivered the In-App Message instruction to the device.
group_id
Present if the push which delivered the In-App Message was part of a group. See Group ID.
variant_id
Present if the push which delivered the In-App Message was part of a variant in an A/B test.
triggering_push
Present if the user started the current session by opening a push notification. An Associated Push object.
session_id
An identifier for the “session” of user activity. May be absent.

In-App Message Resolution Event

Example In-App message resolution object:

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

}

If an In-App Message was cleared from the display, either by timeout or user action, an event with the type IN_APP_MESSAGE_RESOLUTION will appear on the stream. It pertains to an individual device, so the device information object will be present.

push_id
A Push ID for the push which delivered the In-App Message instruction to the device.
group_id
Present if the push which delivered the In-App Message was part of a group. See Group ID.
variant_id
Only present if the notification was sent as part of an experiment. See Variant ID.
time_sent
An ISO 8601 datetime indicating when the payload defining the In-App Message was sent to the device. May be absent.
triggering_push
Present if the user started the current session by opening a push notification. An Associated Push object.
type

Indicates how the In-App Message was resolved. type takes one of the following values:

  • "BUTTON_CLICK" :

    The user clicked on a button in the message. There will be additional optional fields describing the button that was clicked. They are:

    button_id

    A unique identifier for the button.

    button_group

    A category associated with the message.

    button_description

    The title of the button on which the user clicked.

  • "MESSAGE_CLICK":

    The user clicked on the message, but not on a button.
  • "TIMED_OUT":

    The user ignored the notification, it dismissed itself after an interval of time.
  • "USER_DISMISSED":

    The user either clicked an “X” or used the swipe gesture to dismiss the notification.
duration

The amount of time for which the message was displayed, in milliseconds.

session_id

An identifier for the “session” of user activity. May be absent.

In-App Message Expiration Event

Example In-App message expiration:

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

If an In-App Message won’t be displayed, either because a new message has taken its place, because it has passed its expiration, or because displaying it in app would be redundant, an event with type IN_APP_MESSAGE_EXPIRATION will appear in the stream.

This event won’t be emitted until the application becomes active, which means they may be latent.

The event body will be a JSON object with the following fields:

push_id
A Push ID for the push which delivered the In-App Message instruction to the device.
group_id
Present if the push which delivered the In-App Message was part of a group. See Group ID.
variant_id
Only present if the notification was sent as part of an experiment. See Variant ID.
time_sent
An ISO 8601 datetime indicating when the payload defining the In-App Message was sent to the device. May be absent.
triggering_push
Present if the user started the current session by opening a push notification. An Associated Push object.
type

Indicates how the In-App Message was expired. type takes one of the following values:

  • "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.
time_expired

Present for expirations of type EXPIRED. An ISO 8601 datetime, in UTC, when the message was set to expire.

replacing_push

Present if type is REPLACED. An Associated Push object identifying the push specification defining the In-App Message which should replace the current message.

session_id

An identifier for the “session” of user activity. May be absent.

Urban Airship Push Identifier Reference

Push ID

A Push ID is a string uniquely identifying a push. The Push ID identifies a push specification delivered at a single point in time.

Group ID

A Group ID is a string identifying a push specification requiring delivery over an interval of time, e.g. as part of the fulfillment of an automation pipeline or a push-to-local-time specification.

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.

Variant ID

The Variant ID is an integer which, together with a Push ID identifies a push fulfilling an experiment (A/B Test). Experiments consist of a collection of push specifications sent to randomly selected partitions of an audience. The variant ID identifies which specification in the collection is associated with the event.