Migrating to OneSignal

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

​

Choosing a migration path

​

Prerequisites

• Setup a OneSignal App
• Invite your team

​

Migration steps

​

1. Audit your current messaging setup

​

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)

• Mobile SDK setup
• Web SDK setup

​

3. Remove your legacy implementation

​

Push token conflicts

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

​

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.

​

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)

​

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

​

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