fix: queue user and device ID changes for proper event ordering by polbins · Pull Request #349 · amplitude/Amplitude-Kotlin

polbins · 2026-02-02T22:32:06Z

Describe what this PR is addressing

Identity changes setUserId() / setDeviceId() / reset() followed by track() could send events with stale identity because identity changes and events were processed on different dispatchers with no ordering guarantee.

Identity changes ran on amplitudeDispatcher
Events processed on storageIODispatcher

No ordering guarantee between the two.

Describe the solution

Dual-path architecture:

Immediate - store.userId = value updates in-memory state synchronously for event enrichment and plugin notifications
Background - super.setUserId() dispatches idContainer.commit() via coroutine for disk persistence

Key changes:

Amplitude.kt: Android overrides update store immediately then delegate to core for persistence
State.kt: Unified Identity object with synchronized access and idempotent observer notifications
AndroidContextPlugin.kt: Refactored to pure createDeviceId() function

Steps to verify the change

Manual verification:

Call setUserId("user1") then immediately track("event1")
- Verify event1 has userId "user1"
Call reset() then immediately track("event2")
- Verify event2 has a new deviceId (not the previous one)

Checklist

Does your PR title have the correct title format?
Does your PR have a breaking change? No

Note

Medium Risk
Touches core identity/state synchronization and device ID initialization paths, which can affect event attribution and persistence across platforms despite added test coverage.

Overview
Fixes cases where setUserId()/setDeviceId()/reset() followed by track() could emit events with stale identity by updating in-memory identity (State) synchronously and only committing to the identity manager asynchronously.

Android initialization now computes and persists deviceId during buildInternal (preferring configured ID, then stored non-AppSet IDs, then generated), while AndroidContextPlugin is refactored to a pure createDeviceId() helper and deprecates plugin-driven identity setting. Core State is reworked to hold a synchronized Identity object with idempotent observer notifications, ContextPlugin no longer performs deviceId initialization, and new tests assert ordering for setUserId, setDeviceId, identify options, and reset().

^{Written by Cursor Bugbot for commit 4203557. This will update automatically on new commits. Configure here.}

macroscopeapp · 2026-02-02T22:32:56Z

Queue identity updates and commit them in `android.Timeline` to ensure `setUserId`, `setDeviceId`, and `reset` apply before subsequent events on Android

Route setUserId, setDeviceId, and reset through a new android.Timeline.queueSetIdentity message that commits identity changes in FIFO order; initialize deviceId deterministically in android.Amplitude using AndroidContextPlugin.createDeviceId; remove pre-build deviceId setting from plugins and core; add tests for ordering.

🖇️ Linked Issues

Addresses ordering concerns related to Start Session enrichment noted in AMP-133018 by ensuring identity and properties updates precede subsequent events.

📍Where to Start

Start with processEventMessage and queueSetIdentity in android/src/main/java/com/amplitude/android/Timeline.kt, then review identity initialization in android/src/main/java/com/amplitude/android/Amplitude.kt.

Macroscope summarized 06a697d.

android/src/main/java/com/amplitude/android/Timeline.kt

core/src/main/java/com/amplitude/core/Amplitude.kt

android/src/main/java/com/amplitude/android/Amplitude.kt

android/src/main/java/com/amplitude/android/Timeline.kt

polbins · 2026-02-03T18:51:19Z

Converting to draft again, there is still a case that needs to be handled:
#349 (comment)

sojingle

LGTM!

core/src/main/java/com/amplitude/core/State.kt

android/src/main/java/com/amplitude/android/Amplitude.kt

core/src/main/java/com/amplitude/core/State.kt

android/src/main/java/com/amplitude/android/plugins/AnalyticsConnectorIdentityPlugin.kt

android/src/main/java/com/amplitude/android/Amplitude.kt

android/src/main/java/com/amplitude/android/plugins/AndroidContextPlugin.kt

android/src/main/java/com/amplitude/android/Amplitude.kt

core/src/main/java/com/amplitude/core/platform/Plugin.kt

