OneSignal automatically creates a device-channel record with unique OneSignal User ID aka player_id when:

• a user opens your mobile app with the OneSignal SDK initialized for the first time.
• a user subscribes to your website with the OneSignal SDK initialized.
• an email address is provided to OneSignal.
• a phone number is provided OneSignal.

For example, if a user subscribes to your website and provides you their email, then downloads and opens your mobile app, they will have 3 player_id records within OneSignal: a web push record, an email record, and a mobile push record.

It is recommended to combine your OneSignal User Record player_ids through your own custom User ID called external_user_id. See our guide on External User IDs for more details.

---

Subscription Process

OneSignal automatically tracks subscription and certain device data through the SDK. See: Data Collected by the OneSignal SDK. You can view this data through the Dashboard and even Export User Data through the dashboard or API.

Push Notification and In-App Message Channel Opt-in

Web Push Subscribers must opt-in to push notifications. See our Web Prompting Guide for more details on getting permission.

iOS Mobile App Subscribers must opt-in to push notifications, but starting in iOS 12, can receive Provisional Push Notifications.

Android Mobile App Subscribers are opted-in when they open the app for the first time.

Email Opt-in

Email records subscribe when added to OneSignal. See Import Email Addresses.

SMS Opt-in

SMS Phone records subscribe when added to OneSignal. See Import Phone Numbers.

---

Detecting Unsubscribes

The OneSignal SDK and API provides methods to unsubscribe devices at the OneSignal level. See the SDK method to disable push or API Edit device call, setting notification_types to -2.

Push Notifications Opt-out

Web Push records get unsubscribed when they:

• Clear Browser Data.
• Go into the Browser settings and unsubscribe (see Unsubscribe from Notifications Guide).

Mobile Push records get unsubscribed when they:

• Uninstall the app.
• Go into the device's Notification Settings and unsubscribe from the app.

Any subscribed device that unsubscribes will be detected and marked in OneSignal automatically when they:

1. Interact with the OneSignal SDK (increasing Revoked Count). You can capture this event with our Subscription Observer methods and send to your Database.

2. After you send 2 notifications to the unsubscribed device. Devices using FCM (Android Mobile Apps and Web) will alert us that the device is unsubscribed immediately after the 2nd notification is sent to the unsubscribed device.

Devices using APNS (iOS devices like iPhone/iPad) will alert us that the device is unsubscribed after some time has passed between the first notification to the unsubscribed device and the 2nd notification sent.

For example:

• Notification 1 sent and user receives on device, then user unsubscribes.
• Notification 2 sent, the OneSignal Dashboard shows "Delivered" but the user does not actually receive it.
• Notification 3 sent, the OneSignal Dashboard shows Failed (Unsubscribed). On iOS, it may take additional notifications and time for the unsubscribed event to be sent to OneSignal from Apple.
• Notification 4 will not be sent to that device.

🚧

iOS Unsubscribe Detection

To protect user privacy, Apple doesn't want developers to know when a user removes the app. Some details provided by Apple can be found here: https://developer.apple.com/forums/thread/670868

If a device unsubscribes and opens the app, OneSignal detects this unsubscribe event right away and updates the record through our SDK. However if the device uninstalls the app or unsubscribes and does not open the app, it may take several weeks for Apple to report the unsubscribe event.

Apple will wait a random amount of time, typically over 14 days, before reporting a device is unsubscribed. The unsubscribed detection requires at least two notifications to be sent to the app, after the app is uninstalled.

Apple also has an edge case where development apps must have at least one currently installed in order to determine that another one is uninstalled and can't get notifications (in addition to the random multi-day delay involved). Details here: https://developer.apple.com/library/archive/technotes/tn2265/_index.html#//apple_ref/doc/uid/DTS40010376-CH1-TNTAG34

If you need to remove older devices, you can delete them using our dashboard or API or send Background Notifications to all users once a week. Once Apple responds that the token is invalid, we will unsubscribe it automatically.

If you target devices directly via the API using include_player_ids or include_external_user_ids parameters we also provide the unsubscribed devices as "invalid_player_ids" or "invalid_external_user_ids" callback results which you can process in your Internal Database, DMP, & CRM.

Email Opt-out

Email records get unsubscribed when users click unsubscribe url.

SMS Opt-out

SMS records get unsubscribed when users reply "STOP" or your opt-out keyword to the sending number. Twilio then marks the device as unsubscribed. Upon the next SMS sent to the device, Twilio responds with an Error Code 21610 at which point we mark the device unsubscribed in our system.

It is a good practice to include an opt-out sentence in your SMS such as: "Reply STOP to unsubscribed" or "Reply STOP to stop future messages".

Revoked Count

This tracks how many previously subscribed devices returned to your app after opting-out of push permissions and how many web push users opted-out of push using the SDK.

---

Resubscribing Users

If a device was unsubscribed, how do they resubscribe?

Push Notifications Resubscribe

Web Push Device Records will get prompted again if they unsubscribe through the browser settings and will be resubscribed when the following occurs:

• automatically if they clear browser cookies/history and return to the site with OneSignal code.
• re-enable push using the OneSignal Bell Prompt or Custom Link prompt

Mobile App Push Device Records will get automatically resubscribed when they open after they enabled push in the App Settings.

Email Resubscribe

If a user unsubscribes from email, they will get resubscribed if you manually click "Resubscribe to email" in the All Users tab for their record. If you use the setEmail SDK method or API Add/Edit Device calls, you will also need to remove that email from your ESP Suppression list.

SMS Resubscribe

If the device texted back "STOP" to the sending number, then they will not get SMS again until they text back "START" to the same number. You can set your own opt-out keywords in Twilio.

