Onboarding With OneSignal

Migration steps, importing users, and getting started quickly.

Whether you are migrating to OneSignal or just getting started, we're happy to have you! This checklist walks through getting set up as fast as possible. If you haven't done so already, head to onesignal.com to set up your account.

📘

Add your Team!

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


Integrate OneSignal SDKs

Our SDKs are open source and easy to setup. On average, customers get setup and send their first message in under 30 minutes. Please contact [email protected] if you require any assistance.

Frontend 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:

Backend Server-side SDKs

Optional

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

Note on Server API Integrations for Push Notifications

OneSignal provides the Create user, Create subscription, Update user, and Update subscription APIs for creating and updating user and 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.


Identify Users

Recommended; Required for Integrations

OneSignal stores user data under a unique OneSignal ID and the channels a user is subscribed to under a Subscription ID. You can identify your user within OneSignal by setting an External ID or custom aliases.


Setup Email and SMS Channels

Recommended

After integrating OneSignal's Mobile and/or Web SDKs into your application, you will want to start collecting email addresses and phone numbers to send emails and SMS/MMS text messages. Follow these guides to setup the channels and your application to collect new emails and phone numbers. You can import your current users in the next step.


Data Tags: User Events & Attributes

Optional

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

Tags will be managed at a user level and can be accessed across all subscriptions associated with a OneSignal ID. Tags can be used for Segmentation and Message Personalization.


Migrate 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, they will not be asked to opt-in to messages again, and can be sent messages.

The OneSignal SDK collects certain user data automatically. For custom user data/attributes/properties these can be stored as Data Tags (more details on this later).

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

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

Import Mobile App Subscribers

Optional

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 Create user API.

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

Android, Amazon, Huawei 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.


Integrations

Optional

OneSignal can integrate with any platform.


Outcomes

Optional

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.


Manage your OneSignal Account

Recommended

If you have other team members that need access to your OneSignal account or want to update billing, apps or org data.


Build Journeys & Send Messages!

Recommended

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!