Migrating to OneSignal

Welcome to OneSignal! This guide will help you migrate from your current messaging platform to OneSignal with minimal disruption.

It’s designed for:

• Developers implementing the OneSignal SDK
• Marketers managing campaigns and analytics

​

Choosing a migration path

If you are moving push subscribers, there are two ways to migrate:

​

Prerequisites

Before you begin:

• Setup a OneSignal App
• Invite your team

​

Migration steps

​

1. Audit your current messaging setup

Before migration, take inventory of your current implementation:

​

For developers:

• The platforms you support: iOS, Android, Web, email, SMS, etc.
• The code handling message events:
  • Receiving messages
    • Push: Foreground and click handling
    • Deep links like from push, email, etc.
• The APIs you are using for token management and notification delivery.
  • How are you collecting email addresses, phone numbers, push tokens, etc.

​

For marketers:

• The types of messages you send: (transactional, marketing, etc.)
• How you are segmenting and targeting users.
• The analytics or conversion metrics you track.

​

2. Add the OneSignal SDK (developers)

Set up OneSignal:

• Mobile SDK setup
• Web SDK setup

​

3. Remove your legacy implementation

Remove and 3rd party methods or APIs for collecting email addresses and phone numbers. Keep your existing opt-in prompts or UI.

​

Push token conflicts

Remove all legacy code generating push tokens. Only allow OneSignal to generate the push token.

If needed, use our SDK to get the token and send it to your other provider or backend. Methods for doing so:

1. Get device’s push token identifier using our Frontend Mobile SDK
2. Get device’s identifier using our View user API

OneSignal’s push token format:

• iOS Push APNS token format: 64 characters, hexadecimal characters only (0-9,a-f). deviceToken.map {String(format: "%02x", $0)}.joined()
• Android Push FCM token format: Typically 163 characters, alphanumeric characters, may contain hyphens, colons and underscore.

​

Payload handling

You’ll need to prevent your other SDK from processing OneSignal notifications to avoid duplicates.

OneSignal’s push payload contains a specific "custom" key within the rawPayload of the OSNotification object which our SDK uses to determine whether to handle the notification or not.

You will need to update your Android NotificationCompat and iOS UNNotificationServiceExtension to listen for an object on the OSNotification payload that is different from your other provider’s payload to prevent it from handling notifications sent from us.

​

Phased migration (mobile apps only)

If you must keep both providers for a limited time:

• Do not let multiple SDKs generate push tokens. Let OneSignal handle it, and share the token with your old system if needed.
  • Use Frontend SDK or View user API
• Update payload filters so your legacy SDK doesn’t process OneSignal pushes.
  • OneSignal uses a "custom" key in its rawPayload (docs).
  • Check this key in UNNotificationServiceExtension (iOS) or NotificationCompat (Android).
• Decide which provider handles what types of notifications.
• Set a clear cutoff date and build a phase-out plan for legacy systems.
  • Create a notification template for each type of notification you send.
  • Set up your old provider to send messages to users on the older version of your app and OneSignal to send messages to users on the newer version of your app.
  • Create segments to target specific user groups.

​

4. Web push migration

• If you’re using the same HTTPS origin, subscribers will be silently re-subscribed to OneSignal on their next visit. No prompt will be shown, and they can get push from OneSignal immediately after. They should also stop getting push from the previous provider.
• You cannot import web push subscriptions due to browser security limits. OneSignal will register users when they return.
• You must unregister your old push service workers before OneSignal can take over.

1. Remove the legacy SDK and push config
2. Unregister their service worker:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for (let registration of registrations) {
      if (registration.active.scriptURL.includes("sw.js")) {
        registration.unregister();
      }
    }
  });
}

​

5. Import existing users (optional)

Importing subscribed users that have been active in your app within the past 270 days will help minimize disruption during migration.

We recommend you start by importing known test users, then import the remaining users before app launch.

​

Platform considerations

