Getting Started

This guide will take you through the process of configuring a Direct Connection and route streaming Connect data into your terminal window. At the end of this walkthrough you will have successfully:

  • Generated an access token and started the data flow.
  • Constructed a cURL command that:

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

Connect is an add-on service. Please talk to your Urban Airship Account Manager to enable Connect for your account.

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.

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.

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 Generate an 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.

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.

Generate an 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. Now we will generate a real stream of data by accessing your app’s Connect stream.

  1. Choose your project from the Urban Airship 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. Name and 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, Generate an Access Token.

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

  1. Make request: 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:

    If you are already connected and seeing events on your screen, you are done! Feel free to skip to Next Steps.

  2. Get Cookie: 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, as shown below. Copy the sXXXX portion of the header:
       < Set-cookie: SRV=sXXXX; path=/
       
    

  3. Make request with cookie: Now 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 <app-key> and <access-token> with your actual App Key and Access Token, 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!

Next Steps

Read About Connect

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, please check out About Connect 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 provide seamless integrations with a number of third-party providers. Click Integrations in the left-hand menu on this page to see the current available Connect Integrations.