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.

Quick Reference


Step 1 Setup OneSignal

  • Recommended: Use the SDK Integration.
  • Discussion of API-only integration

Step 2 Migrating Users to OneSignal

Step 3 Connect User Data to OneSignal

Step 4 Send OneSignal Event Data & User Attributes

  • Add Custom User Attributes and Event data to target users with push and customize push messages.

Step 5 Outcomes

  • OneSignal's Advance Analytics to get more insight into your messaging campaigns.

Step 6 Sending Messages

Start sending messages to users! Including:

Step 1 Setup OneSignal

It's recommend to integrate the OneSignal SDK in your apps and/or websites. Our SDKs are open source, very lightweight, and easy to setup. On average, customers get setup and send their first push in under 30 minutes.


Next Steps After Adding The SDK

If you previously had Subscribers to your app or website, continue to Step 2 Migrating Users to OneSignal.

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

API Only Integrations (Not Recommended)

Using an API-only integration is generally not recommended. Each platform (Android, iOS, Web) has different push notification requirements. For example, iOS has a standardized APNS push payload while Android has a non-standard push payload that requires additional dev work to handle client side and Web Push requires Service Workers.

Without our SDK, you will need to setup client-side functionality with native code for subscriber authentication, the displaying of the push message, and parsing our notification payload (Android and Web). Our SDKs provide a lot of functionality that will cutdown your development time.

If you want to continue pursuing an API-only integration, you can use the Add a device endpoint to add devices to OneSignal and the Edit device endpoint for updating device records already created.

Handling Custom Notification Payloads

The OSNotificationPayload Object 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.

Step 2 Migrating Users to OneSignal

Once the OneSignal SDK is integrated, your subscribers will be automatically moved into your OneSignal Account upon opening the App or Website with the OneSignal SDK active. Subscribed devices will not be shown a prompt, they will continue to be subscribed within OneSignal and can get push immediately.


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.



Importing Web Push Subscribers

Detailed steps to automatically and silently move subscribers to OneSignal.

Importing Mobile Push Subscribers

If transferring from Airship, see Import from Urban Airship

Importing Email Addresses

OneSignal supports email integrations with Sendgrid, Mandrill, and Mailgun.

Importing Web Push Subscribers

Due to the way Browsers have setup Web Push, you cannot directly migrate subscriber data from a different push provider into OneSignal. However, if your site meets the below requirements, then there is a way to automatically resubscribe users into OneSignal when they return to the site. No prompt will be shown and they can get push immediately upon return. They should also stop getting push from the previous provider.


  1. You must have an HTTPS site
  2. Your users must be subscribed to the same origin you are adding to OneSignal.
  3. You must be able to add Service Worker files to your server (cannot select "My site is not fully https" in the OneSignal dashboard).

If your site does not meet these requirements, users will need to resubscribe to the site. You can continue to follow these steps and send push from the old provider until you are ready to fully move to OneSignal. Eventually devices will stop getting push from the previous provider if you follow the steps below and once the previous Service Worker files are replaced with the ones we provide.


  1. Remove all your previous Push Provider's code from your site. Including their service workers.
  2. Follow our Web Push Setup.
  3. Check your 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 (shown in setup).

If you added your other service workers 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 subscribers can be imported, however features like monitoring notification click rate wont work for devices with an old version of your app.

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.

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.

Step 3 Connect User Data to OneSignal

OneSignal stores user data at the device and message channel level. Each device can have a Push and Email record which will get its own Player ID (OneSignal Device ID). For example, if I subscribe to Push Notifications on your website and mobile app. I will have 2 separate Player ID records in OneSignal. If you incorporate Email, then I will have 3 records (2 Push Records and 1 Email Record).

To associate multiple Player ID records together, we provide the setExternalUserId method which takes your single User ID and maps it to the current Player IDs (both Push record and Email record if set). Similarly, the setEmail method will associate the current push record with the newly created or current email record in the system. Multiple Emails can be associated with multiple Player ID records and tied together with External User IDs.

You can disassociate External User IDs with the removeExternalUserId (removed External User ID from the current Player ID record) and Emails with logoutEmail method respectively (keeps email record but removes the connection with the current Player ID).


Setup Recommendation

We recommend calling these methods each time the user gets authenticated (logs in) to your site or mobile app to make sure your custom User ID and Email is associated with the OneSignal record.

See Database, DMP, & CRM Integration for details on integration.

Once this mapping is complete, any custom data added to each device record through our SDK will be added to both the current Player IDs (push and email). Our SDK tagging methods will not add the same tags to other associated External User IDs. For example, if you call our sendTag method, the Player IDs currently using the app or site will get the tags, but other Player ID records associated with the External User ID will not get those tags. To tag users across multiple External User IDs, see our server side API Edit tags with external user id.

Step 4 Send OneSignal Event Data & User Attributes

Custom event and user data can be stored in OneSignal as Data Tags which are key : value pairs of string or integer data. Tags can be used for Segmentation and Message Personalization.

Helpful docs to get setup with tags:

Step 5 Outcomes

Outcomes are OneSignal's advanced analytics that help you really track how well your messages are performing. While tracking "clicks" is nice, you want to know if users are actually doing what you want them to do! Examples include incrementing revenue brought in from push, tracking user behavior after entering the app/site, and tracking user click stats like country or language or app version.

Step 6 Sending Messages

Once you are here, you have likely subscribed users and ready to start sending more messages!

You are likely a OneSignal Pro at this point, but some helpful next steps include:


Congrats πŸŽ‰

If you have come this far you have fully integrated OneSignal and are now a master!

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.