Application code change behavior

Application code change behavior

This page explains what happens across the whole platform (SDK, backend, and message delivery) when the application code configured for an app changes on a device that was previously registered with a different application code.

Application code should ideally never change for a given application. It's tied to the application, not to which Infobip plugin/SDK you use. If you migrate your mobile integration from one framework to another (for example, from Cordova to React Native, or from a native integration to Flutter) while keeping the same Android package name, the existing application code continues to work unchanged — there is no need to create a new one. Treat an application code change as a deliberate, rare operation, not a routine step of a plugin migration.

Table of contents

• Fresh install vs. application code change
• What the Android SDK does locally
• What happens on the backend
• Effect on sending and targeting
• Practical guidance

Fresh install vs. application code change

A brand-new installation that has never had an application code stored locally is unaffected by anything on this page — it simply registers normally against whichever application code it's configured with. Everything described below only applies to an existing installation whose application code changes from a previously stored value to a different one (e.g., a client build is repointed from an old application to a new one).

What the Android SDK does locally

On SDK init (MobileMessaging.Builder.build()), the SDK compares the newly-provided application code (or its hash, if ApplicationCodeProvider is used) against the one persisted in SharedPreferences. If a previously stored value exists and differs from the new one, MobileMessagingCore.cleanup() runs, which:

• Removes the stored push registration ID and the cloud/FCM token, and enqueues deletion of the local FCM token so a new one is requested from Firebase.
• Removes user data, custom attributes, and the "primary device" unreported flag.
• Removes message-sync bookkeeping (unreported/unsent message IDs).
• Notifies registered feature modules (chat, inbox) to clean up their own cached data.
• Resets cached synchronizers and the HTTP client so subsequent requests use the new application code.

The local message store (SQLite) is not cleared by this cleanup — previously received messages remain on the device.

No explicit delete/depersonalize call is made to the backend for the old registration. The SDK simply forgets the old registration ID locally; once a new FCM token arrives, the normal installation-sync flow performs what is effectively a fresh registration under the new application code. Because token cleanup and re-registration happen asynchronously, there can be a narrow transition window where the old token/registration combination may still work briefly before the new one takes over.

What happens on the backend

• A push registration ID is permanently bound to a single application code on the backend. The device's next registration under the new application code always creates a brand-new registration ID — there is no way to move an existing registration ID to a different application.
• That new registration always creates a brand-new anonymous LEAD person profile. Registration alone doesn't carry any user identity (external user ID, phone, email), so there's nothing to automatically link the new profile to the one that existed under the old application code.
• The old registration and its old person profile are not deleted or deactivated automatically. Nothing in the SDK or the backend proactively cleans it up as a side effect of the new registration — it simply becomes orphaned and stays live until it naturally expires from inactivity, or until it's explicitly deleted.
• The new registration only converges with the old person profile if the app explicitly re-personalizes with the same external user ID/phone/email as before — that's the normal personalize/merge flow, and it does not happen automatically just because it's the same physical device.

Effect on sending and targeting

Sending to the new application only reaches devices that have already completed a fresh registration under the new application code — practically, that means users who have opened the updated app at least once after the change (registration happens automatically on next SDK init).

Sending to the old application can, in principle, still reach the orphaned old registration on the backend, but the device-side token swap means that reachability is short-lived.

Practical guidance

• Avoid changing application code unless truly necessary. Migrating between Infobip mobile plugins/SDKs with the same package name does not require it.
• If a clean cutover is required (e.g., for compliance or to stop stale sends to old-application registrations), don't rely on automatic cleanup alone — plan the migration so old-application registrations are retired intentionally as part of the rollout, rather than expecting the SDK to clean them up for you.
• Encourage end users to open the updated app so their device completes the fresh registration under the new application code.