Managing your push subscriber base

In Pushwoosh, each subscriber is identified by a push token, a unique identifier that enables message delivery to a specific device. This post covers how push tokens work, their impact on billing, and how to keep only valid tokens in your subscriber base.

A push token is a unique, anonymous identifier assigned to a specific app instance on a device by its push service provider:

• Apple Push Notification Service (APNs) for iOS devices
• Firebase Cloud Messaging (FCM) for Android devices

This token ensures that push notifications are delivered to the correct app on the user’s device.

In Pushwoosh, the push token lifecycle includes these key stages:

1. When the app is launched for the first time, it prompts the device’s operating system (OS) for permission to receive push notifications.

2. The application’s push service (e.g., APNs for iOS, FCM for Android) generates a unique push token for that app instance. By default, the Pushwoosh SDK collects and stores this token even if the user has not granted notification display permissions. Push messages won’t be shown to these users, but the token can still be used to send messages to their application inbox, another messaging channel in Pushwoosh.

   However, you can configure the SDK to collect tokens only from users who have granted permission.

3. The app uses the Pushwoosh SDK to send this token to Pushwoosh database along with device data (including a hardware ID or HWID) to Pushwoosh via the /registerDevice API endpoint.

4. Pushwoosh securely stores the token for future messaging.

5. When a notification is triggered, Pushwoosh uses the stored token to route the message through the appropriate delivery gateway.

6. The chosen gateway delivers the message to the device, and the OS displays it based on system and app notification settings.

7. If the push token becomes invalid (e.g., due to app uninstallation), Pushwoosh detects the delivery failure after another notification sendout, when the gateway returns the list of sendout errors, including expired/invalid/etc. tokens. Then Pushwoosh marks the token as inactive, and deletes it from the database and billing. If the app is re-installed on the same device, a new token will be issued.

While Apple Push Notification Service (APNs) and Firebase Cloud Messaging (FCM) do not provide full transparency into token lifecycle policies or allow proactive token validation, there are known scenarios in which push tokens can become invalid or expire.

Pushwoosh’s billing model is based on the number of valid push tokens (active push subscribers) stored in your project’s database, not the number of notifications sent.

To keep your push subscriber list clean and avoid paying for inactive users, regularly check delivery stats, remove invalid tokens, and ensure your app and backend always have the latest token data.

Pushwoosh offers several ways to help you do this:

Send push messages to your entire subscriber base regularly. This helps Pushwoosh identify invalid tokens. When a message fails to deliver, typically due to an invalid token, the push gateway returns an error. The SDK captures this response and removes the invalid token automatically, ensuring it is excluded from future sends and billing.

Important: Token validity is only checked when a push is sent. Pushwoosh does not perform background checks on token validity.

You can use the /bulkUnregisterDevice Device API method to remove push tokens from your subscriber base, for example, when users opt out or are no longer active.

To do it:

1. Build a segment of users matching your criteria (e.g., opted‑out, free-tier users, or those inactive for X days).
2. Export the segment using the Control Panel or the exportSegment API method.
3. Call /bulkUnregisterDevice to delete the push tokens for the devices in that segment.

The automatic inactivity cleanup algorithm in Pushwoosh helps keep your subscriber list clean by removing push tokens from users who haven’t been active for 90 days.
It works by tracking when users last opened your app using the default Last Application Open tag. If a user hasn’t opened the app for 90 days or more, their push token is marked as inactive and removed from your subscriber base. This ensures you’re only paying for active, engaged users.

Uninstall Tracking keeps your push subscriber list accurate by detecting when users uninstall your app. This allows Pushwoosh to automatically remove invalid tokens, so you’re not charged for users who are no longer reachable.

Note: Uninstall Tracking is supported only on iOS and Android.

Here’s how it works:

1. Pushwoosh sends a silent push notification once per day to all subscribed devices. These silent notifications are invisible to users, with no alerts, sounds, or badges.
2. Each device has a unique push token provided by a notification gateway. If the app has been uninstalled, the token becomes invalid. When the silent push fails, the gateway returns an error.
3. Pushwoosh detects the error, removes the invalid token from your subscriber list, and stops billing for it.

Notification gateways do not guarantee delivery of silent pushes. These messages may be deprioritized or dropped by the gateway, which can delay or limit the accuracy of uninstall detection. Learn more

To monitor uninstall activity, navigate to the Statistics > Dashboards > Application dashboard in your Pushwoosh Control Panel. The App Uninstalls graph provides a timeline view of uninstall trends for your application.

Deleting a push token using any supported method is easily reversible.

When a user re‑opens your app:

1. The Pushwoosh SDK automatically requests a new push token.
2. It then re‑registers the device (via registerDevice).
3. The user becomes an active subscriber again and will receive push notifications going forward.