• Email addresses must be from active and valid users. Do not import email addresses that have never clicked or opened emails before.
• Phone numbers must be in a specific format and users must have consented to receive SMS.
• iOS subscriptions can start receiving push notifications immediately after import. Features like notification click tracking and confirmed deliveries require our SDK to be active on the device.
• Android/Huawei/Amazon subscriptions must have our SDK active on the device to receive notifications, either through an auto-update or manual update.
• Web subscriptions cannot be imported. If you follow the above in Web push migration, the web push subscription will be created and push token fetched via our SDK when the user returns to the site.

​

Import steps

1. Review Users and Subscriptions docs.
2. Export test user data from old system.
3. Format data for OneSignal’s Create user API.
4. Import test users and upon successful testing, keep the process to repeat in pre-release checklist.

Required fields:

• token - The push token or email address or phone number
• type - The type of subscription: iOSPush, AndroidPush, WebPush, Email, SMS
• external_id - A unique identifier for the user. This is recommended to be used for tracking and analytics.

Example API request:

  {
    "identity": {
      "external_id": "user_12345"
    },
    "subscriptions": [
      {
        "type": "iOSPush",
        "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
      },
      {
        "type": "AndroidPush",
        "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
      },
      {
        "type": "Email",
        "email": "test@example.com"
      },
      {
        "type": "SMS",
        "phone_number": "+1234567890"
      }
    ]
  }

​

6. Test the migration

Thorough testing is crucial for a smooth transition.

1. Enable Debug Logging in the OneSignal SDK.
2. Test on real devices for all platforms (Android, iOS, Web, etc.).
3. Verify both foreground and background notification handling.

Test scenarios for developers and marketers teams:

• Send test notifications from OneSignal to imported users before app update.

  • You should receive the push on iOS but will not get confirmed delivery or click analytics.
  • You may receive the push on Android if you have another push SDK and did not implement the Payload handling requirements yet. The notification is likely missing data and doesn’t work as expected when clicked.

• Send test notifications from OneSignal to imported users after app update.

  • You should receive the push on both Android and iOS along with confirmed delivery and click analytics.

• Test notification behavior with app in different states.

• Verify deep links and custom actions work correctly.

If using multiple providers:

• Send from both your current provider and OneSignal.
• Check for duplicate notifications
• Verify each provider’s notifications display correctly
• Test user login/logout scenarios

​

Pre-release check list

For marketers:

• Build a messaging plan to prompt app updates
• Consider using push and in-app messages from your old system to gently remind users to update.

For developers:

• Verify that push and in-app message analytics are working as expected.
  • Click events and confirmed delivery are tracked across Android and iOS.
• Verify click events and foreground received events are handled correctly for messages sent from both providers.
• If importing users, export Android and iOS user that have been active in your app within the past 270 days to prevent importing expired tokens. See FCM Expired Token FAQ for details.

​

Release your app/site

• Most users will have their app’s automatically update to the latest version.
• When users open your updated app, they will not be prompted to subscribe to push notifications if permissions were already granted—either through the required permission prompts or the app’s notification settings.

If you did not import users:

• Users will be created automatically in OneSignal when they open the updated version of the app. They will not be prompted for push if previously subscribed.
• You will need to wait for them to open the updated app before you can send them messages.
• Continue sending notifications and in-app message from the previous push provider for a couple days until enough users show up in OneSignal. Send additional alerts asking them to update the app to the latest version.

​

Monitor results

For developers:

• Monitor error rates and crashes after deployment.
• Watch for unexpected token invalidations.
• Check SDK integration analytics.

For marketers:

• Mark the date of app release.

• Communicate with your developers on:

  • Which migration path was taken (Clean or Phased migration).
  • Were users imported?

• If following a Clean migration:

  • In the previous platform, create a segment or cohort of users that continue to be active. Check their session times, message received, and click events.
  • Only users that have not updated the app should continue to be active and contained in this group.
  • Continue sending push and in-app messages from your previous provider to these users, gently nudging them to update.
  • Stop sending from the previous provider until you are ready to move completely to OneSignal.

• If following a Phased migration:

  • In the previous platform, create a segment or cohort of users that have the the older app version before OneSignal.
  • Continue sending push and in-app messages from your previous provider to these older-app users, gently nudging them to update.
  • Stop sending from the previous provider until you are ready to move completely to OneSignal.
  • Remove the previous push provider’s code on the next app release.