Getting Started

Welcome to Connect, Urban Airship’s mobile data streaming service. This document will walk you through the Connect UI and the process of configuring a Direct Connection. We do assume conceptual familiarity with the Connect service throughout the document – if you aren’t totally sure what Connect does, please read our Connect Primer. The Connect API can be found here.

The Connect UI

The rest of this tutorial assumes you have purchased Connect access. If you have not and are interested, please contact your account manager.

To get started with Connect, log in to Urban Airship and navigate to your app’s dashboard. Click Connect on the sidebar, and you will see a list of availble integrations:

The top of the page displays your Active Connections, or connections you have already configured. Below you will find a full list of available Connections. Click on a connection for details:

The precise form that appears depends on the integration, but many integrations have a similar workflow:

  1. Enter some information

  2. Generate a token

  3. Transfer that token to the service (e.g. Lytics, etc)

After step 3, mobile data will begin funneling through the chosen service. For connection-specific instructions, follow the instructions in the UI or visit our index of integrations. In the next section, we will cover the configuration of a Direct Connection, an integration which gives you direct access to the connect stream.

Even if you are uninterested in having direct access to the Connect data stream, we still recommend completing the Direct Connection tutorial. 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.

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

In this tutorial, we are going to route streaming Connect data into your terminal window. The remainder of the tutorial assumes that you’re on Mac OS X or a Linux environment. To begin, open a terminal window. You’re going to construct a cURL command that:

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

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 doesn’t reflect how the events are actually being delivered.

First Steps: The Connect Test Server

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 Generate a Direct Connection Access Token.

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. In your terminal window, 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.

Generate a Direct Connection Access Token

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

Before you can access the Connect stream, you need to generate an access token for your app. Begin by navigating to Connect in the dashboard, and click on Direct Connection. You should see the following form:

  • Name: Used within the dashboard to refer to this integration.
  • Description: Used within the dashboard to describe this integration.
  • Location Events: Determines whether your integration will collect location events.

Once you have filled out the Name and Description fields, and selected whether you would like location events included in your stream, click Save and Create Access Token. You should now see your app key and newly-created access token at the bottom of the page:

Before proceeding, be sure to copy your access token somewhere safe – once you click Save & Exit, you will not be able to view this token again. If you forget or misplace this token, you will have to go through the process of generating another (see Editing Your Connection for details on generating additional tokens). Now that you’ve copied your access token, click Save & Exit.

In the next section, we take a small diversion from the main tutorial to explore Connection management features.

Editing Your Connection

After saving your connection, you will be redirected to the connection management screen:

From here, you can create new tokens, edit the connection details, or delete the connection.

Edit Connection

To edit or delete your connection, hover your mouse beneath the connection’s name, and you will see a small blue Edit icon appear:

Click on the icon, and you will see the following form:

From here you can edit the connection’s name and/or description, or you can delete the connection, by clicking the small Delete text in the bottom right corner.

Manage Tokens

To create a new token, click the Add New Token button, and enter a name for your token:

Click Create Token, and you will see the following display:

You will not be able to view your access token again, so remember to copy it down now.

You can create a maximum of 25 access tokens per connection.

If you would like to delete a token, simply click the Revoke button, located to the right of each token. You will be asked to confirm the deletion:

Click the checkbox to finalize your decision, and then click Delete.

Connect to Your App’s Connect Stream

Assuming you completed the previous section, you should have your Connect access token. You’ll also need to know the Urban Airship app key for the app that you’ll be using.

  1. Make request: The next step is to 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 <access-token> with your access token and <app-key> with your Urban Airship app key.

  2. Get Cookie: (If you are already connected and seeing events on your screen, you are done! Feel free to skip to the What’s Next? section.) After making the request in step 1, you’ll likely get an HTTP 307 status code and be disconnected. Part of this 307 response will include a Set Cookie header:
       < Set-cookie: SRV=sXXXX; path=/
       
    
    Copy the sXXXX portion of the header.

  3. Make request with cookie: Next, you will recreate the request you made in step 1, but with the addition of the Cookie header:
       -H "Cookie: SRV=sXXXX; path=/" \
       
    
    In the above example, the sXXXX is the string you copied in step 2. Here is the request made in step 1, but with the additional header:

    Example Request:
       curl -vv https://connect.urbanairship.com/api/events/ \
          --compressed \
          -H "Authorization: Bearer your-access-token" \
          -H "X-UA-Appkey: your-app-key" \
          -H "Accept: application/vnd.urbanairship+x-ndjson; version=3;" \
          -H "Cookie: SRV=sXXXX; path=/" \
          -d "{}"
       
    
    Again, be sure to replace <access-token> with your access token, <app-key> with your Urban Airship app key, and sXXXX with the text you copied in step 2.

    After executing the command in step 3, you should now be connected and receiving events. Congratulations!

What’s Next?

Read our Connect primer
Was this tutorial just a series of weird technical instructions that resulted in a stream of seemingly meaningless text flying across your terminal window? If that’s the case, you may want to revisit our high-level Connect Primer for a conceptual overview of Connect.

Explore the Connect API
Experiment with additional filters and offsets to get a feel for what the API can do. See the Connect API documentation for details.

Explore other integrations
In addition to Direct Connections, we currently provide seamless integrations with a number of other third-party providers. Navigate to the Connect page in your Urban Airship dashboard for an overview.