Welcome to OneSignal! This guide will help you migrate from your current push notification provider (such as Firebase) to OneSignal with minimal disruption to your users. We've designed this guide for both technical teams implementing the changes and marketing teams who need to understand the migration process.

There are two migration approaches:

• Clean migration - Using only OneSignal
• Phased migration - Temporarily using multiple push providers

1. Audit your current push setup

Before migration, take inventory of your current implementation:

For developers:

• The platforms you support: iOS, Android, Web, etc.
• The code handling push payloads recieved on the device.
• The APIs you are using for token management and notification delivery.

For marketers:

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

2. Implement the OneSignal SDK

For developers:

Follow our Mobile SDK setup and/or Web SDK setup to add OneSignal to your app or website.

3. Update your existing push provider's code

For websites you must follow the Clean Migration path.

For mobile apps, you have the option on migration paths, but we recommend Clean Migration.

Clean Migration (Recommended)

Remove all code related to your previous push provider from your application.

Benefits for developers:

• No conflicts between SDKs
• Simplified codebase
• No need to manage multiple push token systems

Benefits for marketers:

• Single dashboard for all notifications
• Consistent analytics
• Unified user segments

Web push migration

If you have an HTTPS website and use the same origin for OneSignal as your previous provider, then current subscribers will be automatically moved into OneSignal when they return to your site with the OneSignal SDK. 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 must remove the previous provider's SDK and unregister their service workers completely.
• Web push requires Service Workers and while you can have multiple service workers for your site, you need to unregister your previous provider's service worker to prevent conflicts with handling push notifications.
• Add the following code to your site to unregister the service worker for the existing service. Replace sw.js with the name of your previous push provider's service worker filename.

//change sw.js to the name of your previous service worker file
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for(let registration of registrations) {
      if (registration.active.scriptURL.includes("sw.js")) {
        registration.unregister();
      }
    } 
});
}

Phased migration (multiple providers)

If you must maintain both systems temporarily this can only be considered for iOS and Android (including Huawei and Amazon) mobile apps. Web apps cannot follow this migration path.

For marketers:

• Decide which types of messages to send through each system during transition
• Create a timeline for when to phase out the old system completely

For developers:

There are several code considerations that must be addressed to ensure a smooth transition.

Push token conflicts

Remove any 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. 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

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.

4. Import existing users into OneSignal (Optional)

Importing subscribed users that have been active in your app within the past 270 days will help minimize disruption during migration. See FCM Expired Token FAQ for details.

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

Platform considerations before import

• 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.

Process overview:

1. Please review our Users and Subscriptions docs.
2. Export test or known user data from your current provider
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 data for import:

• Push token
• Subscription type
• User identifier external_id (recommended)

Example API request:

POST https://api.onesignal.com/users
{
  "identity": {
    "external_id": "user_12345"
  },
  "subscriptions": [
    {
      "type": "iOSPush",
      "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
    },
    {
      "type": "AndroidPush",
      "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
    }
  ]
}

5. Test the migration

Thorough testing is crucial for a smooth transition.

For developers:

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

6. Pre-release check list

For marketers:

• Create a communication plan for users on older versions.
• Consider using push and in-app messages from your current provider 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.

7. Release the app with the OneSignal SDK

• 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.

8. 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.

👍

Migration complete!

You have successfully migrated to OneSignal!

For technical issues during migration, contact [email protected] with your debug logs and reproduction steps.

For strategy questions about migration planning, our customer success team can provide personalized guidance.