Blueprint update causing app downgrade and full device reconfiguration: use version pinning, Converge targeting, and Managed Configuration for per-device tokens

Android

When you update a Blueprint with an older app version, Esper's Converge mechanism may downgrade apps on your devices to match the Blueprint specification. If your app stores device-specific data—like access tokens—in local storage, this downgrade can wipe that data and require manual reconfiguration across your fleet. This article explains how to prevent this scenario and implement a scalable solution using version pinning, selective Converge targeting, and Managed Configuration.

Understanding the problem

When you run Converge on a device group, Esper enforces the Blueprint as the source of truth for app versions. If your Blueprint specifies app v1.0.0 but devices are running v2.0.0, Converge will reinstall v1.0.0 to bring devices into compliance. If your app stores per-device access tokens in local app data, this reinstallation clears that data and requires you to manually re-enter the token on each affected device.

This is expected platform behavior: Blueprints enforce declarative state. The operational issue occurs when the Blueprint's app version field is not updated to match your production app version before Converge is executed.

Step 1: Keep your Blueprint app version current before running Converge

1. Open the Esper Console and navigate to Blueprints → [Your Blueprint Name] → Apps.
2. Check the APK version pinned in the Blueprint.
3. Verify this version matches the app version currently deployed on your production devices.
4. If your production devices are running a newer version, update the Blueprint's app version field to that same version.
5. Save the Blueprint.
6. Only after the Blueprint version is aligned with production, run Converge: navigate to Devices & Groups → [Your Group] → Blueprint → Converge.

Step 2: Use Converge selectively

Run Converge only on device groups or individual devices that require updates. This reduces the risk of unintended changes across your fleet.

• If you need to push a single setting change (for example, granting Camera permission) without affecting app install state, update only that specific setting in the Blueprint.
• Run Converge against only the devices or groups that require the change—not your entire fleet.
• For per-device changes that should not propagate fleet-wide, make the change directly on the individual device by navigating to Devices & Groups → [Device Name] → [Setting]. Esper will record this as Drift rather than overwriting it on the next Converge unless you explicitly reconcile it.

Step 3: Use Managed Configuration to automate token delivery (recommended for scale)

The most scalable solution is to configure your app to read device-specific tokens from Managed Configuration instead of storing them in local app data. This way, tokens are reapplied automatically after any reinstall or upgrade.

1. Work with your app developers to implement Android Managed Configuration support. This allows your app to read its configuration—including device tokens or identifiers—from the managed config bundle at launch.
2. In the Esper Console, navigate to Blueprints → [Your Blueprint] → Apps → [Your App] → Managed Configuration.
3. Configure the token or identifier field using an Esper dynamic placeholder:
   • ${esper.serialNumber} — pushes the device's serial number
   • ${esper.uuid} — pushes the Esper device UUID
4. Save the Managed Configuration.
5. When you run Converge, Esper substitutes the placeholder with the device-specific value and delivers it to the app via the managed config channel. Your app reads this value on launch and uses it to look up or activate the correct token from your backend—no manual entry required.
6. After Converge completes, open your app on a test device and verify it completes setup automatically without prompting for manual token entry. Confirm in your backend that the device is registered with the correct token.

Still need help?

If you encounter issues or need guidance on implementing Managed Configuration for your app, contact Esper Support.