OneSignal automatically creates a device/channel record with unique OneSignal User ID aka
- a user opens your mobile app for the first time
- a user subscribes to your website with the OneSignal SDK initialized
- an email address is provided. See Import Email Addresses
- a phone number is provided. See SMS Overview
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 the Database, DMP, & CRM Integration guide for more details.
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.
If you have an analytics tool, see our Analytics Integration Guides for more details on setting this up.
Web Push Subscribers and iOS Mobile App Subscribers must opt-in to subscribe. See our Prompting Guide for more details on getting permission.
Android Mobile App Subscribers are opted-in when they open the app for the first time.
Email records subscribe when added to OneSignal. See Import Email Addresses.
SMS Phone records subscribe when added to OneSignal. See Import Phone Numbers.
Push records get unsubscribed when they:
- Uninstall the mobile App
- Clear Browser Data
- Go into Device or Browser settings and unsubscribe (see Unsubscribe from Notifications Guide)
- You unsubscribe them through the SDK method to disable push or API Edit device call, setting
Any subscribed device that unsubscribes will be detected and marked in OneSignal automatically when they:
After you send 2 notifications to the unsubscribed device on Android Mobile Apps and Web. For iOS, this may take a week for Apple to update the subscription record. More details below.
If you target devices directly via the API using
include_external_user_ids parameters we also provide the unsubscribed devices as
"invalid_external_user_ids" callback results which you can process in your Internal Database, DMP, & CRM.
Email records get unsubscribed when users click unsubscribe url.
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".
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.
iOS Unsubscribe Detection
Apple changed the way it reports unsubscribe events on iOS apps.
In the past, they would report the unsubscribed device upon the 2nd notification. They stopped doing this for privacy reasons. Apple intentionally does not want token invalidation to be used as a method to detect app uninstall.
Some details provided by Apple can be found here: https://forums.developer.apple.com/thread/116445
Currently if a device unsubscribes and opens the app, we detect this right away 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 device unsubscribe event.
If you need to remove older devices, you can delete them using our dashboard or API.
If a device was unsubscribed, how do they 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.
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. Or if you call the
setEmail method again for their record through the SDK.
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.
If you called the SDK
logoutSMS method, you can resubscribe the SMS using the
setSMSPhoneNumber method with the same phone number.
The OneSignal Player ID is a UUID (Unique Universal Identifier) that OneSignal creates per device per OneSignal App ID.
The format is lowercase letters and numbers 8 characters-4 characters-4 characters-4 characters-12 characters like
A common practice is to tie the OneSignal Player ID with your User ID (we call External User Id). See our Internal Database, DMP, & CRM Integration Guide for more on this setup.
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:
- Deleting Users
- 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.
Please see Finding Users
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 Firebase User ID, CRM User ID, or even email if you choose.
- OneSignal creates the
player_idfor every device record
- You send OneSignal the
external_user_idbased 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
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.
More details in our Internal Database, DMP, & CRM.
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.
Once they log out of the app, you can remove the
removeExternalUserId method. If using Identity Verification then
removeExternalUserId does not work. Instead you can call
setExternalUserId with an empty string for the External User Id and use the same User Auth Hash for the original external user id you are trying to remove.
This means if User A logs in and you call
setExternalUserId("user_a") then any messages sent directly to
include_external_user_ids will not be shown on the device until User A logs out,
removeExternalUserId is called and User B logs in.
Use a custom User Id and set it with the
setExternalUserId method whenever the user logs into the 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.
Updated over 1 year ago