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.

Integrations

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

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:

Configure a Direct Integration to route your event stream data into your terminal window.
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.

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.

Go to Settings » Project Configuration and click Manage for Real-Time Data Streaming.
Under Real-Time Data Streaming, click Direct Integration. Previously configured integrations are listed under Enabled Integrations.
Enter a user-friendly name and description.
Check the box if you’d like to send location events through this connection.
Click Create Access Token.
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.
Click Save and 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.

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.

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 by the Real-Time Data Streaming service. These events are emitted as soon as they are available. See API: Data Formats for the full list.

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 EventsEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom Events can trigger automation, including Sequences and Scenes. You can code them into your app or website, or send them to Airship from an external source using the Custom Event API. Custom Events contain properties that you can use to personalize messages..
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 our Gimbal integration 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 MessageA message that appears inside of your app. You can send in-app messages to your entire app audience, not just users who have opted-in to push notifications. The standard format, as opposed to In-App Automation, is a banner that slides downward or upward from the top or bottom of a device screen. 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.

Feedback

Was this page helpful?