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

Whether you are moving millions of users or just getting started, this checklist walks through getting setup as fast as possible.

Step 1. Setup OneSignal

SDK Implementation is recommended. Our SDKs are open source and easy to setup. On average, customers get setup and send their first push in under 30 minutes.

• Web Push Quickstart
• Mobile Push Quickstart

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

👍

Next Steps After Adding The SDK

If migrating subscribers to OneSignal from another provider, continue to Step 2 Migrating Users to OneSignal.

If you are integrated with a database or 3rd party data platform see Step 3 Connect User Data to OneSignal.

To collect custom user data in OneSignal, see Step 4 Send OneSignal Event Data & User Attributes.

To just start sending messages: Step 6 Sending Messages.

API Only Integrations (Not Recommended)

API-only integrations are generally not recommended. Each platform (Android, iOS, Web) has different push notification requirements. For example, iOS has a standardized APNS push payload but Android has a non-standard push payload and Web Push requires Service Workers; both of which would need additional dev work to handle notifications client side.

See OneSignal's Custom Push Payload for more details.

---

Step 2. Migrating Users to OneSignal

Once the OneSignal SDK is integrated, your users will automatically show in your OneSignal Audience page upon users updating and opening the App or returning to the Website.

Previously 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

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 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. You must have an HTTPS website.
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 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 update and open the app with the OneSignal SDK active will automatically be added to OneSignal and will keep their current subscription status.

iOS subscribers can be imported and start getting push immediately. However, features like monitoring notification click rate wont work for devices without the OneSignal SDK active.

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 automatically after they updated and opened your app anyway.

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

---

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 number 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 the Database, DMP, & CRM Integration 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

Recommended Step

OneSignal stores user data as a device record with a unique Player ID (OneSignal User ID) when the device:

• Web Push: Subscribes to Push Notifications
• Mobile Apps: Opens the Mobile App with OneSignal SDK
• Email shared with OneSignal. See Import Email Addresses.
• SMS shared with OneSignal. See Import Phone Numbers.

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 External User Ids 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.

---

Step 4. Send OneSignal Event Data & User Attributes

Recommended Step

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.

Helpful setup guides:

• Data Tags Overview - Overview of how data tags work.
• Message Personalization and Time Operators - Add user details to a message or track events based on time.
• Example code and common use case setup in Use Cases & Best Practices.

---

Step 5. Outcomes

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.

---

Step 6. Sending Messages

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

• Sending Push Messages for all the details on sending push. Send test messages by Finding your Devices & Set Test Users.
• Automated Messages which is how to setup drip campaigns to send messages automatically to users.
• Sending Email Messages - Make sure you are setup with our Email Overview first.
• In-App Messaging Overview to get the full spectrum of In-App Message Capabilities for Mobile Apps.
• Sending SMS - Learn about how to setup SMS first.

👍

Congrats 🎉

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