If you are already using web push notifications with another provider, then you probably want to migrate your existing userbase to Batch. The methodology described below will allow you to transfer to Batch all users who are already subscribed to notifications on your website.

The steps are very straightforward.

Understanding web push protocols

Here comes some context about the key points discussed in this article:

VAPID keys

VAPID stands for Voluntary Application Server Identification.

Most browsers such as Chrome, Firefox, Edge and derivatives support the Web Push API W3C standard for push notifications.

Within that standard, each website domain can be identified with a pair of public and private VAPID keys.

VAPID keys mainly serve two purposes:

  1. When a user subscribes to push notifications, a "push token" is generated, which is attached to these VAPID keys.

  2. A push provider (e.g. Batch) needs the VAPID keys to identify itself to a push service (e.g. Google Chrome's push service) and deliver a notification to a visitor of your website.

You can only send notifications to tokens tied to your own pair of VAPID keys. You will find more information on how web push notifications work here.

Apple Push Notification service (APNs)

Before Safari v.16.1 on macOS Ventura, Safari only relied on Apple's push protocol for web push notifications: Apple Push Notification service (APNs).

Push providers like Batch needed a certificate delivered by Apple to identify themselves to APNs and be able to contact the tokens of your visitors. This is why Safari (< v.16.1 on macOS Ventura) support requires an extra step during the setup. An APNs push certificate has a validity of one year, and push tokens are not attached to a specific certificate.

Since Safari v.16.1 on macOS Ventura, Web Push Standard protocol is also supported by Safari. You don't need to rely on APNs to send web push notifications to users using the latest versions of Safari.

Migrating your userbase

The migration is based on Batch's re-registration script. It is some additional code included in the Batch JavaScript tag, and will allow the site's current opt-in users to be registered on the new pair of VAPID keys generated by Batch, without any interruption in service.

The users tokens will be migrated to Batch as they return to your website, and they will not be requested to provide push permission again.

Make sure to refer to your dedicated Solutions Engineer or reach out at support@batch.com to get this script.

1. Remove the existing configuration

A. Code on the website pages

Remove the code used to initialize the SDK of the previous web push provider, and any code calling its functions.

B. Service worker

Keep the existing service worker file, which should stand at the root of the website, without modifying it.

By keeping the file untouched, the previous service worker will not be updated until the user returns on the website and will still be able to display a push notification. See Accelerate the migration part below for more details.

Delete the previous file a few weeks after the Batch release, or as soon as you stop using your previous web push tool.

⚠️ If you are using a shared service worker (e.g. PWAs) and want to keep sending push notifications from your previous tool, create a new file for your service worker that integrates the Batch code.

2. Integrate Batch into your website

Follow the Batch web integration steps. When creating the app on the dashboard, new VAPID keys will be generated.

The JS tag sent by our team will include the re-registration script, so there will be no additional action needed on your side.

For Safari, you will need to generate a new APNs certificate.

You could use the current one, but the Safari package installed on the browser would remain controlled by your previous provider, who could for example change the website name attached to a push.

Accelerate the migration

The previous configuration remains cached until the user returns to the website. This means that you can send push campaigns from your old tool in addition to the campaigns sent with Batch. Users will never receive push notifications from both Batch and your previous web push notification provider. This will allow you to continue to address your entire opt-in base while accelerating the migration process:

  • New users and those who have already returned to the website will be targeted by Batch campaigns, as their token is attached to Batch's VAPID keys, and the push will be interpreted and displayed by our service worker.

  • Old opt-in users who have not yet returned to the website will be targeted by the campaign of your previous tool, because their token is still attached to the old VAPID keys, and the notification will be displayed by the service worker of the previous provider.

You can also use any other channel to bring traffic to your website (e.g. email).

Can I import a file with all my existing tokens?

Note: A service worker is a script that your browser runs in the background, separate from a web page. This is what will display the push notification.

The web push format does not allow to import the tokens at once as for mobile apps.

Each service worker expects information in non-standard fields (e.g. title, description, etc.) to display the message contained in the received notification. These fields are different for each provider, and there can only be one service worker on a website.

As long as the user has not returned to the site, the SDK and service worker of the previous provider are still running. If this user is targeted by a notification sent from Batch, the notification would be badly displayed or not displayed at all, because it will be interpreted by the service worker of the previous provider.

Using the vapid keys of the previous provider

If you are able to recover the public and private VAPID keys used by your previous provider, you can also reuse them with Batch. In this case, our re-registration script will not be necessary. The result will be the same: when a user who already opted in visits the website, Batch will collect the existing token and you will be able to address this user with Batch.

You will have to replace the VAPID keys of the dashboard generated by Batch with the old keys:

⚠️ Make sure that the public VAPID key in the JS tag coincides with the dashboard key. Changing the VAPID keys after integrating Batch JS Tag wouldn't have any effect.

Testing the migration

Once the integration is complete, your dedicated Solutions Engineer will verify that the migration is successful, and that the old tokens are attached to the new VAPID keys in Batch.

To perform this verification on your side, there are two simple steps to follow:

If the push is well received, it means that the push token has been attached to the new VAPID keys of Batch.

Congrats, you can now use Batch to its full potential 🚀

Did this answer your question?