AWS Mobile Blog

Migrating from Parse Push to Amazon SNS

by Arjun Cholkar | on | | Comments

As you may already know, Parse announced that it will retire its operations by January 28, 2017. To help customers transition their Parse Core resources to another hosted provider like AWS, Parse open-sourced the Parse Server and published a migration guide. The guide, however, does not have a migration path for Parse Push and suggests that another push provider be used for push workloads. While searching for push provider alternatives, we recommend that you try Amazon Simple Notification Service (Amazon SNS), using the migration script and steps specified in this article.

If you are new to Amazon SNS, here is what you should know: Amazon SNS is a publish-subscribe based notification service that is used by several leading brands and startups to send billions of mobile push notifications (iOS, Android, Windows, FireOS, and Baidu) and enterprise messages every day. Amazon SNS scales as your needs grow and offers usage-based pricing. With Amazon SNS you can make 1M requests, 1M mobile push delivery attempts and send 1GB of data out of any AWS region at no-charge every month. After that, you pay just $0.50 per million requests and $0.50 per million mobile push delivery attempts (plus applicable data transfer charges). More information on pricing, can be found here.

Migrating from Parse Push to Amazon SNS is easy: you can export all of your push tokens from Parse, import them to Amazon SNS, and start publishing to your apps immediately without any client code changes or app store updates. Here is how you migrate:

Step 1: Export Parse Push data

  1. Log in to the Parse console and select your application.
  2. Under Core > Browser, select the Installation class.
  3. In the top right corner click Edit.
  4. Select Export this data.

  1. In Export this class, select Export.

  1. An email will arrive shortly with a link to download your exported zipped JSON file.
  2. Download and save the exported JSON file. We’ll be using it next. The exported JSON file should look like the sample below and should have deviceToken, deviceType and channels keys with appropriate values.


Step 2: Obtain your APNS and/or GCM credentials

  1. Obtain the APNS and/or GCM credentials that you used to create the integration with Parse.

    • For Apple (APNS) applications: Amazon SNS uses a .p12 push certificate. You can export it from your Mac Keychain. If you don’t have the .p12, follow Step 1 from the tutorial here.
    • For Android (GCM) applications: You need to provide the API (Server) Key from the Google Developers Project associated with your Parse app.
    • For Windows (WNS) applications: You need to provide the Client secret and Package Security Identifier (SID) by following instructions from here.
  2. Save these credentials for later because we will use these to create your Amazon SNS resource using the AWS Mobile Hub.

Step 3: Create AWS resources

3.1. Create a new AWS Account (if you need one):

  1. Go to http://aws.amazon.com/ and click Sign In to the Console.
  2. Follow the on-screen instructions.

Note: As part of the sign-up procedure, you’ll receive an automated telephone call asking you to use your telephone keypad to enter the supplied PIN. You must also supply a credit card number even if you are signing up for the free tier.

3.2. Create an AWS Mobile Hub project and configure the Push Notifications feature:

  1. Navigate to the AWS Mobile Hub console here.
  2. Choose Get Started.

  1. Review the details of the “First things first…” prompt page.

  1. To grant permissions, click Yes.
  2. Choose Create new mobile project, and enter a project name (for example, “Parse Migration”).
  3. After the project has been created, add the Push Notifications feature.

  1. Click Enable push, then select the platform your app is currently supported on, upload your platform credentials (from Step 2), and click Save changes.

  1. Click Resources on the left panel of the Mobile Hub console.
  2. Under Amazon SNS Platform Applications, copy the highlighted name and save it in a temporary location (you will use it later as a parameter to the migration tool).

                         

  1. Under Amazon SNS Topics, copy the topic name and save it in a temporary location (you will use it later as a parameter to the migration tool).

 

Your fully qualified SNS platform application name will look something like the following. The highlighted part is the application name that you will provide to the migration tool in Step 4:

arn:aws:sns:us-east-1:xxxxxxxxxxxx:app/APNS/awsalerts_MOBILEHUB_1768078871

