OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Onboarding With OneSignal

Guide on moving to OneSignal: Migration steps, importing devices and getting started quickly.

Moving to OneSignal? Good choice! We are are happy to have you!

Whether you are moving over millions of users or just getting started, this checklist will walk you through the steps needed to get going as fast as possible.

Step 1 Add the OneSignal SDK

We highly recommend setting up OneSignal with our SDK active in your apps and/or websites. Our SDKs are very lightweight and easy to integrate. On average, customers get setup and send their first push in under an hour.

Using an API-only integration is generally not recommended. Each platform (Android, iOS, Web) has different push notification requirements. Without our SDK, you will need to setup client-side functionality with native code for subscriber authentication across the platforms, the displaying of the push message, and parsing our notification payload (Android and Web). Our SDKs provide a lot of functionality and features that will cutdown your development time.

An API-only integration can work on iOS due to the standardized APNS push payload but Android's non-standard push payload and Web Push's requirement for Service Workers creates further complexity. OneSignal's SDKs are open source. Our API does expose the Add and Edit Device Endpoints and you can view the OSNotificationPayload Object in our docs if you would like to explore an API-only integration.


Next Steps After Adding Our SDK

If you previously had Subscribers to your app or website, continue to step 2.

If you are just getting started with no Subscribers previously, jump to our Features Setup.

Step 2 Migrating Users to OneSignal

Once the OneSignal SDK is integrated and active in your App and/or Website, your subscribers will be automatically and silently moved over to your OneSignal Account immediately after opening the App or Website with the OneSignal SDK active.

In certain circumstances, the ability to directly import users and start sending them push depends on the type of platform.


Data Required for Push Notifications

You cannot directly import devices without the device having a push token associated with the record. A Push Token is generated through the website or mobile app when the user subscribes.

Phone number, email address, IP address are not enough information to target a user for push.

Below are details on options available for each platform:

Importing Web Push Subscribers

Due to the way Web Push is setup by the browsers, you cannot directly migrate subscriber data from a different push provider to OneSignal. However, if your site is HTTPS and you can add the service worker files to your server, then there is a way to silently resubscribe users to OneSignal when they return to the site.


  1. You must have an HTTPS site
  2. Your users must be subscribed to the same origin/site currently (not a provided subdomain or previously HTTP)
  3. You must be able to add files to your server (cannot select "My site is not fully https" in the OneSignal dashboard)

Then those previously subscribed users will be automatically resubscribed upon returning to your site with OneSignal installed properly.


  1. Remove all your previous Push Provider's code from your site. Including their service workers.
  2. Follow our HTTPS Setup Guide for your Web Push Setup Option.
  3. Check Service Workers. If you placed your previous push provider's service workers in the root of your site (e.g then simply remove those service workers and use the OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js files.

If you added your other service works to a subdirectory (not the root) you will need to unregister your previous service workers. For example, if you added your service worker to then you will need to unregister your service worker before the user can subscribe to OneSignal, use this code to unregister your service worker:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistration ('/subdirectory/js/service-worker.js'). then (function (registration) {
    if (registration) {

Make sure to change /subdirectory/js/service-worker.js to the actual path of your service workers are found.

  1. Test your site to make sure you can subscribe and show up in the OneSignal Dashboard. In the browser's debugger console, check the Application > Service Workers and make sure no other service workers are registered or trying to register.

See Troubleshooting Web Push if you are having issues.

Then you can continue to send push notifications from your previous push provider to current subscribers. Upon revisiting your site, your subscribed users will now show up in your OneSignal Dashboard and the previous Service Worker should be removed from the subscribers browser and replaced with the OneSignal Service Worker.

At that point, the subscriber will not be able to get notifications from the previous provider and should show as unsubscribed in the previous provider's system. No duplicate notifications should occur.

Importing Mobile App Subscribers

Before migrating, we recommend updating your app to have the OneSignal SDK. This way no users will be lost between the time you migrate your current subscribers and the time you update your app.

iOS - iOS subscribers can be imported, however features like monitoring notification click rate wont work for devices with an old version of your app.

Android - Android subscribers can be imported, however they will not be able to receive notifications until they update to a version of your app with the OneSignal SDK. Therefore it's usually not beneficial to import them since they would get added to OneSignal after they updated and opened your app anyway.

You can import your current subscribers using the API Add a device POST Endpoint.

Customers on a Paid Plan with over 300,000 mobile device can contact support providing a .csv file of subscriber data. If possible to provide data similarly setup as our API Add a device POST Endpoint data and we will import them over the next few days.

Import from Urban Airship

OneSignal supports automatically importing devices from Urban Airship. Under Audience > All Users, select Actions and the Import Devices From Another Provider.

When Android devices are imported from Urban Airship they will not be able to receive notifications until they update to a version of your app with the OneSignal SDK. Therefore it's usually not beneficial to import them since they would get added to OneSignal after they updated and opened your app anyway.

Handling Custom Notification Payloads

The OneSignal Notification Payload contains a “custom” key with a nested “i” value like this: “custom”: { “i”: “”}.

On Android, if the notification payload received does not contain this, our SDK will not process the notification. However, if you have another SDK, there is no guarantee it will not process our Notifications.

On iOS, because Apple has a standard payload it will show all notification sent to the device. So if you send a push from your old platform to a device, do not send the same notification from OneSignal or the user will get it twice.

For iOS Click Handlers, depending on how you handle notification opens you might have to add a check for “custom”: { “i”: “”} data (or if you have your own format, we recommend checking for yours instead) if you need to handle the notification sent from OneSignal differently than notifications sent from other provider.

Importing Custom User Attributes To OneSignal

If you are moving to OneSignal from another provider that has custom data/attributes about users, that data can be stored in OneSignal as Data Tags which are Key: Value pairs of string or integer data. Data cannot be stored as arrays or objects in OneSignal.

If you track your own User IDs (like in your CRM or Database), you can add these to OneSignal user records as external_user_id's. See our Internal Database, DMP, & CRM Guide for more details.


Only Import Necessary Data

OneSignal automatically collects common user data which you can view here in Data Collected by the OneSignal SDK.

For custom user data, it is recommended to only import data needed for sending messages.

List Import Option

If you map User IDs from your other provider or database as external_user_ids then you can use the Importing User Attributes option.

API Import Option

If importing this data from the API, you can map the User IDs to external_user_id: "123" and data attributes as tags: {"tag_key_1":"tag_value_1","tag_key_2":"tag_value_2"}.

SDK Import Option

If using our SDK, you can add the external_user_id with our setExternalUserId method upon login to the app/site.

For data tags, use our Tagging Methods in areas that capture the data needed for push.

Updated about a month ago

Onboarding With OneSignal

Guide on moving to OneSignal: Migration steps, importing devices and getting started quickly.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.