Overview

Batch allows you to migrate seamlessly from the majority of push solutions on the market. Our migration methodology enables you to keep reaching your whole audience and migrate your running campaigns without interruption.

Here is an overview of the migration steps:

1. Integrate Batch SDK in your app (optionally keep the other provider's SDK for the first release);
2. Tag your app to keep collecting the necessary custom data on your users;
3. Get the push payload expected by your former push solution and Import your current push tokens to target users who have not upgraded the app yet;
4. Migrate your push campaigns from your former push solution to Batch without interruption.

Prerequisites

Here are the three steps you need to follow to start the migration:

1. Create an account on https://batch.com/register. We recommend that you invite your team members from the account manager section (in the bottom left corner of your dashboard, under "Manage Team" → "Invite user").
2. Create your apps on Batch dashboard. We recommend that you create two applications per OS on the dashboard: one for tests and one for production (e.g. MyApp and [DEV] MyApp). This will allow you to use the Live API Key for all your apps and test all features before going live.
3. Integrate Batch SDK in your app following our dedicated documentation (iOS / Android / Cordova / Flutter / React Native).

Migration types

Depending on your constraints, you will choose to keep or remove the SDK of your previous push provider for the first release of your app with Batch. Here are details on these two migration types to help you make a decision.

Note: Both methods guarantee a 100% import of tokens and the possibility to target users who have updated the app or not.

Keep both SDKs: Staged migration

In this case, the first app release integrates both the previous push solution’s SDK and Batch SDK. This makes it possible to use one or the other solution in parallel to send push notifications as long as the SDKs coexist in the app.

The timeline for teams training on Batch dashboard and tokens export/import is more flexible with this method. There is no sudden service interruption with your former push provider. The cohabitation of SDKs can cause duplicate pushes on Android. In this case, you need to use an Interceptor in your app (see Push payload).

Include only Batch SDK: Hot swap migration

The SDK of the previous push solution is removed from the app once Batch SDK is integrated. As soon as the version of the app with Batch is released, Batch is the only solution that collects the new push tokens, and becomes the only solution that you can use to target your userbase.

This method allows you to migrate within a short timeframe, but implies fixed tokens export dates and that your marketing teams are comfortable with using the dashboard before the first app release with Batch.

Tagging plan

You should list the campaigns to be migrated in order to determine the tagging plan to be implemented. This guide can help you creating and implementing the tagging plan: Creating a tagging plan.

Important note: You should keep the same attributes and tags names as your previous tagging plan to ensure that your imported tokens will be targeted by your campaigns (see how to import custom data with your push tokens).

Push tokens import

A push token is an anonymous ID generated by the push services (Apple, Google etc.) that is used to target your users via push notifications. In the context of a migration, importing all your existing tokens makes it possible to reach your whole userbase, including users who don’t have a version of the app that includes Batch SDK yet.

Note: You should plan to export the tokens after the apps have been released with the Batch SDK to avoid any loss in the collection of tokens between the time of export and the time when Batch starts collecting them.

Here are the detailed specifications for the tokens import: Importing your tokens.

Push payload

After migrating your push tokens to Batch, you will be able to target users who are still using a version of the app that does not include Batch SDK.

In order to contact these users correctly, you need to use the payload that is expected by the SDK of your previous push solution. You have to get in touch with your previous push provider to get it.

iOS

The iOS payload of a push notification is standard and push notifications are displayed by the system. The expected payload is still needed to manage deeplinks.

Android

On Android, push notifications are handled by the SDK. The expected payload is required to manage the whole content: the title and body of the push notification, the deeplinks etc. In case of a staged migration (see Migration types), both SDKs might try to display the notification sent by Batch, which may result in duplicate push notifications.

To address this, here is an interceptor to be integrated into your app that disables the Batch receiver when the payload of another solution is detected (read more on how to register it here):

package com.batchlabs.android.batchstore.core;
​
import android.content.Context;
import android.os.Bundle;
import android.support.annotation.NonNull;
import android.support.annotation.Nullable;
import android.support.v4.app.NotificationCompat;
​
import com.batch.android.BatchNotificationInterceptor;
​
public class BatchInterceptor extends BatchNotificationInterceptor {
    @Nullable
    @Override
    public NotificationCompat.Builder getPushNotificationCompatBuilder(@NonNull Context context, @NonNull NotificationCompat.Builder defaultBuilder, @NonNull Bundle pushIntentExtras, int notificationId) {
        if (pushIntentExtras.getString(<KEY_FROM_OTHER_PAYLOAD>) != null) { // replace <KEY_FROM_OTHER_PAYLOAD> with a key that is always contained in the payload expected by the SDK of your previous push provider
            return null;
        }
        return defaultBuilder;
    }
}

Note: In case you cannot import your push tokens or retrieve the payload expected by your previous push provider, you will need to start collecting your userbase from scratch. This happens for example if you previously used Firebase as a push service (read more here).

Testing

Once all elements have been integrated, you need to test the basic implementation following these guides: iOS / Android.

As part of the migration process, it is crucial to ensure that all users will be contacted correctly and that there is no unexpected behaviour in any version of the app. You will find all the extra testing steps here: Testing.

Campaigns migration

Once your app has been released with Batch SDK and your tokens have been imported, you can start migrating your push campaigns. Here is how to proceed:

1. Create your campaigns as drafts on Batch dashboard
2. Deactivate your campaigns running with your previous push provider
3. Activate your campaigns on Batch dashboard

Warning: You must never run the same campaign from both push solutions: some tokens might be present in both userbases and might receive the notification twice.

The process of campaigns migration is detailed here: Campaigns migration.