Once they opt-back-in, you can detect this with Twilio's Webhook for Incoming Messages and mark the device as subscribed in OneSignal using the Edit Device API with notification_types set to 1.

If you called the SDK logoutSMS method, you can resubscribe the SMS using the setSMSPhoneNumber method with the same phone number.

---

Player Id

The OneSignal Player Id is a UUID (Unique Universal Identifier) that OneSignal creates per subscription per app. A user can have multiple subscriptions: push notifications, email, and sms.

The format is lowercase letters and numbers 8 characters-4 characters-4 characters-4 characters-12 characters like b3aaabc2-9a47-4647-adda-3e4583a2d19e.

A common practice is to tie the OneSignal Player Id with your User Id (we call External User Id). See our guide on External User IDs for more details.

When does the OneSignal Player ID change?

Web Push - When the user clears their cookie data for your site.

Mobile Apps - If using version 3.4.1+ of our iOS SDK or 4.3.1+ of our Android SDK, the Player ID will always change when:

1. Deleting Users
2. Uninstalling and Re-installing the Mobile App or Installing the Mobile App on a new device

Earlier Versions of our Mobile SDKs, OneSignal makes a best effort to keep the same Player ID on all devices that are assigned. Some circumstances that may cause it to change:

• Android: If the user has opted out of the Google Advertising ID, uninstalls the app and re-installs.
• iOS: If the user does not have any other apps installed that have your IFV (identifierForVendor), then uninstalling your app and re-installing it, will give them a new Player ID.

Finding Player IDs

Please see Finding Users

---

External User IDs

The external_user_id is an identifier you set which helps map your unique database User ID's to the OneSignal player_id device record. This could be any unique identifier like a database user ID, CRM user ID, or even an email or phone number if you choose.

To clarify:

• OneSignal creates the player_id for every device record
• You send OneSignal the external_user_id based on how you identify users.

Multiple device records in OneSignal can have the same external_user_id but will each have a unique player_id. For example, a user subscribed to your website, android mobile app and iOS mobile app will have 3 different player_id records, but you can map these devices to your database via the same external_user_id.

Our SDKs support a setExternalUserId method which you can call as soon as the user logs into your website and/or mobile apps to set their User Id.

Also, see our Internal Database, DMP, & CRM for more details.

---

User Profile Page

You can access a user profile page for your subscribers by selecting Options > View User Profile from the All Users page.

The User Profile page contains information about your subscriber including:

• Device and subscription type (push, email, SMS)
• External User ID
• Location
• Last and first seen
• Session count
• Usage duration
• Data tags
• Segments the user belongs to

The Activity Timeline will show recent message activity for Push, Email, SMS and In-App including if a message was sent or opened. The Activity Timeline shows activity for the past 3 days and is currently available on our Professional and Enterprise plans. See pricing.

You can add and edit tags from the User Profile page. This makes it convenient to test personalization, create internal test groups or update message-critical user information without developer resources. For instance, you could use this to create a Segment to test out a new Journey before launching it externally.

---

FAQ

Managing Multiple Users On One Device

To manage multiple users that share a device, you will need to detect when User A is on the device and only send them their notifications when they are on the device, otherwise User B will get them.

The best way to handle this is with your own External User IDs.

Call the setExternalUserId method when each user signs in to the app, then you can target them by the external_user_id using the API include_external_user_ids parameter.

Once they log out of the app, you can remove the external_user_id with the removeExternalUserId method. If you want to remove data tags, use the deleteTags methods.

This means if User A logs in and you call setExternalUserId("user_a") then any messages sent directly to user_b with include_external_user_ids will not be shown on the device until User A logs out, removeExternalUserId is called and User B logs in.

Upon removing external_user_id's the data tags associated with the device will persist. They can be deleted with the deleteTags method.

If you want to prevent push being sent to the device while logged out, use the disablePush method. Set it to true upon logout and false upon login.

📘

Email and/or SMS Subscribers

IMPORTANT: If using email and/or sms, you should also call logoutEmail and logoutSMSNumber methods upon the user logging out and setEmail and setSMSNumber upon login.

Managing One User On Multiple Devices

Use a custom User Id and set it with the setExternalUserId method whenever the user logs into the app.

Can I track users that have uninstalled my app?

Yes and no. Mobile operating system providers make it intentionally difficult to reliably detect when a user has uninstalled an app.

OneSignal does not differentiate an Uninstall vs Unsubscribe And Never Opening the App Again.

OneSignal detects the last time a device opened the app with the "Last Session" parameter. You can Export User Data to check the Subscription Status and Last Active time.

Why do I see a higher number of users when I import records?

When you import a list of "users" a single user can have several devices, email addresses and/or phone numbers. OneSignal sends messages to device-channels, not users. This is why you see a higher number of "users" in OneSignal, because they are actually the number of "devices/channels" attached to the user.

For example:

• If a user has an Android device and iOS device, that is 2 devices per 1 user.
• If a user has 1 android device, 2 iOS devices, 1 email and 1 phone number that user has 5 device records.
• If a user uninstalls the app and re-installs it on the same device, that is 2 devices in OneSignal.

Why do I see a lower number of users when I import records?

The reasons you see lower numbers in a OneSignal segment after an import are:

1. If a user's device is unsubscribed, it will not be included in the segment and therefore will not be targeted. Segments only contain subscribed devices.

• If a user has a single device and that device is unsubscribed, it will not be included in the segment for a notification.
• If a user has multiple devices and all of which are unsubscribed, they will not be included in the segment.

2. If the user's device has either (1) uninstalled the app OR (2) unsubscribed and has not opened the app, then Google and Apple will "tell us" they are unsubscribed after sending 2+ notifications to the device. At which point we mark them as "Failed (Unsubscribed)" in the message report.