An app upgrade can change more than the user interface. It may alter the push token, application identifier, notification permission state, storage format, SDK configuration or relationship between a device and a user. If your notification system assumes those details remain unchanged, delivery can degrade just as a new version reaches more customers.
Maintaining delivery requires treating an upgrade as a notification migration, not only a client release. The aim is to keep valid registrations usable, refresh registrations when they change, preserve user identity and prevent retries from creating confusing duplicates. This guide sets out a practical approach for mobile and web applications using HoneyNotify or a comparable push provider.
Map what can change
Before releasing an upgrade, document every value involved in delivery and identify which system owns it. At minimum, review:
- The application or bundle identifier for each platform and environment
- The push provider credentials and project configuration
- The device or browser token
- The provider-side device identifier
- The user identity associated with that device
- Tags, segments and subscription preferences
- Notification permission status
- The payload fields and client handling logic
- The SDK version and its registration lifecycle
This inventory separates stable concepts from replaceable ones. A user identity may remain stable across an upgrade, while a device token can change. A provider device ID may also remain useful, but only if it continues to represent the current token and environment correctly.
Do not assume that reinstalling, upgrading or restoring an app produces the same registration state. Treat registration as an ongoing synchronisation process rather than a one-time setup action.
Refresh registration deliberately
The client should initialise the notification SDK on every supported app launch or equivalent lifecycle point, then reconcile its current state with the provider. The exact SDK calls depend on the platform and integration, but the responsibilities are consistent: register the device, handle token changes, associate identity and process lifecycle events.
A robust registration flow should:
- Detect when the operating system or browser supplies a new push token
- Send the current token and relevant environment to your server or notification service
- Associate the device with the signed-in user when identity is available
- Reapply required tags or preferences after registration
- Record permission and registration state separately
- Tolerate registration being unavailable until the user grants permission or the platform is ready
Avoid storing a token only in local app storage and assuming it is still valid after an upgrade. Local storage can be cleared, restored incorrectly or become inconsistent with the provider. The client should be able to re-register safely without creating an uncontrolled collection of duplicate device records.
When using HoneyNotify, its client SDKs cover device registration, identity, token lifecycle, payload handling and lifecycle events across iOS, Android and Web Push. Use those lifecycle capabilities as part of normal application startup and token-change handling, rather than adding a one-off migration path that will be forgotten after the release.
Preserve identity separately from the token
Users care about receiving notifications on their account, not about a particular token. Keep those concepts separate in your data model. A user can have multiple devices, and one device can move from one signed-in user to another. Your system should therefore support explicit association and disassociation rather than treating a token as a permanent user identifier.
During an upgrade, re-establish identity after registration and after login. Also decide what should happen when a user logs out. For example, you may remove the user association while retaining an anonymous device registration, or you may stop sending to that device until another user signs in. The correct policy depends on your product and privacy requirements, but it should be deliberate and testable.
If you import OneSignal subscription IDs into HoneyNotify, those IDs can remain as device IDs when matching provider tokens later register. That matching can fail when the token rotates or when the app registers under another provider environment. Plan for that case: allow a new registration to be created or reconciled, and do not make the imported identifier your only recovery mechanism.
Protect the server-side send path
Client migration cannot compensate for an unreliable send path. Server-side sends to HoneyNotify use POST /v1/notifications with a Bearer API key and an Idempotency-Key. A notification requires a title, body and target. Targets can address a device, user, tag, segment or all enabled devices.
Keep the API key on the server. During an upgrade, verify that the new client and server agree on target identifiers, environment and payload structure. A release that changes an identity format or tag name without updating the sending service can appear to have a delivery failure when the real problem is targeting.
Use an idempotency key that represents the logical notification operation, not every network attempt. If a timeout occurs and your worker retries the same operation, the retry should use the same key according to your integration design. Generate a new key for a genuinely new notification. This distinction helps avoid duplicate sends while still allowing safe recovery from transient failures.
Queue notifications during a rollout when immediate delivery is not essential. A queue gives you a place to retry failed registration-dependent work and to delay non-urgent sends while configuration changes are being verified. For urgent messages, define the retry and fallback behaviour explicitly rather than relying on an unbounded loop.
Roll out in stages
A staged release reduces the chance that a registration defect affects every installation at once. Start with internal builds and test accounts, then expand to a controlled group before wider distribution. At each stage, compare registration and delivery behaviour between the old and new versions.
Useful checks include:
- New installations register successfully
- Existing installations refresh their tokens after upgrading
- Signed-in users retain the intended identity association
- Logged-out devices do not receive another user’s notifications
- Tags and segments still describe the right audience
- Tapping a notification opens the expected destination
- Foreground and background payload handling remains correct
- Permission-denied users are not repeatedly prompted or treated as deliverable
- Rollback or downgrade behaviour is understood
Keep the old client compatible with the server for the duration of the rollout. If the new app expects a new payload field, make the client tolerant of its absence before you begin sending it. Likewise, do not remove an old target or registration path until the upgrade population has moved far enough that it is safe to do so.
Handle platform and environment boundaries
An upgrade may involve separate development, staging and production applications. Tokens and credentials are often environment-specific, so never assume a token registered in one environment can be used in another. Make the environment an explicit part of registration data and server routing.
Review platform changes as well. Permission flows, notification settings, background execution and token refresh behaviour can vary between iOS, Android and Web Push. Test clean installs, upgrades over several previous versions, restored devices, denied permissions, re-enabled permissions and token rotation. For web applications, include browser permission changes and service worker updates in the test plan.
If the application identifier, signing configuration, push project or web origin changes, treat that as a migration with its own acceptance criteria. A visually identical app can still be a different push application to the operating system or provider.
Observe registration, not just delivery
A delivery dashboard alone may not explain an upgrade-related incident. Record enough operational data to distinguish these stages:
- The app started its registration flow
- Permission was available or denied
- A token was received or changed
- The token was associated with a device and environment
- Identity was attached or removed
- A server-side notification was accepted for its target
- The client received and handled the payload
- The user opened the notification, where that event is available
Use privacy-conscious identifiers and avoid putting raw tokens into ordinary logs. Track version, platform, environment and registration outcome so that a sudden change can be correlated with a release. Alert on meaningful changes in registration failures, invalid-token handling or send errors, but establish a baseline from your own system rather than relying on an assumed industry benchmark.
A useful support workflow should also let you answer whether a user has a current registration, which app version last refreshed it and whether the device is enabled for the relevant notification category. This makes individual troubleshooting more effective without asking users to reinstall immediately.
Common mistakes
Several approaches create avoidable gaps during an upgrade:
- Treating a push token as a permanent identifier
- Registering only after a user signs in, leaving anonymous or logged-out states unmanaged
- Sending with a device identifier from the wrong environment
- Changing tag or segment names without migrating the sending logic
- Removing old payload fields before older clients have been retired
- Retrying timed-out sends with a new idempotency key every time
- Assuming permission granted in the old version remains granted in all states
- Testing only a clean install instead of an upgrade over real historical versions
- Deleting old registrations immediately when a new token appears
- Logging raw tokens or other sensitive identifiers without a clear need
The remedy is usually the same: make registration repeatable, identity explicit, environments visible and rollout reversible.
Conclusion
Notification continuity during an app upgrade depends on disciplined state management. Refresh device registrations, separate user identity from replaceable tokens, verify environment and payload compatibility, protect server-side retries with idempotency and release in stages. Test upgrade paths as carefully as clean installs, and monitor the registration lifecycle as well as the final send. With those controls in place, an upgrade becomes a managed migration rather than a sudden loss of reachability.