With the preceding procedure, you have now created an Amazon SNS resource called a PlatformApplication that holds the credentials for the specific push notification gateway (e.g. APNS or GCM). This PlatformApplication is represented in AWS by something called an Amazon Resource Name (ARN). Additionally, an Amazon SNS Topic is a resource that is similar to what Parse calls channels. Topics are also represented in SNS as ARNs.

3.3. Obtain your AWS credentials (access key ID and secret access key):

You will need your AWS credentials so that the migration tool can authenticate on your behalf and create SNS resources called PlatformEndpoints that are similar to your Installation objects in Parse. Just like other resources, PlatformEndpoints are referenced using ARNs. Here is how you get your AWS credentials:

  1. Navigate to the AWS credentials console here.
  2. Click Continue to Security Credentials.
  3. Click Access Keys (Access Key ID and Secret Access Key).
  4. Click Create New Access Key.

  1. From Create Access Key, select Show Access Key. Copy both Access Key ID and Secret Access Key and save them for later.

Step 4: Import Parse Push data

Download the Parse Push migration tool here.

Note: The migration tool is a standalone .jar file that you will run from your Mac/PC. You will provide the tool with the information in the form of parameters you collected in the previous steps. The migration tool requires a Java Runtime Environment (JRE). If you type java at a command line on a PC or a terminal on a Mac, and nothing appears, you’ll need to install the JRE first.

The following are the migration tool parameter requirements:

  • Exported Parse JSON file from Step 1.
  • A valid APNS .p12 push certificate (for APNS) or API Key (for GCM) from Step 2.
  • An SNS platform application and topic name from Step 3.2.
  • AWS credentials (key and secret) from Step 3.4.

Run the command as specified below with the appropriate command line options and start the migration!

java -jar SNSImportTool.jar -s -f <PATH_TO_EXPORTED_PARSE_INSTALLATION_.JSON_FILE>
--apnsName <APNS_PLATFORM_APP_NAME_STEP_3.2.9>
--gcmName <GCM_PLATFORM_APP_NAME_STEP_3.2.9>
--wnsName <WNS_PLATFORM_APP_NAME_STEP_3.2.9>
--topicName <SNS_TOPIC_NAME_STEP_3.2.10>
--awsaccess <AWS_KEY_ID_STEP_3.3>
--awssecret <SECRET_ACCESS_KEY_STEP_3.3>

 

Use --help to list a menu of options for executing the migration tool.

Parameters: The APNS, GCM, and WNS parameters are only required if you are supporting those platforms. If you leave any of the platforms out, the tool will skip any tokens that match the platform type. If you don’t provide the optional –topicName, the tool will create a default “parse_alldevicesTopic and Subscribe all PlatformEndpoints to this Topic, in addition to creating a Topic for each unique channel. Subscribing creates an association between the PlatformEndpoint and the Topic, much like the association between the Installation object and a channel in Parse Push.

After running the tool, you will see the Amazon SNS resources being created in the output as it iterates through your exported Parse Push data.

Warning: Google Cloud Messaging (GCM) tokens that do not have a corresponding GCMSenderId in the Parse Installation class cannot be migrated to Amazon SNS at this time. According to Parse, the GCM registration IDs (stored in the deviceToken field of the Parse Installation class) for your app are associated with Parse’s GCM sender ID (1076345567071), which means that only Parse has the API Key to publish to those devices. If this is the case, please follow Parse’s Exporting GCM Registration IDs solution here. In this solution, you will enable the Google Cloud Messaging API in a Google Developers Console project, update the Parse client SDK with the new sender ID from the Google Developers Console project, and re-register the device with GCM to receive new tokens associated with your sender ID. You can then come back to Amazon SNS to migrate those tokens and follow the instructions here.

What does the migration tool do?

The migration tool first verifies the PlatformApplication you provided. It then creates an Amazon SNS PlatformEndpoint for each unique token in the exported JSON file. In addition, the tool creates an SNS Topic for each unique channel and then subscribes each PlatformEndpoint to those Topics.

