---

Subscription Records

A subscription refers to the ways a user can receive messages sent from OneSignal like push notifications, SMS, and email. These messaging channels are each assigned a Subscription ID to uniquely identify that specific channel. In-app messages do not have a Subscription ID.

Subscription Properties

Users can have multiple subscriptions, but each subscription will have the following properties.

Subscription Status Tracking

When someone subscribes or unsubscribes from messages, OneSignal automatically detects this and updates the status. You can get the current subscription status with the:

1. Dashboard Audience > Subscriptions page.
2. View user or Export Subscriptions CSV APIs.
3. SDK methods for:
   1. getting the subscription status (mobile SDK & web SDK)
   2. observing subscription changes (mobile SDK & web SDK )

If a user uninstalls the app or unsubscribes and does not open the app again, OneSignal receives the unsubscribe event from the server and updates the subscription status.

---

Mobile App Push Subscription Lifecycle

When the OneSignal SDK is initialized in your mobile app, it creates a Subscription ID for that device. The user must opt-in (aka subscribe) to receive push notifications for your app. See How to Prompt for Push Permissions with In-App Messages.

The Mobile Push Subscription ID will never change. However, a new Subscription ID will be assigned to the that same user's device when:

1. Uninstalling and re-installing the mobile app on the same device. In this case, the original Subscription ID will eventually be marked as unsubscribed. See below Push Notification Subscription Tracking for details.
2. Deleting the original Subscription ID and opening the app again on the same device.

There are 3 options for users to opt-out (aka unsubscribe) from receiving push notifications:

1. Uninstall the app.
2. Go into the device's notification settings and unsubscribe from the app.
3. The OneSignal SDK and API provides methods to disable push at the OneSignal level. In this case, the push token is still subscribed and your app's notification settings are still subscribed, but the user is marked as unsubscribed in OneSignal and cannot be sent push from OneSignal until re-enabled. See the SDK method to opt-out of push or Update subscription API.

Web Push Subscription Lifecycle

The Web Push Subscription ID is created for a browser profile when the user opts-in (aka subscribes) to push notifications on your website. See our Web Prompting Guide for more details on getting permission.

The Web Push Subscription ID will never change. However, a new Subscription ID will be assigned to that same user's browser profile when:

1. Clearing browser data or cookies, then returning to the website. In this case, the original Subscription ID will eventually be marked as unsubscribed. See below Push Notification Subscription Tracking for details.
2. Deleting the original Subscription ID, then clearing browser data and returning to the site.

There are 2 options for users to opt-out (aka unsubscribe) from receiving push notifications:

1. Go into the browser's notification settings and unsubscribe from the website.
2. The OneSignal SDK and API provides prompts and methods to disable push at the OneSignal level. In this case, the push token is still subscribed and your website's notification settings are still subscribed, but the user is marked as unsubscribed in OneSignal and cannot be sent push from OneSignal until re-enabled.
   See the SDK method to opt-out of push or Update subscription API.

See below Push Notification Subscription Tracking for details on how OneSignal automatically tracks subscription change events.

Push Notification Subscription Tracking

The subscription status will be updated in OneSignal automatically when the user:

1. Interacts with the OneSignal SDK. You can capture this event with our Subscription Observer methods and send to your Database.

2. After sending 2+ notifications to the unsubscribed device.

   1. Devices using FCM (Android Mobile Apps and Web) will alert OneSignal that the device is unsubscribed immediately after the 2nd notification is sent to the unsubscribed device.
   2. Devices using APNS (iOS devices like iPhone/iPad) will alert OneSignal that the device is unsubscribed after some time has passed between the first notification to the unsubscribed device and the 2nd notification sent.

Example sending 2+ notifications to detect unsubscribed devices:

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

📘

No Network Connection

If the device is no longer connected to the internet (eg it is turned off, destroyed, or reset) then it cannot report back to Google/Apple that it can no longer receive notifications.

In this case, you will want to delete older subscriptions.

🚧

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.

---

Email Subscription Lifecycle

Each email address will have its own unique Email Subscription ID. There can only be a single instance of the email address within a OneSignal app.

The Email Subscription ID can only be associated with one user at a time. For example, if "user_A" is assigned "email_1" and then "user_B" is assigned "email_1", the Subscription ID for "email_1" is removed from "user_A" and assigned to "user_B".

An Email Subscription ID will be opted-in aka subscribed when:

• created. See Import Email Addresses for details.
• you set enabled to true in the Update subscription API.
• you select "Resubscribe to email" in the OneSignal dashboard.

An Email Subscription ID will be opted-out aka unsubscribed when:

• the user opts-out through Unsubscribe Links.
• you set enabled to false in the Update subscription API.
• you select "Unsubscribe from email" in the OneSignal dashboard.

---

SMS Subscription Lifecycle

Each phone number will have its own unique SMS Subscription ID. There can only be a single instance of the phone number within a OneSignal app.

The SMS Subscription ID can only be associated with one user at a time. For example, if "user_A" is assigned "phone_number_1" and then "user_B" is assigned "phone_number_1", the Subscription ID for "phone_number_1" is removed from "user_A" and assigned to "user_B".

A SMS Subscription ID will be opted-in aka subscribed when:

• created. See Import Phone Numbers for details.
• you set enabled to true in the Update subscription API and the phone number is not on the Twilio's Block List. See below Twilio Block List for details.

A SMS Subscription ID will be opted-out aka unsubscribed when:

• you set enabled to false on the Update subscription API.
• the user replies "STOP" or your opt-out keyword to the sending number. See below Twilio Block List for details.

Twilio Block List

Twilio provides certain default keywords like "STOP" and custom key words which a user can reply back to a message in order to opt-out of further communications. See Twilio Support for opt-out keywords (SMS STOP filtering) for details.

When a user opts-out of SMS messages, they get added to Twilio's Block List.

Once on Twilio's Block List, the only way to opt-in again is to text back the same number "START" or you can set your own opt-out keywords in Twilio.

It is a good practice to include this opt-out/opt-in sentences in your SMS such as: "Reply STOP to unsubscribed and START to resubscribe" or "Reply STOP to stop future messages, you can always opt-in by texting START".

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 Update subscription API with enabled set to true.

---

FAQ

How is usage duration calculated?

Usage Duration is the number of seconds the user has interacted with the app on the device (subscription), as recorded whenever the app is in the foreground. However, this only gets sent to OneSignal once the user has been in that session for over a minute.

If the user has the app open for a minute, we track all 60 seconds. If they have the app open for 59 seconds or less and then quit the app, that data is not sent to the OneSignal servers.

If the user has the app open for under 60 seconds, then puts the app in the background and opens it again, it will still be count towards the current usage duration and once the 60 seconds gets triggered, it will send to OneSignal.