Guides
DashboardPricingLoginSign-up for free

Importing Web Push Subscribers

SETUP - How to migrate subscribers from another Web Push vendor?

Suggest Edits

You're using OneSignal, Batch, Urban Airship or another web push provider and you want to migrate to WonderPush.
There are 2 alternative approaches.

1- Progressive migration as your users visit your website

[RECOMMENDED]

If your site is HTTPS and your users have subscribed to your own domain, then by installing WonderPush on your site, your current subscribers will be automatically and transparently migrated (without having to resubscribe) when they return to your site.

👍

Follow our two-step guide to migrate progressively

2- One-off import of your subscribers

[ADVANCED]

🚧

Different push providers expect different push notification formats, so importing your push tokens into WonderPush isn't helpful in most cases. That's why we recommend that you simply let your subscribers automatically migrating to WonderPush as they revisit the new version of your website.

Please note that the PushEngage push notification format is not compatible with WonderPush.

The overall process to import all your subscribers right away is as follows:

  1. Export your subscribers
  2. Get your VAPID key pairs from your previous push provider
  3. Configure VAPID properly in WonderPush
  4. Import your subscribers in WonderPush.
  5. Remove your previous push provider's code from your web pages.
  6. Integrate WonderPush
  7. Watch your WonderPush subscribers migrate automatically
  8. Craft your notification payload accordingly

Step 1. Export your subscribers

Your export must have, for each subscriber:

  • their push token: This is a URL like https://fcm.googleapis.com/fcm/send/…, for Chrome.
  • the auth encryption material: A small random string of around 20 characters.
  • the P256DH encryption material: A longer random string of around 90 characters.
  • the associated VAPID public key, also known as application server key, in case multiple values are present in your user base, which is rarely the case.

OneSignal

On OneSignal, here is how to export your users:

curl -XPOST \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic YOUR_ONESIGNAL_REST_API_KEY" \
    -d '{"extra_fields":["country","external_user_id","location","country","web_auth","web_p256"]}' \
    'https://onesignal.com/api/v1/players/csv_export?app_id=YOUR_ONESIGNAL_APP_ID'

You can find YOUR_ONESIGNAL_REST_API_KEY and YOUR_ONESIGNAL_APP_ID in Settings / Keys & IDs page.

The output looks like the following:

{"csv_file_url":"https://onesignal.s3.amazonaws.com/csv_exports/YOUR_ONESIGNAL_APP_ID/users_SOMEUSERID_YYYY-MM-DD.csv.gz"}

The file at the given URL has the following columns:

  • id: The unique identifier of your subscriber. We'll reuse it as the installation's id field in WonderPush.
  • identifier: The push token of your subscriber. We'll reuse it as the installation's pushToken.data field in WonderPush.
  • session_count
  • language
  • timezone
  • game_version
  • device_os
  • device_type
  • device_model
  • ad_id
  • tags
  • last_active
  • playtime
  • amount_spent
  • created_at
  • invalid_identifier
  • badge_count
  • country
  • external_user_id
  • lat
  • lon
  • web_auth: The push token auth encryption material. We'll reuse it as the installation's pushToken.auth field in WonderPush.
  • web_p256: The push token auth encryption material. We'll reuse it as the installation's pushToken.p256dh field in WonderPush.

Step 2. Get your VAPID key pairs

Contact your previous push provider and ask them your VAPID public-private key pairs.

📘

A note on Base64

There exist multiple flavors of the Base64 encoding, a widely used way of representing binary data where only alphanumeric characters can be used.

The standard Base64 variant uses uppercase letters A to Z, lowercase letters a to z, digits 0 to 9, the + and / signs as well as = for padding the length.
The URL-safe Base64 variant uses uppercase letters A to Z, lowercase letters a to z, digits 0 to 9, the - and _ signs and no padding.

You may encounter the standard Base64 variant in some places with your previous push provider. WonderPush uses the URL-safe Base64 variant everywhere for the Web subscribers.

Transforming the standard to the URL-safe variant is as easy as:

  1. Replace all occurences of individual + by an individual -.
  2. Replace all occurences of individual / by an individual _.
  3. Remove all occurences of trailing =.
  4. Remove all occurences of whitespace or line breaks, although you are unlikely to encounter any.

Step 3. Configure VAPID properly in WonderPush

If not already done, create your project in WonderPush.
Grab your Application Id and Management API access token in the Settings / API credentials page.

curl -XPATCH \
    -H 'Content-Type: application/json' \
    'https://management-api.wonderpush.com/v1/applications/YOUR_WONDERPUSH_APPLICATION_ID' \
    -d '{
        "accessToken": "YOUR_WONDERPUSH_ACCESS_TOKEN",
        "body": {
            "vapidPublicKey": "YOUR_VAPID_PUBLIC_KEY",
            "vapidPrivateKey":"YOUR_VAPID_PRIVATE_KEY"
        }
    }'

🚧

Make sure that YOUR_VAPID_PUBLIC_KEY and YOUR_VAPID_PRIVATE_KEY that your previous push provider gave you are using the URL-safe Base64 variant, without padding.

In short:

  • replace any + by a - (minus sign)
  • replace any / by a _ (underscore)
  • remove any final = or .

