Guides
Log InSign Up

Onboarding With OneSignal

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

Suggest Edits

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

Whether you are moving millions of users or just getting started, this checklist walks through getting set up as fast as possible. If you haven't done so already, head to onesignal.com and setup an account. It's free!

If you have other team members that need access to your OneSignal instance, see our Account Management page to invite them.

Identifying Users

Understanding user identifiers

The current Version 9 documentation is dedicated to OneSignal's legacy device-centric model (player ID). If you are using OneSignal's SDKs below 5.0, you are in the right place. If you setup the OneSignal SDK with version 5+ or wish to migrate to OneSignal's new user-centric data model (OneSignal ID), please refer to Version 11 of our documentation for user-centric information.

OneSignal's legacy user data is stored at the subscription-level as a subscription ID (aka player ID) when the device:

For example, a user that subscribes to Push Notifications on your website and downloads your iOS mobile app will have 2 OneSignal Player ID records. If you incorporate Email, then that single User will have 3 records: 2 Push Records (web and iOS) + 1 Email Record.

To associate multiple Player ID records together, use an External User Id to map your Database/DMP/CRM User ID to the current Player ID. The "external_user_id" can be anything like an email, username, or Database User ID.

If you are integrating with your own database or one of our partners like Mixpanel, Hubspot, Amplitude or Segment, please follow the setup guides listed in our Integrations Page.

Integrate OneSignal SDKs

Our SDKs are open source and easy to setup. On average, customers get setup and send their first push in under 30 minutes. Please contact OneSignal if you require support in onboarding without our SDK.

Client-side SDKs

Required for Push, In-App Messages, and Live Activities; Recommended for SMS and Email

Follow the steps in our Quickstart guides to get started integrating our Client-side SDKs:

Server-side SDKs

Recommended for SMS and Email

As you continue integrating OneSignal into your application, you may find it helpful to use one of our Server-side SDKs to simplify and orchestrate API calls.

Note on Server API Integrations for Push Notifications

OneSignal provides the Add a device, Edit device, and Edit tags with external user id APIs for creating and updating subscription data along with the Create notification API sending push notifications, email, and SMS messages. The OneSignal SDK is required if you plan to use the In-App Messaging functionality.

Server API-only integrations are possible but not recommended because push notifications have several different requirements that our SDK handles for you including:

  • obtaining push tokens across Android, iOS, Huawei, and Web Browsers
  • verifying subscription status, prompting, and opting-in users
  • displaying the notification and handling the payload

For example, the APNS push payload has a standardized format but FCM does not. Setting up both would need additional dev work to handle notifications client side. OneSignal's Push Payload contains a "custom" key with a nested "i" value when sent through our system. Our SDK checks this value to handle the push notification. See OneSignal's Custom Push Payload here and our article on Build vs Buy for more details.

Setup Communication Channels

As you're integrating OneSignal into your application, you'll want to establish communication channels with your users. Each channel works differently:

Migrating Current Users to OneSignal

Optional

Once the OneSignal SDK is integrated, your users will automatically become available in your OneSignal dashboard when they update and open your mobile app or return to your website (certain web requirements apply). Previously subscribed devices will stay subscribed and can be sent messages. Also, subscribed iOS and web users will not be shown the subscription prompt again.

The OneSignal SDK collects certain user data automatically. For custom user data/attributes/properties these can be stored as Data Tags which are Key: Value pairs of string or number data. Data should be stored as arrays or objects in OneSignal.

Importing Emails & Phone Numbers

Recommended
You can import your current emails and phone numbers through the OneSignal Dashboard using a csv file or the API. More details see:

🚧

Data Required for Push Notifications

You cannot directly import push subscribers without a push token identifier. The 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

Due to the way Browsers have set up Web Push, you cannot directly import subscriber data from a different push provider into OneSignal. However, if your site meets the below requirements, current subscribers will be automatically moved 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.

Requirements:

  1. Remove the previous Web Push SDK from your site. Only use the OneSignal Web Push SDK. See Web Quickstart.
  2. You must have an HTTPS website and use the same origin in which your users are currently subscribed.
  3. You must be able to upload Service Worker files to your server. See OneSignal Service Worker for details on migration.

If your site does not meet these requirements or you are changing your site origin (like removing/adding www), users will need to resubscribe to the site. You can continue to send push from the old provider until you are ready to fully move to OneSignal.

Importing Mobile App Subscribers

Before migrating, we recommend releasing your app with the OneSignal SDK. Any user that updates and opens the app with the OneSignal SDK active will automatically be added to OneSignal and will keep their current subscription status.

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

iOS subscribers can be imported using our API and start getting push immediately. However, features like monitoring notification click rate won't work for devices without the OneSignal SDK active.

Android subscribers can be imported using our API. 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 automatically after they updated and opened your app anyway.

Send OneSignal Event Data & User Attributes

Optional

Custom User data can be stored in OneSignal as Data Tags which are key : value pairs of string or number data.

Tags can be used for Segmentation and Message Personalization.

Integrations

Optional

If you have other databases or business products that you'd like to integrate with OneSignal account, please follow the setup guides listed in our Integrations Page.

Outcomes

Optional

Outcomes are OneSignal's advanced analytics that lets you track actions users take after clicking or receiving messages.

For instance, tracking "clicks" is nice, but setting Outcomes can show you how much revenue was brought in from a push. Also track user behavior after entering the app/site, like did they read/share/update/interact with a post or another user. Other tracking includes click stats like country or language or app version.

Adding Teammates

Optional
If you have other team members that need access to your OneSignal account, see our Account Management page.

Build Journeys & Send Messages!

Now, you have likely subscribed users and are ready to start sending messages!

👍

Congrats 🎉

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

Updated over 1 year ago