android/src/main/java/com/amplitude/android/Amplitude.kt

android/src/main/java/com/amplitude/android/plugins/AndroidContextPlugin.kt

android/src/main/java/com/amplitude/android/Amplitude.kt

core/src/main/java/com/amplitude/core/Amplitude.kt

android/src/main/java/com/amplitude/android/Timeline.kt

- core's timeline is empty as it is, so focusing on Android for now

…essing

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-11T19:10:32Z

android/src/main/java/com/amplitude/android/Amplitude.kt

+
+    override fun setDeviceId(deviceId: String): Amplitude {
+        store.deviceId = deviceId
+        super.setDeviceId(deviceId)


Deferred identity callbacks can overwrite newer immediate state

Medium Severity

The dual-write architecture introduces a race: the Android setDeviceId/setUserId overrides write to store immediately, then super launches a deferred coroutine that commits to the identity manager, whose AnalyticsIdentityListener callback writes to store again. When two calls happen in succession with different values, the deferred callback from the first call can temporarily revert the store to the stale value, causing events enriched during that window (on storageIODispatcher) to pick up the wrong identity — the exact problem this PR aims to fix.

Additional Locations (1)

core/src/main/java/com/amplitude/core/utilities/AnalyticsIdentityListener.kt#L8-L15

It's a pre-existing race in core's coroutine dispatch + listener pattern, not introduced by this PR. Noted, in case it becomes an issue later.

I think this is valid - state would be temporarily overwritten by AnalyticsIdentityListener, leading to the same mismatch between what was set and what we add to events. Does AnalyticsIdentityListener still have to update the state on initialization if we're already updating state from the user/device id setters?

It looks to me that the onUserIdChange/onDeviceIdChange is the one flagged here.
So I made those noop, since we're updating state ourselves anyway.

Can experiment edit the identity too? The callbacks on AnalyticsIdentityListener still may be used even if they aren't used here.

I do see a race condition here specifically in the IdentityUpdateType.Initialized path in AnalyticsIdentityListener -

init(deviceId: A) // sets state deviceId: A, async kicks off AnalyticsIdentityListener.init
setDeviceId: B // sets state deviceId: B
init async callback // sets state deviceId: A again

android/src/main/java/com/amplitude/android/Amplitude.kt

crleona · 2026-02-11T20:33:39Z

android/src/main/java/com/amplitude/android/Amplitude.kt

+
+    override fun setDeviceId(deviceId: String): Amplitude {
+        store.deviceId = deviceId
+        super.setDeviceId(deviceId)


I think this is valid - state would be temporarily overwritten by AnalyticsIdentityListener, leading to the same mismatch between what was set and what we add to events. Does AnalyticsIdentityListener still have to update the state on initialization if we're already updating state from the user/device id setters?

crleona · 2026-02-11T20:34:29Z

android/src/main/java/com/amplitude/android/plugins/AndroidContextPlugin.kt

+            configuration.deviceId
+                ?: amplitude.store.deviceId?.takeIf { validDeviceId(it, allowAppSetId = false) }
+                ?: createDeviceId()
+        amplitude.setDeviceId(deviceId)


this saved to storage synchronously in the previous version - could you please maintain that behavior?

The initializeDeviceId is no longer called internally, deprecated it just in case some external usage exists for some reason.

Now the actual init path is in buildInternal() which now persists directly

Previously all the calls here went from setDeviceId -> amplitude.setDeviceIdInternal (via the AndroidContextPlugin override) -> idContainer.identityManager.editIdentity().setDeviceId(deviceId).commit(). It seems like this now waits for isBuilt in the core amplitude instance.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-12T23:02:18Z

core/src/main/java/com/amplitude/core/utilities/AnalyticsIdentityListener.kt

        if (updateType == IdentityUpdateType.Initialized) {
-            state.userId = identity.userId
-            state.deviceId = identity.deviceId
-            // TODO("update device id based on configuration")


No-op identity callbacks lose state after initialization overwrites

Medium Severity

Making onUserIdChange and onDeviceIdChange no-ops removes the feedback loop that corrected state after the Initialized callback. If setUserId("x") is called before build completes, store.userId is set to "x" immediately. Then createIdentityContainer fires onIdentityChanged(persisted, Initialized), overwriting the store with persisted values (e.g., null). After isBuilt completes, the deferred commit() fires onUserIdChange("x") — which is now a no-op — so the store permanently loses "x". The old code restored state correctly through this callback.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-13T22:26:45Z

core/src/main/java/com/amplitude/core/Amplitude.kt

-            },
-        )
+        configuration.deviceId?.let { setDeviceId(it) }
+        add(ContextPlugin())


Core build no longer initializes device ID

High Severity

buildInternal() now sets deviceId only when configuration.deviceId is provided. Since ContextPlugin no longer initializes identity in setup(), fresh core instances can start with store.deviceId == null, causing events enriched by ContextPlugin to carry a missing deviceId.

Additional Locations (1)

core/src/main/java/com/amplitude/core/platform/plugins/ContextPlugin.kt#L8-L16

macroscopeapp bot reviewed Feb 2, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Timeline.kt Outdated Show resolved Hide resolved

polbins force-pushed the pintal/AMP-AMP-133018/user-id-change-ordering branch from ca80fc8 to 8b5f5ec Compare February 3, 2026 00:31

macroscopeapp bot reviewed Feb 3, 2026

View reviewed changes

core/src/main/java/com/amplitude/core/Amplitude.kt Show resolved Hide resolved

android/src/main/java/com/amplitude/android/Amplitude.kt Show resolved Hide resolved

polbins changed the title ~~fix: queue user and device ID changes for proper event ordering~~ fix(android): queue user and device ID changes for proper event ordering Feb 3, 2026

polbins force-pushed the pintal/AMP-AMP-133018/user-id-change-ordering branch from 2ff8cdd to c57c618 Compare February 3, 2026 18:15

polbins marked this pull request as ready for review February 3, 2026 18:17

macroscopeapp bot mentioned this pull request Feb 3, 2026

(via polbins): Fix race condition in ContextPlugin by adding synchronous deviceId initi #350

Closed

polbins changed the title ~~fix(android): queue user and device ID changes for proper event ordering~~ fix: queue user and device ID changes for proper event ordering Feb 3, 2026

polbins requested review from crleona and sojingle February 3, 2026 18:27

macroscopeapp bot mentioned this pull request Feb 3, 2026

(via polbins): Add setDeviceIdDuringInit() to fix race condition during device ID initi #351

Closed

cursor bot reviewed Feb 3, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Timeline.kt Outdated Show resolved Hide resolved

polbins marked this pull request as draft February 3, 2026 18:50

polbins marked this pull request as ready for review February 3, 2026 19:52

sojingle approved these changes Feb 4, 2026

View reviewed changes

macroscopeapp bot reviewed Feb 4, 2026

View reviewed changes

core/src/main/java/com/amplitude/core/State.kt Show resolved Hide resolved

android/src/main/java/com/amplitude/android/Amplitude.kt Outdated Show resolved Hide resolved

android/src/main/java/com/amplitude/android/Amplitude.kt Outdated Show resolved Hide resolved

cursor bot reviewed Feb 4, 2026

View reviewed changes

core/src/main/java/com/amplitude/core/State.kt Outdated Show resolved Hide resolved

android/src/main/java/com/amplitude/android/plugins/AnalyticsConnectorIdentityPlugin.kt Outdated Show resolved Hide resolved

cursor bot reviewed Feb 4, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Amplitude.kt Show resolved Hide resolved

macroscopeapp bot reviewed Feb 4, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/plugins/AndroidContextPlugin.kt Show resolved Hide resolved

macroscopeapp bot reviewed Feb 5, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Amplitude.kt Outdated Show resolved Hide resolved

cursor bot reviewed Feb 5, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Amplitude.kt Show resolved Hide resolved

android/src/main/java/com/amplitude/android/Amplitude.kt Show resolved Hide resolved

polbins force-pushed the pintal/AMP-AMP-133018/user-id-change-ordering branch from 5aab61a to 0139681 Compare February 5, 2026 18:27

cursor bot reviewed Feb 5, 2026

View reviewed changes

core/src/main/java/com/amplitude/core/platform/Plugin.kt Outdated Show resolved Hide resolved

macroscopeapp bot reviewed Feb 5, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Amplitude.kt Show resolved Hide resolved

android/src/main/java/com/amplitude/android/Amplitude.kt Outdated Show resolved Hide resolved

android/src/main/java/com/amplitude/android/plugins/AndroidContextPlugin.kt Outdated Show resolved Hide resolved

polbins force-pushed the pintal/AMP-AMP-133018/user-id-change-ordering branch from ab4feba to 1a91523 Compare February 5, 2026 20:13

macroscopeapp bot reviewed Feb 5, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Amplitude.kt Show resolved Hide resolved

cursor bot reviewed Feb 5, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Amplitude.kt Show resolved Hide resolved

polbins force-pushed the pintal/AMP-AMP-133018/user-id-change-ordering branch from 1a91523 to 06a697d Compare February 5, 2026 21:38

crleona reviewed Feb 6, 2026

View reviewed changes

android/src/main/java/com/amplitude/android/Amplitude.kt Outdated Show resolved Hide resolved

core/src/main/java/com/amplitude/core/Amplitude.kt Show resolved Hide resolved

android/src/main/java/com/amplitude/android/Timeline.kt Outdated Show resolved Hide resolved

polbins added 13 commits February 11, 2026 10:48

fix: queue user and device ID changes for proper event ordering

f3ac02f

refactor: simplify device and user ID handling in Amplitude

5523406

fix: add logging on failed channel send

a6499e4

make queuing logic to android timeline only

5f87fa0

- core's timeline is empty as it is, so focusing on Android for now

simplify event types and logging

02f312f

refactor: update reset logic to queue device ID reset in timeline

6d2f6e6

refactor: streamline device ID generation and handling

e5b49c0

refactor: unify identity handling and streamline identity change proc…

5259267

…essing

update reset logic to generate new deviceId and clear identity

9b897f0

address review comments

134b9c5

remove onIdentityChanged

5ea7b9c

simplify device id stuff

bac5645

simplify identity updates, use coroutine dispatch instead of event queue

d18d353

polbins force-pushed the pintal/AMP-AMP-133018/user-id-change-ordering branch from 06a697d to d18d353 Compare February 11, 2026 18:58

cursor bot reviewed Feb 11, 2026

View reviewed changes

crleona reviewed Feb 11, 2026

View reviewed changes

cursor bot reviewed Feb 12, 2026

View reviewed changes

address review comments

4203557

polbins force-pushed the pintal/AMP-AMP-133018/user-id-change-ordering branch from f365fb3 to 4203557 Compare February 13, 2026 22:22

cursor bot reviewed Feb 13, 2026

View reviewed changes

polbins closed this Feb 13, 2026

Conversation

polbins commented Feb 2, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe what this PR is addressing

Describe the solution

Steps to verify the change

Checklist

Uh oh!

macroscopeapp bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Queue identity updates and commit them in android.Timeline to ensure setUserId, setDeviceId, and reset apply before subsequent events on Android

🖇️ Linked Issues

📍Where to Start

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

polbins commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sojingle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 11, 2026

Choose a reason for hiding this comment

Deferred identity callbacks can overwrite newer immediate state

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 12, 2026

Choose a reason for hiding this comment

No-op identity callbacks lose state after initialization overwrites

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 13, 2026

Choose a reason for hiding this comment

Core build no longer initializes device ID

polbins commented Feb 2, 2026 •

edited by cursor bot

Loading

macroscopeapp bot commented Feb 2, 2026 •

edited

Loading

Queue identity updates and commit them in `android.Timeline` to ensure `setUserId`, `setDeviceId`, and `reset` apply before subsequent events on Android

polbins commented Feb 3, 2026 •

edited

Loading