Migrating Your Devices to Urban Airship from Another Push Provider

UPDATE: Our Parse Importer Tool is now available. Click here to find out more.

With Parse announcing that they are winding down, we know many developers are working through migration plans, including selecting a new push notifications provider. Last week we let you know how Urban Airship is here to help make the transition as seamless as possible for developers to get up-and-running with Urban Airship push notifications.  

Today we're going into further detail, providing you the exact steps to complete the migration to Urban Airship yourself, as well as to let you know how to engage our support organization to help you with the migration at no cost.

To migrate your app to Urban Airship, you will work through the steps in our Quickstart Guide to download the Urban Airship SDK, install it in your app, upload your certificate (for iOS), and send a test push for the platform of your choice. This article will help you through the process.

Initial Urban Airship Setup

Step 1: Setup your Urban Airship Environment

The first step is to create an app in the Urban Airship dashboard at go.urbanairship.com.

We recommend creating both a production and development mode app. Apple will treat these apps differently and will supply any devices registered through the development servers with a device token unique from the one they will receive in production. For further information on why we recommend a production and development app, see Production vs Development Apps in Urban Airship.

For your initial testing, it is important that you use a development mode app.

See our Getting Started documentation for more help.

Step 2: Work through the Quickstart Guide to implement the Urban Airship SDK in your app

If you need further guidance on this process, see our documentation

Step 3: Set up the Push Services

Set up your app's push service as needed via the Quickstart Guide:

Step 4: Send a Test Push

The final step of the Quickstart Guide is to send a message to test your setup. Once you've completed this step, you will see more options in the left menu and you'll now have complete access to your app.

To create a production app, you'll need to repeat the process for creating the development app, this time switching to production/distribution when appropriate. You can do some last minute testing with your production app by provisioning test devices by creating an Ad Hoc provisioning profile.

Migrate Device Records to Urban Airship

Urban Airship provides an API endpoint that will allow you to import your iOS and Android devices from your databases into Urban Airship for push.

API Endpoint:

POST /api/channels/import/

Import a number of Device Tokens or GCM Registration IDs into Urban Airship, creating a Channel for each device.

This API will not allow more than 200 devices in a single request.

API Request:

This API endpoint uses the base url https://go.urbanairship.com/. This request has a body, and the body must be in JSON format. When sending this request, set the Content-type header to application/json.

The body of the request must contain one device object, or an array of device objects that include:

  • A single push address

  • Device Type (iOS or Android)

  • Opt-in status (True or False)

The body of the request may also include:

  • Tags or attributes for segmentation

If you would like to segment your imported devices we recommend adding a tag when devices are imported. For example, adding an "imported_device" tag to your devices will allow you to target or exclude imported devices when sending messages.

Authentication:

This API request is identified using HTTP Basic Authentication. The username portion is the application key in Urban Airship. The password portion will be your master secret in Urban Airship.

Versioning Syntax:

You must specify the version of the API you are using with the Accept HTTP header.

The default content type is JSON, while the latest version of the API is 3.

IOS

Validating your iOS devices:

Before you import your iOS audience, we recommend that you validate your iOS audience, to ensure you can reach an active and engaged audience when the migration is complete.

In order to validate your iOS devices, send a push notification without an alert. The ideal method would be to use your current push provider to send a push notification with an empty alert field, or simply omit the alert from your payload.

The notification will reach the device, but will not display to the user.

Apple will provide feedback to you on the unreachable devices. These should then be removed from any import to Urban Airship.

Importing your iOS devices:

Register your iOS device to Urban Airship.

Example Request:

POST /api/channels/import/
HTTP/1.1 Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json  

[
   {
       "device_type": "ios",
       "opt_in": true,
       "push_address": "<DEVICE TOKEN>"
   }
]

Android

Importing your Android devices:

If you are migrating from Parse’s Push Service and are using the default GCM integration, you will need to release an updated version of your app with the Urban Airship SDK integrated to register your app users prior to beginning your migration to Urban Airship.
If you are using your own GCM API key and Sender ID on Parse, follow the instructions below.

Register your Android device to Urban Airship.

Example Request:

POST /api/channels/import/
HTTP/1.1 Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json  

[
  {
       "device_type": "android",
       "opt_in": true,
       "push_address": "<GCM REG ID>"
   }
]

FAQs

Will Integrating Urban Airship's library interfere with other Push Notification services?

No. Integrating and registering your app users with Urban Airship will not render these devices unable to receive notifications from the previous service you were using. Notifications are sent to devices by Apple or Google. Any push service you are using will be querying Apple or Google to send the data, which you've provided, to your users.

How do I add additional attributes to my audience?

If you have additional attributes or tags from your current push provider that you would like to carry over, you can use Urban Airship tags to ensure that information is carried across.

Example Request:

POST /api/channels/import/
HTTP/1.1 Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json  

[
   {
       "device_type": "ios",
       "opt_in": true,
       "push_address": "<DEVICE TOKEN>",
       "set_tags": true,
       "tags": [
           "exampleTag1",
           "exampleTag2"
       ]
   }
]

Example Response:

HTTP/1.1 202 Accepted Content-Type: application/vnd.urbanairship+json; version=3;  { "ok": true }

Example Request with both iOS and Android:

POST /api/channels/import/
HTTP/1.1 Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

[
   {
       "device_type": "ios",
       "opt_in": true,
       "push_address": "<Device Token>"
   },
   {
       "device_type": "android",
       "opt_in": true,
       "push_address": "<GCM Registration ID>"
   }
]

We hope this documentation makes the process of migrating to Urban Airship easy, but if you’d like our help, our support organization is here to assist you. Feel free to contact us at https://support.urbanairship.com to get the conversation started.

Stay tuned. We’ve got more coming for developers and look forward to helping you.