Importing ZeroPush projects to Boxcar Push Service

Since the announcement of ZeroPush closing its push service the next January 31, 2016 we have worked into offering a service to migrate your project(s) to our Boxcar Push platform. This article explains how to export data from ZeroPush service, import it using our Push Console importer tool and how to migrate your mobile applications from ZeroPush to Boxcar SDK. If you have questions or troubles migrating your existing application feel free to contact us at zeropush@boxcar.io or our @boxcar account on Twitter.

Exporting your project

First of all, you need to extract your project data at ZeroPush. The export service is available here and once the job has finished it will e-mail you with a link to the URL of the XML dump file.

The data extracted from a ZeroPush export dump can be categorized as follows:

  • Users: users with login access to your ZeroPush project.
  • Applications: every type of client application platform supported by your project. Within a Boxcar Push project these are known as client applications. Every application also contains associated data:
    • Certificates: PEM formatted push certificates and private key (iOS) or API keys (Android) needed to deliver pushes.
    • Devices: Every device token subscribed to the application.
    • Channels: Broadcast topics created to broadcast pushes to several subscribers. Within a Boxcar Push project these are known as tags.

For more details, the following is a document from ZeroPush team explaining what kind of data is exported from your existing project and how to do it.

Importing your project

The next step is to import your project data to Boxcar. Go to the Boxcar Push Console and create a new account in case you don’t have one already. Now login with your user and create a new project:

The figure above shows where you can find the option to add a new project.

After the creation of the new project go to the Dashboard and click on the ‘Settings’ button of the new project. You will see a new screen that allows to edit most important properties. Click on the ‘Import data’ button (if your application is supposed to create channels when a client tries to subscribe to an unexistent one, then mark the ‘Implicit tag creation’ option).

The figure above shows the settings page withe the ‘Import data’ button.

Now you will see a new page with an input to set the url of the dump file generated by ZeroPush (see image below). Copy the url sent via e-mail by ZeroPush and click on the ‘Import’ button.

The import process can take some time. That’s why you will see a list of pending import tasks after submitting your import job:

You can also check this task list at any time by browsing to your project settings and clicking in the ‘View Import Jobs’ button:

Please note that your current Boxcar plan has limits of allowed devices and tags (channels). In case your ZeroPush project exceeds these limits, you will see a warning about this in the alert section of Boxcar Push Console:

Similarly, when your project is successfully migrated a message is posted in the alert section of Boxcar Push Console:

Migrating your client applications

After importing your ZeroPush project into your Boxcar account it is time to ensure your existing users can receive pushes from Boxcar platform.

iOS devices

For iOS device applications the only important aspect to take care is about switching the SDK to Boxcar, to ensure these register to the new platform. Because tokens were migrated in the previous step and the push format is maintained, this means that notifications sent from Boxcar will be received even by old applications. In this case the suggested approach is to begin sending pushes from Boxcar (and stop doing it from ZeroPush) as soon as the client application is published in the App Store.

Android devices

Android and specifically GCM takes a different approach for push handling. In this platform the payload processing is handled by the application itself and the payload format is not restricted (compared to iOS, where the payload must follow a strict format). Boxcar Push Service uses an specific payload structure to allow publishing notifications to diverse platforms with a single call, however this is a problem for applications using ZeroPush, because the platform doesn’t assume any payload format. In other words, existing ZeroPush client applications won’t be able to process incoming pushes from Boxcar service. For this reason the suggested approach to successfully migrate applications to Boxcar is the following:

  • Implement a new version of your application using Boxcar SDK 3.1.2 or greater. This SDK ensures you can handle the pushes ‘as they come’ (needed to handle the push format you were using with existing apps from ZeroPush) but also the pushes sent from Boxcar Push Service.
  • Define a transition period. During this transition perdiod you would publish notifications from both ZeroPush and Boxcar. This ensures that both old and new applications will receive and display notifications.
  • During this transition period every ‘Boxcar-capable’ application will subscribe to Boxcar and unregister from ZeroPush when one of the following conditions met:
    • A new push from ZeroPush is received
    • The application is open manually by the user
  • After the transition period has elapsed you will only send pushes from Boxcar Push Service. From this time you can release newer applications compatible with Boxcar only.

Migration example

The aforementioned approach is implemented using the same Zero Push Android demo but refactored to perform a migration to our Boxcar Push Service. See the source code for this modified example. The ZeroPush credentials should be edited on MigratorIntentService class, while the Boxcar keys should be added on the BoxcarDemoDelegate class. This is just a basic example that assumes the existing application followed the same implementation shown in the original ZeroPush Android Demo [1]: for example, it assumes your registrationID was cached using a SharedPreferences file with a different key for each application version. It is possible that your application manages it differently, so don’t hesitate to ask for help if you have doubts about this example.

We suggest to avoid sending pushes to Android devices using the token that was migrated from ZeroPush. For simplicity we will refer to these tokens as ‘old tokens’, meaning registration IDs that are registered in ZeroPush. There are basically three problems to use the same tokens with Boxcar:

  1. ZeroPush SDK uses a now deprecated GCM library (informally known as GCM 2). Google recommends to use the latest (GCM 3), which now relies on a new generic service called Instance ID to manage tokens. This is the implementation that Boxcar SDK v3.* uses.
  2. Google recommended to renew the token every time an application is updated while GCM 2 was the latest running service. Now this recommendation is not explicitly stated on their docs, however it is still recommended to refresh it often.
  3. Using the migrated tokens directly from Boxcar means sending pushes to applications that possibly don’t use Boxcar, so they won’t be able to understand the notification.

The workaround for this transition issue is to either remove all migrated Android tokens (assuming your application will request a new token and register on Boxcar if it is activated by a push) or create a new client application (a different client application that the one automatically created during the migration step). Doing so you can push to this new client application, knowing that only those devices that did renew his token are registered there and will receive the pushes. Warning: please pay attention to the fact that Boxcar allows to send a push to a whole project, which means all client applications belonging to it. In this latter case you should be careful to push to an specific client application.

Questions?

Feel free to contact us at zeropush@boxcar.io or @boxcar. We would be glad to help you in case of doubts or questions.