Skip to main content
This guide covers how to 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

​
Prerequisites

Before you begin:

​
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 push and in-app message events:
    • Foreground displaying and click handling
    • Deep link usage for push, email, etc.
    • Push token and payload handling
  • How you are collecting email addresses, phone numbers, push tokens, etc.
  • Email domains and DNS ownership
  • SMS senders and opt-in mechanisms
For marketers:
  • The types of messages you send (transactional, marketing, etc.) and the templates for each
  • How you segment and target users
  • The analytics or conversion metrics you track

​
2. Map your terminology to OneSignal

Most messaging platforms share similar concepts under different names. Here’s how OneSignal’s terms map to what you’re likely already using:
Your platformOneSignal termDetails
User / contact / profileUserIdentified by an External ID. Contains properties and subscriptions.
Push token, email address, phone numberSubscriptionA channel through which a user can receive messages (mobile push, web push, email, SMS).
Audience, cohort, listSegmentA dynamic group of users based on shared properties or behavior.
Custom attribute, user propertyTagA key-value pair attached to a user for targeting and personalization.
Tracked action, analytics eventCustom EventAn action a user takes, used for segmentation and triggering messages.

​
3. Add the OneSignal SDK (developers)

Set up the OneSignal SDK in your mobile app and/or website:

Mobile SDK setup

Required for in-app messages and recommended for push notifications on iOS and Android.

Web SDK setup

Required for web push notifications.
After integrating the SDK, use the following methods to identify users and collect subscription data:
  • login — Set the External ID to identify a user across devices and channels.
  • addEmail — Create an email subscription from an address collected in your app or site.
  • addSms — Create an SMS subscription from a phone number collected in your app or site.
See the SDK references for implementation details:

Mobile SDK reference

Methods for login, addEmail, addSms, push token access, and notification listeners.

Web SDK reference

Methods for login, addEmail, addSms, and web push event handling.

​
4. Remove your legacy implementation

There are two migration paths:
  • Clean migration — Remove your old SDK entirely and replace it with OneSignal in a single app release. This is the recommended approach.
  • Phased migration — Keep both SDKs temporarily, sending from each provider to different user groups based on app version. Use this only if you cannot remove the old SDK in one release.
In either case, remove legacy methods and APIs for collecting push tokens, email addresses, and phone numbers. Push token collection in particular can create conflicts with the OneSignal SDK.

​
Push token conflicts & format

Remove all legacy code generating push tokens. Only allow OneSignal to generate the push token which happens automatically when the SDK is initialized. If needed, use our SDK to get the token and send it to your other provider or backend. Methods for doing so:
Push token formats differ by platform (iOS APNS vs. Android FCM). See Push token formats for details.

​
Firebase Messaging SDK conflict

If your app includes the Firebase Messaging SDK (firebase_messaging or a custom FirebaseMessagingService), it can intercept FCM messages before OneSignal processes them. This causes notifications to show as “Delivered” in OneSignal but never appear on the device. To resolve this:
  • Remove legacy Firebase receivers from AndroidManifest.xml.
  • Do not call FirebaseMessaging.getToken() or FirebaseMessaging.deleteToken().
  • Ensure OneSignal is the only SDK managing the push token lifecycle.
See Firebase Messaging SDK conflict for full troubleshooting steps.

​
Push payload handling

If using OneSignal and another push provider in parallel, you’ll need to prevent your other SDK from processing OneSignal notifications to avoid duplicates. OneSignal’s push payload contains a "custom" key in the rawPayload that distinguishes it from other providers. If running both SDKs, update your notification handler to check this key so your legacy SDK doesn’t process OneSignal notifications. See the OSNotification payload reference for details.

​
Phased migration (mobile apps only)

A common approach is to continue sending from your old provider to users on the older app version and from OneSignal to users on the newer version. However, if you must keep both SDKs for a limited time:
  • Let OneSignal manage push tokens exclusively. Share the token with your old system if needed (see Push token conflicts above).
  • Update payload filters so your legacy SDK ignores OneSignal pushes (see Push payload handling above).
  • Send from your old provider to users on the older app version and from OneSignal to users on the newer version.
  • Set a clear cutoff date and phase-out plan.