Step 4. Import your subscribers in WonderPush.

For each of your exported subscriber, make the following API call:

curl -XPUT \
    -H 'Content-Type: application/json' \
    'https://management-api.wonderpush.com/v1/installations/SUBSCRIBER_INSTALLATION_ID' \
    -d '{
        "accessToken": "YOUR_WONDERPUSH_ACCESS_TOKEN",
        "userId": "SUBSCRIBER_USER_ID",
        "body": {
            "device": {"platform": "Web"},
            "pushToken": {
                "data": "SUBSCRIBER_SUBSCRIPTION_ENDPOINT",
                "auth": "SUBSCRIBER_SUBSCRIPTION_AUTH",
                "p256dh": "SUBSCRIBER_SUBSCRIPTION_P256DH",
                "applicationServerKey": "SUBSCRIBER_APPLICATION_SERVER_KEY"
            }
        }
    }'
  • SUBSCRIBER_INSTALLATION_ID must be unique per subscriber. It should start with a digit from 0 to 9 or a lowercase letter from a to f. Some push provider use an UUID, you can reuse that directly.
    You can use the id field from your OneSignal CSV export.
  • SUBSCRIBER_USER_ID can be an empty string if you do not use any external CRM user id.
    You can use the external_user_id field from your OneSignal CSV export.
  • SUBSCRIBER_SUBSCRIPTION_ENDPOINT is the Web API Subscription Endpoint. It looks like https://fcm.googleapis.com/fcm/send/…, for Chrome.
    You should use the identifier field from your OneSignal CSV export.
  • SUBSCRIBER_SUBSCRIPTION_AUTH is the associated auth encryption material. It must be in the URL-safe Base64 variant.
    You should use the web_auth field from your OneSignal CSV export.
  • SUBSCRIBER_SUBSCRIPTION_P256DH is the associated auth encryption material. It must be in the URL-safe Base64 variant.
    You should use the web_p256 field from your OneSignal CSV export.
  • SUBSCRIBER_APPLICATION_SERVER_KEY is the VAPID public key (aka application server key) used when subscribing this user. Most of the time your VAPID public key is reused throughout your whole user base.

🚧

Make sure that SUBSCRIBER_SUBSCRIPTION_AUTH, SUBSCRIBER_SUBSCRIPTION_P256DH and SUBSCRIBER_APPLICATION_SERVER_KEY are using the URL-safe Base64 variant, without padding.

In short:

  • replace any + by a - (minus sign)
  • replace any / by a _ (underscore)
  • remove any final = or .

You can also give more built-in information, properties or tags as you see fit.
We recommend giving an information that will help you segment those imported users easily, like an "imported" tag or property.

Note that you can group network calls using the /v1/batch API endpoint as such:

curl -XPOST \
    -H 'Content-Type: application/json' \
    'https://management-api.wonderpush.com/v1/batch' \
    -d '{
        "accessToken": "YOUR_WONDERPUSH_ACCESS_TOKEN",
        "requests": [
            {
                "method": "PUT",
                "path": "/v1/installations/SUBSCRIBER_INSTALLATION_ID",
                "args": {
                    "userId": "SUBSCRIBER_USER_ID"
                },
                "body": {
                    "device": {"platform": "Web"},
                    "pushToken": {
                        "data": "SUBSCRIBER_SUBSCRIPTION_ENDPOINT",
                        "auth": "SUBSCRIBER_SUBSCRIPTION_AUTH",
                        "p256dh": "SUBSCRIBER_SUBSCRIPTION_P256DH",
                        "applicationServerKey": "SUBSCRIBER_APPLICATION_SERVER_KEY"
                    }
                }
            },
            ...
        ]
    }'

The response will look like the following:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success":true,
    "responses": [
        {"success":true},
        ...
    ]
}

Step 5. Remove your previous push provider's code from your web pages.

Uninstall your previous push provider's snippet from your page.
If you are using your own service worker, uninstall your previous push provider from there too.
Otherwise we recommend that you keep your previous push provider's dedicated service worker file hosted at your website root for a while (something looking like mypreviouspushprovider-service-worker.js), to minimize potential disruption for your existing users.

Do not deploy your new website just yet, wait for the next step.

Step 6. Integrate WonderPush

Follow our Website Quickstart guides.

You can now deploy your new website.

Step 7. Watch your WonderPush subscribers migrate automatically

As your users visit your website, they will be subscribed imported inside WonderPush.
At the same time, the imported subscriber's installation will become opt-out, so you won't send duplicate notifications.

Step 8. Craft your notification payload accordingly

When sending notifications, make sure to use payload override to present the previous push provider's SDK with a payload that it can act on to display the notification.

You can use you DevTools in the Application / Background Services / Push messaging tab to record received push notifications in order to see the expected format.

OneSignal

For supporting your imported OneSignal subscribers, you can use the following payload:

{
    "custom": {
        "i": "00000000-0000-4000-8000-000000000000",
        "u":"URL_TO_REDIRECT_UPON_CLICK",
    },
    "title":"The notification title",
    "alert": "The notification text",
    "icon":"https://example.com/icon.jpg",
    "image": "https://example.com/image.jpg"
}

Updated over 1 year ago