Let’s see what this means with an example. Say you had only one APNS token that was subscribed to three channels: "Seahawks", "Bears", and "Football." After the tool runs, it will verify the existence of the PlatformApplication that you should have created via the Mobile Hub. The name used for verification will be what you supply on the command line to the tool using the options --apnsName, --gcmName, or --wnsName. Next, it will create a PlatformEndpoint that represents the unique token, and then create three SNS Topics with the names “Seahawks”, “Bears”, and “Football” (if they didn’t exist as Topics already). The tool then subscribes the created PlatformEndpoint to all three SNS Topics. The tool will also create a “parse_alldevicesTopic and subscribe all PlatformEndpoints to it (in this case the one and only PlatformEndpoint) to allow you to send one broadcast message to all of your users.

Step 5: Post migration

After the migration is complete, you can publish directly to PlatformEndpoints to target individual devices publish to Topics to reach all users subscribed to specific interests, or publish to the “parse_alldevicesTopic to send a single message to all users across all platforms.

Here are a few additional terms that you need to know and some information that will be helpful as you migrate:

Publish: An operation (and API call) that sends a push notification to a device or a group of devices. You accomplish the former by specifying the ARN of the PlatformEndpoint in the Publish API call, and the latter by specifying the ARN of the topic which has a number of PlatformEndpoints associated with (or subscribed to) it. For more information, see the SNS documentation at: http://docs.aws.amazon.com/sns/latest/api/API_Publish.html

Subscribe: An operation (and API call) that associates PlatformEndpoints to Topics so that you can send a message to many PlatformEndpoints with a single Publish operation. You create a subscription by specifying the PlatformEndpoint ARN and the Topic ARN in the API call. For more information, see the SNS documentation at: http://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html.

Tools: AWS provides mobile SDKs, IDE toolkits, and command line tools to simplify access to AWS services from your applications with an API tailored to your programming language or platform. For mobile development, AWS offers a mobile SDK for iOS (Objective-C/Swift), Android & Fire OS, Xamarin, Unity, and JavaScript. For server-side publishing, subscribing, and management of your AWS resources, we offer SDKs for Java, .NET, Node.js, PHP, Python, Ruby, Go, and C++.

Resources: All of your SNS resources can be viewed and managed from the AWS SNS console here. You can also install the CLI or use any of the preceding AWS SDKs to subscribe, publish to, or list your resources.

Parse Push and Amazon SNS feature comparison table:

While migrating from Parse to Amazon SNS is straightforward, there are a few differences between the two services that you should familiarize yourself with to ensure your app behaves appropriately. Here’s a comparison list of Push features between the two services:

Feature

Parse Push

Amazon SNS

Subscriptions

Yes – channels

Yes – topics

Advanced Targeting

Yes – objects, users, queries, and GeoPoints

No

Custom Segments

Yes – Saved Audiences

No

Scheduled Notifications

Yes (Android/Windows Only)

No

A/B Testing

Yes – Push Experiments

No

Push Localization

Yes

No

Badge Increment

Yes – (iOS only)

No

Expiration Date

Yes

Yes

Background/Silent Push

Yes

Yes

Sound

Yes

Yes

Campaigns

Yes

No

Token Feedback

No

Yes

Token/Endpoint Event Triggers

Yes

Yes

100% Delivery Success/Failure Logging

No (“Generic” Push Delivery Report Only)

Yes (100% success/failure logs targeting each endpoint)

Pricing

·  1M unique recipients (i.e. tokens) per month.

·  $0.05 per 1,000 unique recipients after that

·  1 million free requests and mobile push delivery attempts per month.

·  $0.50 per million requests and $0.50 per million mobile push delivery attempts after that.

·  More information on pricing here

We hope these steps were useful and wish you the best with creating successful push engagements using Amazon SNS!

Looking for more information? Register to join our webinar

Other Resources: If you are interested in setting up a Parse server on AWS, we recommend that you refer to this tutorial.