Migrating to OneSignal

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

​

Prerequisites

• Setup an account at OneSignal
• Invite your team

​

Migration steps

​

1. Audit your current messaging setup

• 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

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

​

2. Core OneSignal concepts

• Users - Identified via the External ID. Users are composed of properties (tags, session data, etc.) and subscriptions (push, email, SMS).
• Subscriptions - Refers to how a user can receive messages. There are 4 types of subscriptions:
  • Mobile: Can receive push notifications, in-app messages, and Live Activities.
  • Web push: Can receive web push notifications.
  • Email: Can receive email notifications.
  • SMS: Can receive SMS notifications.
• Segments - A group of users that share common properties.
• Tags - A custom user property.
• Custom Events - An action a user takes.

​

3. Add the OneSignal SDK (developers)

​

Identify users with External ID

• Mobile SDK
• Web SDK

​

Collect new emails and phone numbers

• Email subscriptions: use the addEmail method in our Mobile SDK and Web SDK
• SMS subscriptions: use the addSms method in our Mobile SDK and Web SDK

​

4. Remove your legacy implementation

​

Push token conflicts & format

• Get device’s push token identifier using our Frontend Mobile SDK
• Get device’s identifier using our View user API

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

​

Push payload handling

​

Phased migration (mobile apps only)

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

​

5. Web push migration

• 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: Code on website and Service Worker files.
2. Add this code to make sure the Service Worker is unregistered.
3. Replace sw.js with the name of the 3rd party 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();
      }
    }
  });
}

​

6. Email and SMS setup

​

Is email warm up required?

​

Can I get a dedicated IP address?

​

7. Import existing users (optional)

​

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 for understanding.
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.

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

  {
    "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"
      }
    ]
  }

​

7. Test the migration

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.

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

• 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

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

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

• 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

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

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