Custom Events

User events that occur outside of your app can be submitted to Airship for inclusion in analytics reporting, as triggers for Automation, or for export via Connect. These events can take place on the web, e.g., your website, social media, or in your back office systems such as CRM or POS software. Any event that can be associated with a mobile app user can be submitted as an Airship Custom Event. The events that you submit are associated with channels and are available to use as Custom Event triggers.

Add Custom Events

Submit an externally-generated Custom Event, associated with a Channel ID or Named User, to Airship. You can use these events as Custom Event triggers for Automation or Sequences and can use handlebars to personalize messages using Custom Event properties (information in the body.properties object).

Jump to examples ↓

POST /api/custom-events

Note

Requests complete validation before returning a response.
Requests are authenticated with a bearer token, which can provide access to this resource alone or to this resource and others.
The name value inside body must not contain any uppercase characters, or the event will be rejected with a 400 status code.

Security:

bearerAuth
oauth2Token : evt

Request headers:

X-UA-Appkey stringREQUIRED

Request body:

An array of Custom Event objects.

Content-Type: application/json
array<Custom Event Object>
Min items: 1, Max items: 100

Responses

200
Returned on success.
Response body:
- Content-Type: application/vnd.urbanairship+json; version=3
  OBJECT PROPERTIES
  - ok boolean
    Success.
  - operation_id string
    A unique string identifying the API interaction. You can use the operation_id in support requests if something goes wrong.
400
There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response to help you find the cause of the error.
Response body:
- Content-Type: application/json
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.
401
Authentication information (the app key and secret or bearer token) was either incorrect or missing.
Response body:
- Content-Type: text/plain
  Error response
  Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Examples

POST /api/custom-events HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <application key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
   {
      "occurred": "2020-05-02T02:31:22",
      "user": {
         "named_user_id": "hugh.manbeing"
      },
      "body": {
         "name": "purchased",
         "value": 239.85,
         "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
         "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
         "interaction_type": "url",
         "properties": {
            "description": "Sneaker purchase",
            "brand": "Victory Sneakers",
            "colors": [
             "red",
             "blue"
            ],
            "items": [
               {
                  "text": "New Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Old Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Blue Line Sneakers",
                  "price": "$ 79.95"
               }
            ],
            "name": "Hugh Manbeing",
            "userLocation": {
               "state": "CO",
               "zip": "80202"
            }
         },
         "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
      }
   }
]

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .setBearerToken("<bearer token>")
        .build();

CustomEventUser customEventUser = CustomEventUser.newBuilder()
        .setNamedUserId("hugh.manbeing")
        .build();

CustomEventPropertyValue customEventProperty = CustomEventPropertyValue.of("Victory Sneakers");

List<CustomEventPropertyValue> items = new ArrayList<>();
items.add(CustomEventPropertyValue.of("New Line Sneakers"));
items.add(CustomEventPropertyValue.of("Old Line Sneakers"));

DateTime occurred = new DateTime(2020, 05, 02, 02, 31, 22, DateTimeZone.UTC);

CustomEventBody customEventBody = CustomEventBody.newBuilder()
        .setName("purchased")
        .addPropertiesEntry("brand", customEventProperty)
        .addPropertiesEntry("items", CustomEventPropertyValue.of(items))
        .build();

CustomEventPayload customEventPayload = CustomEventPayload.newBuilder()
        .setCustomEventBody(customEventBody)
        .setCustomEventUser(customEventUser)
        .setOccurred(occurred)
        .build();

CustomEventRequest customEventRequest = CustomEventRequest.newRequest(customEventPayload);
Response<CustomEventResponse> response = client.execute(customEventRequest);

from datetime import datetime
from urbanairship import (
    BearerTokenClient, CustomEvent
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

event = CustomEvent(
   client=client,
   name='purchased',
   user={'named_user_id': 'hugh.manbeing'},
   interaction_type='url',
   interaction_id='your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234',
   value=239.85,
   transaction='886f53d4-3e0f-46d7-930e-c2792dac6e0a',
   session_id='22404b07-3f8f-4e42-a4ff-a996c18fa9f1',
   properties={
      'description': 'Sneaker purchase',
      'brand': 'Victory Sneakers',
      'colors': ['red', 'blue'],
      'items': [
         {'text': 'New Line Sneakers', 'price': '$ 79.95'},
         {'text': 'Old Line Sneakers', 'price': '$ 79.95'},
         {'text': 'Blue Line Sneakers', 'price': '$ 79.95'}
      ],
      'name': 'Hugh Manbeing',
      'userLocation': {
         'state': 'CO',
         'zip': '80202'
      }
   },
   occurred=datetime(2020, 5, 2, 2, 31, 22)
)

response = event.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', token: '<token>')

example_events = [
  UA.custom_events(
    body: UA.custom_events_body(
      interaction_id: "api/ua/#schemas-customeventobject",
      interaction_type: "url",
      name: "example",
      properties: {
        "who" => "Alf",
        "where" => "In the garage!",
        "from" => "Melmac"
      },
      session_id: "8d168d40-bc9b-4359-800c-a546918354ac",
      transaction: "d768f61f-73ba-495f-9e16-b3b9c3b598b7",
      value: 1
    ),
    occurred: "2021-10-01T00:00:00",
    user: UA.custom_events_user(named_user_id: "Gordon Shumway")
  )
]
event = Urbanairship::CustomEvents::CustomEvent.new(client: airship)
event.events = example_events
event.create