Getting Started with Connect


Connect is a mobile engagement data streaming service that delivers engagement events in real time via our Data Streaming API or through our many partner integrations. With Connect, Urban Airship is not only your digital engagement service provider, but your most valuable source of mobile engagement data.

Base URL Address

The Connect API is a single endpoint, available at:

Partner Integrations

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

Start Using Connect

Connect is an add-on service. Please talk to your Urban Airship Account Manager to enable Connect for your account. After Connect has been enabled for your account:

  1. Configure a Direct Connection to route streaming Connect data into your terminal window.

  2. Construct a cURL command that:

    • Connects to the Urban Airship Connect server at
    • Passes in no parameters.
    • Receives the raw firehose of events.

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


While anyone should be able to follow these instructions, we do assume conceptual familiarity with the Connect 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 Connect stream looks like. If you would like to proceed directly to integrating your application with Connect, skip to Configure a Direct Connection.

If you don't have an app in the Urban 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 \
   --compressed \
   -u "sample_connection:sample_connection" \
   -H "Accept: application/vnd.urbanairship+x-ndjson; version=3;" \
   -d "{}"

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


Using this method, there might be a lag in between when events are delivered via Connect 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 Connection

A Direct Connection 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 Connection integration is designed for customers who are interested in building their own custom applications on top of the Connect data stream.

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

  1. Open your project from the dashboard, then click Settings and select Connect Integrations.

  2. Under Connections, click the pane for Direct Connection.

    Previously configured integrations are listed under Active Connections.

  3. Configure the new integration:
    • Enter a user-friendly name and description.
    • Check the box if you'd like to send location events through this connection.
  4. Click the Save & Create Access Token button.

  5. Copy the App Key and Access Token and save in a secure location. You will use both in the next section, Connect to Your App's Connect Stream.

    You will not be able to view the App Key and Access Token after leaving this screen, so copy and save them now. You may, however, add new tokens and delete existing tokens. See: Manage Connections.

  6. Click the Save & Exit button.

Connect to Your App's Connect Stream

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

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

  1. Create cURL a request to the Connect API.

    Example Request:
       curl -vv \
          --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 Connect 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 Urban Airship dashboard or API. The relevant identifiers and payload (content) are included in the event.
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.
Occurs when a user closes your application.

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.

Customer-defined events. See: Custom Events.
If location services are enabled for your app, location events provide latitude and longitude for a user.
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.
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 Urban Airship SDK-enabled app for the first time. Useful for new user onboarding message campaigns.
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 In-App Messages 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.