​
5. Web push migration

If you’re using the same HTTPS site origin, subscribers are silently added to OneSignal on their next visit — no prompt is shown and they can receive push immediately. Web push subscriptions cannot be imported due to browser security limits. Before OneSignal can take over, you must unregister your old push service workers:
  1. Remove the legacy SDK code and Service Worker files from your website.
  2. Add the following snippet to unregister the old Service Worker. Replace sw.js with the filename of your legacy provider’s 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();
      }
    }
  });
}

​
Migrating between OneSignal apps

If you are moving subscribers from one OneSignal app (App A) to another (App B):
  • Web push subscriptions cannot be transferred directly between apps. Each subscription is tied to both your site’s domain (origin) and the OneSignal App ID.
  • To migrate, update your site’s OneSignal initialization code to use App B’s appId: 
OneSignal.init({
  appId: "YOUR_APP_B_ID",
});
  • When a user revisits your site, the browser’s existing push permission will allow OneSignal to silently register them in App B.
  • No new permission prompt will appear, but users must visit your site at least once for the subscription to be created in App B.
  • Subscribers will continue to appear in App A until they become inactive.
Best practice: Stop sending from App A once you confirm enough users have migrated. Monitor subscriber counts in both apps to validate migration progress.

​
6. Email and SMS setup

If you are sending emails and/or SMS with OneSignal, you will need to follow our Email setup and SMS setup guides. Migrating your current email sending domain to OneSignal requires updating the DNS records. You can set up multiple email senders in OneSignal if needed. Migrating SMS senders may take time. Contact support@onesignal.com if you need assistance.

​
7. 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 the Users and Subscriptions docs.
  2. Export test user data from your old system.
  3. Format data for OneSignal’s Create user API.
  4. Import test users first. Once verified, repeat the process for remaining users before release.
Each user needs an external_id (identity) and at least one subscription with a type and token (or email/phone_number). See the Create user API reference for required fields, supported subscription types, and example payloads.

​
8. 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 development and marketing teams:
  • Send test notifications from OneSignal to imported users before adding the OneSignal SDK.
    • 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 adding the OneSignal SDK.
    • 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 checklist

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 users 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 apps 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 messages 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 and confirm with your developers which migration path was taken (clean or phased) and whether users were imported.
  • In your previous platform, create a segment of users who have not yet updated to the new app version. Continue sending from your old provider to this group, nudging them to update.
  • Stop sending from the previous provider once subscriber counts stabilize in OneSignal.
  • If following a phased migration, remove the old provider’s SDK in your next app release after the cutoff date.

​
FAQ

​
Can I run OneSignal alongside my current push provider?

Yes, but only temporarily. Running two push SDKs in parallel can cause token conflicts and duplicate notifications. If you need a phased migration, follow the Phased migration guidance to prevent conflicts and set a clear cutoff date.

​
Can I import web push subscribers?

No. Browser security restrictions prevent transferring web push subscriptions between providers. When you integrate OneSignal on your site, existing subscribers are silently re-registered on their next visit — no new prompt is shown. See Web push migration.

​
Do I need to re-prompt users for push permission after migrating?

No. If users already granted push permission to your app or site, OneSignal uses the existing permission. No new prompt is displayed.

​
Is email warm-up required?

Not if your sending domain already has an established sending reputation. Warm-up is only required if you are using a dedicated IP address.

​
Can I get a dedicated IP address?

Yes, depending on your plan type and sending volume. Contact your account manager for details.

​
How long should I keep sending from my old provider?

Continue sending from your old provider until most users have opened the updated app with the OneSignal SDK. Monitor subscriber counts in both systems and stop sending from the old provider once the numbers stabilize.
You have successfully migrated to OneSignal! For strategy questions about migration planning, contact our customer success team for personalized guidance.
Need help?Chat with our Support team or email support@onesignal.comPlease include:
  • Details of the issue you’re experiencing and steps to reproduce if available
  • Your OneSignal App ID
  • The External ID or Subscription ID if applicable
  • The URL to the message you tested in the OneSignal Dashboard if applicable
  • Any relevant logs or error messages
We’re happy to help!