Getting Started with Connect

About

Urban Airship 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.

Mobile Engagement Data

At Urban Airship, we think of mobile engagement as the sum total of your users’ interactions with your brand on their mobile devices. Though we are primarily concerned with mobile apps, mobile engagement encompasses other mobile channels, e.g., mobile web.

The mobile engagement data that Urban Airship Connect provides is specific to mobile apps that have installed our SDK, and fall into three main categories of event types:

  • User-initiated action, e.g., opening/closing your app, tapping a push notification.
  • Device responding to an environment change, e.g., encountering a beacon.
  • Experience-changing actions initiated by app publisher, e.g., push send.

In order to quantify mobile engagement, the Urban Airship SDK looks for engagement events and sends them to the Connect data stream as soon as they are observed, along with the relevant identifiers that associate the events with a particular app user and notification or group of notifications.

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.
    • 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 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 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. Choose your project from the Engage dashboard, then click Connect in the navigational header.
  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 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 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.
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.

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 Urban 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 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.

Learn: Dashboard

Dashboard and Menus

Tutorials: Integrations

Learn: API

Reference