Migrating your current app audience to Urban Airship

To migrate your app and current audience 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: Create an Urban Airship app.

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.

If you import invalid iOS Device Tokens to your app, you may no longer be able to send push notifications using that Urban Airship app. 

If you are unsure about importing your audience to Urban Airship, contact support at https://support.urbanairship.com. 

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 Token or GCM Registration Token)

  • Device Type (iOS or Android)

  • Opt-in status (True or False)

The body of the request may also include:

  • Tags or other 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 Urban Airship app key. The password is your Urban Airship master secret.

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:
Register your Android devices to Urban Airship.

You can import GCM Registration Tokens, but not the older GCM Registration IDs. For more information on how to differentiate the two, see the FAQ topic How do I know I'm importing correctly? in the FAQs section below.

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 REGISTRATION TOKEN>"
    }

 

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 }

 

How do I know I'm importing correctly?

If you import incorrect/invalid device identifiers to your app, you may no longer be able to send push notifications. If you are unsure about importing your audience to Urban Airship, contact support at https://support.urbanairship.com. 

When importing your Android audience, make sure you are working with GCM Registration Tokens and not the older GCM Registration IDs. The GCM Registration Tokens contain eleven characters and then a colon : followed by a longer string. For example: cPkf713ro4k:APA91bF86NR5K57Ba5KuU9-Lxcgx5d6U3UM0HW9PY-tMBiqxwMjathk0Pe2BewadL_B8vSy6r_oVBmJEJtKo5f0jb6wAfHDB4wClhzaSfmFcapdyEdoBZlZ9P1OR6kgxGkqTnVr9a7a

 

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 Token>"
    }
]

Related Content: