Getting Started with Real-Time Data Streaming

Deliver engagement events in real time using the Airship Data Streaming API or through our many partner integrations. With Real-Time Data Streaming, Airship is not only your digital engagement service provider, but your most valuable source of mobile engagement data.

See:

Base URL Address

The Data Streaming API is a single endpoint, available at:

  • https://connect.urbanairship.com/api/events — for customers accessing our North American data center.
  • https://connect.asnapieu.com/api/events — for customers accessing our EU data center.

Partner Integrations

In addition to Direct Integrations, we provide seamless integrations with a number of third-party providers. See: Partners.

Start Using Real-Time Data Streaming

Real-Time Data Streaming is an add-on service. Please contact Airship Sales to enable the service for your account. After it has been enabled for your account:

  1. Configure a Direct Integration to route your event stream data into your terminal window.
  2. Construct a cURL command that:
    • Connects to the appropriate Airship server.
    • Passes in no parameters.
    • Receives the raw firehose of events.
 Tip

Even if you don't require direct access to the event stream, we still recommend setting up a Direct Integration. Configuring a Direct Integration will give you a good idea of how the event stream works, and you can simply delete the connection once you have completed the tutorial.

 Note

While anyone should be able to follow these instructions, we do assume conceptual familiarity with the Real-Time Data Streaming service throughout the document.

Connect to the Test Server (optional)

While completing this section is not required, connecting to the test server is an easy way to see what the event stream looks like. If you would like to proceed directly to integrating your application with data streaming, skip to Configure a Direct Integration.

If you don't have an app in the Airship system or just want to try a test connection, you can use our test server. This data is randomly generated and, while it attempts to provide an approximation of a mobile user's potential lifecycle, it should not be assumed that anything in here is useful or truly similar to what will be happening in your app.

This section assumes that you're in a terminal window on Mac OSX or a Linux environment.

  1. Paste the following code:
curl -vv https://connect-testing.urbanairship.com/api/events/ \
   --compressed \
   -u "sample_connection:sample_connection" \
   -H "Accept: application/vnd.urbanairship+x-ndjson; version=3;" \
   -d "{}"

Wait a little bit, and you should see Airship events appear.

 Note

Using this method, there might be a lag in between when events are delivered via the Airship event stream and when they show up in your terminal. This is due to how cURL processes compressed events and does not reflect how the events are actually being delivered.

Configure a Direct Integration

A Direct Integration is similar to other integrations, but rather than funneling mobile engagement data through an external service, you are routing it directly through your backend systems. The Direct Integration is designed for customers who are interested in building their own custom applications on top of the event stream.

If you completed the previous section, you have a general idea of what the event stream looks like, albeit when filled with dummy data. Now we will generate a real stream of data by accessing your app's event stream.

  1. Open your messsaging project and go to Settings » Real-Time Data Streaming.
  2. Under Real-Time Data Streaming, click Direct Integration.
     Tip

    Previously configured integrations are listed under Enabled Integrations.

  3. Enter a user-friendly name and description.
  4. Check the box if you'd like to send location events through this connection.
  5. Click Create Access Token.
  6. Copy the App Key and Access Token and save in a secure location. You will use both when you connect to your app's event stream.
     Warning

    You will not be able to view the Access Token after leaving this screen. You may, however, add new tokens and delete existing tokens. See: Manage Integrations.

  7. Click Save & Exit.

Connect to Your App's Event Stream

To complete this section, you need the App Key and Access Token created in the previous section, Configure a Direct Integration.

This section assumes that you're in a terminal window on Mac OSX or a Linux environment.

  1. Create cURL a request to the Data Streaming API.

    Example Request:
       curl -vv https://connect.urbanairship.com/api/events/ \
          --compressed \
          -H "Authorization: Bearer <access-token>" \
          -H "X-UA-Appkey: <app-key>" \
          -H "Accept: application/vnd.urbanairship+x-ndjson; version=3;" \
          -d "{}"
       
    Be sure to replace <app-key> and <access-token> with your actual App Key and Access Token.

  2. You're done! You should now be connected and receiving events. Congratulations!

Supported Event Types

Below is an inexhaustive list of event types that are currently supported via the Real-Time Data Streaming service. These events are emitted as soon as they are available.

For a complete reference of supported event types, see Connect Filters in our API reference.

Push Body
Occurs when you initiate a notification or message through the Airship dashboard or API. The relevant identifiers and payload (content) are included in the event.
Open
Occurs when a user opens your application. This event also includes information about the last delivered push, and, if available, the triggering push if a causal relationship is determined.
Close
Occurs when a user closes your application.
 Note

Close events are often latent as they may not be delivered over the network until the next time the app is activated. Use offsets to adjust stream location for close events.

Custom
Customer-defined events. See: Custom Events.
Location
If location services are enabled for your app, location events provide latitude and longitude for a user.
Region
Similar to location events, region events are emitted when a device enters a predefined geographic or beacon region. See Location Triggers for information about geofence and beacon triggers.
Send
A push send identifier is created for each individual device that you target for receipt of the push. The send event maps devices to the pushes or push campaigns that are associated with the device.
Tag Change
Tag change events occur any time a tag is added or removed from a device, e.g., when a user changes a stated preference or is tagged "active" or "gold_member" by the device.
First Open
First open events appear when a user opens your Airship SDK-enabled app for the first time. Useful for new user onboarding message campaigns.
Uninstall
Emitted when we learn from a push provider, e.g., Apple, that the app has been uninstalled in response to a push notification. Consider using uninstall data to inform your omnichannel communications.
Message Center Events
Delivery, read, and delete events are provided along with device-specific identifiers for Message Center messages.
Screen Viewed Events
Indicates that a user has finished viewing a screen. Duration, session ID, and developer-assigned screen names may be returned.
In App Message Events
Engagement events emitted for an In-App Message A message that appears inside of your app. include:
  • Display: Was the message displayed?
  • Resolution: What action did the user take with the message?
  • Expiration: Message is expired or supplanted or otherwise unnecessary.
Web Click Event
Indicates that a user has interacted with a web notification, e.g., clicked or tapped it.
Web Session Event
Indicates that an opted-in user has begun interaction with a website.