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

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

@@ -7,6 +7,7 @@ import com.amplitude.android.migration.MigrationManager
 import com.amplitude.android.plugins.AnalyticsConnectorIdentityPlugin
 import com.amplitude.android.plugins.AnalyticsConnectorPlugin
 import com.amplitude.android.plugins.AndroidContextPlugin
+import com.amplitude.android.plugins.AndroidContextPlugin.Companion.validDeviceId
 import com.amplitude.android.plugins.AndroidLifecyclePlugin
 import com.amplitude.android.plugins.AndroidNetworkConnectivityCheckerPlugin
 import com.amplitude.android.storage.AndroidStorageContextV3
@@ -97,14 +98,15 @@ open class Amplitude internal constructor(
         if (this.configuration.offline != AndroidNetworkConnectivityCheckerPlugin.Disabled) {
             add(AndroidNetworkConnectivityCheckerPlugin())
         }
-        androidContextPlugin =
-            object : AndroidContextPlugin() {
-                override fun setDeviceId(deviceId: String) {
-                    // call internal method to set deviceId immediately i.e. dont' wait for build() to complete
-                    this@Amplitude.setDeviceIdInternal(deviceId)
-                }
-            }
+        androidContextPlugin = AndroidContextPlugin()
         add(androidContextPlugin)
+        val deviceId =
+            configuration.deviceId
+                ?: store.deviceId?.takeIf { validDeviceId(it, allowAppSetId = false) }
+                ?: androidContextPlugin.createDeviceId()
+        // Persist device ID synchronously during build (not via coroutine dispatch)
+        store.deviceId = deviceId
+        idContainer.identityManager.editIdentity().setDeviceId(deviceId).commit()
         add(GetAmpliExtrasPlugin())
         add(AndroidLifecyclePlugin(activityLifecycleCallbacks))
         add(AnalyticsConnectorIdentityPlugin())
@@ -126,20 +128,29 @@ open class Amplitude internal constructor(
 
     /**
      * Reset identity:
-     *  - reset userId to "null"
-     *  - reset deviceId via AndroidContextPlugin
+     *  - reset userId to null
+     *  - generate and set a new deviceId
      * @return the Amplitude instance
      */
     override fun reset(): Amplitude {
-        this.setUserId(null)
         amplitudeScope.launch(amplitudeDispatcher) {
             isBuilt.await()
-            idContainer.identityManager.editIdentity().setDeviceId(null).commit()
-            androidContextPlugin.initializeDeviceId(configuration as Configuration)
+            setUserId(null)
+            setDeviceId(androidContextPlugin.createDeviceId())
         }
         return this
     }
 
+    override fun setUserId(userId: String?): Amplitude {
+        super.setUserId(userId)
+        return this
+    }
+
+    override fun setDeviceId(deviceId: String): Amplitude {
+        super.setDeviceId(deviceId)
+        return this
+    }
+
     @GuardedAmplitudeFeature
     fun onEnterForeground(timestamp: Long) {
         (timeline as Timeline).onEnterForeground(timestamp)

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

@@ -2,6 +2,9 @@ package com.amplitude.android
 
 import com.amplitude.android.Amplitude.Companion.END_SESSION_EVENT
 import com.amplitude.android.Amplitude.Companion.START_SESSION_EVENT
+import com.amplitude.android.EventQueueMessage.EnterForeground
+import com.amplitude.android.EventQueueMessage.Event
+import com.amplitude.android.EventQueueMessage.ExitForeground
 import com.amplitude.core.Storage
 import com.amplitude.core.Storage.Constants
 import com.amplitude.core.Storage.Constants.LAST_EVENT_ID
@@ -10,6 +13,7 @@ import com.amplitude.core.Storage.Constants.PREVIOUS_SESSION_ID
 import com.amplitude.core.events.BaseEvent
 import com.amplitude.core.platform.Timeline
 import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.channels.onFailure
 import kotlinx.coroutines.launch
 import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.atomic.AtomicLong
@@ -65,34 +69,31 @@ class Timeline(
             incomingEvent.timestamp = System.currentTimeMillis()
         }
 
-        val result = eventMessageChannel.trySend(EventQueueMessage.Event(incomingEvent))
-        if (result.isFailure) {
-            amplitude.logger.error("Failed to enqueue event: ${incomingEvent.eventType}. Channel is closed or full.")
-        }
+        eventMessageChannel.trySendAndLog(Event(incomingEvent))
     }
 
     internal fun onEnterForeground(timestamp: Long) {
-        eventMessageChannel.trySend(EventQueueMessage.EnterForeground(timestamp))
+        eventMessageChannel.trySendAndLog(EnterForeground(timestamp))
     }
 
     internal fun onExitForeground(timestamp: Long) {
-        eventMessageChannel.trySend(EventQueueMessage.ExitForeground(timestamp))
+        eventMessageChannel.trySendAndLog(ExitForeground(timestamp))
     }
 
     /**
      * Process an event message from the event queue.
      */
     private suspend fun processEventMessage(message: EventQueueMessage) {
         when (message) {
-            is EventQueueMessage.EnterForeground -> {
+            is EnterForeground -> {
                 val stopAndStartSessionEvents = startNewSessionIfNeeded(message.timestamp)
                 foreground.set(true)
                 processAndPersistEvents(stopAndStartSessionEvents)
             }
-            is EventQueueMessage.Event -> {
+            is Event -> {
                 processEvent(message.event)
             }
-            is EventQueueMessage.ExitForeground -> {
+            is ExitForeground -> {
                 foreground.set(false)
                 refreshSessionTime(message.timestamp)
             }
@@ -202,6 +203,12 @@ class Timeline(
         return sessionId > DEFAULT_SESSION_ID
     }
 
+    private fun Channel<EventQueueMessage>.trySendAndLog(event: EventQueueMessage) =
+        trySend(event)
+            .onFailure {
+                amplitude.logger.error("Failed to enqueue event $event. Channel is closed or full.")
+            }
+
     private fun Storage.readLong(
         key: Constants,
         default: Long,

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

@@ -7,13 +7,11 @@ import com.amplitude.common.android.AndroidContextProvider
 import com.amplitude.core.Amplitude
 import com.amplitude.core.RestrictedAmplitudeFeature
 import com.amplitude.core.events.BaseEvent
-import com.amplitude.core.platform.Plugin
+import com.amplitude.core.platform.plugins.ContextPlugin
 import java.util.UUID
 
 @OptIn(RestrictedAmplitudeFeature::class)
-open class AndroidContextPlugin : Plugin {
-    override val type: Plugin.Type = Plugin.Type.Before
-    override lateinit var amplitude: Amplitude
+open class AndroidContextPlugin : ContextPlugin() {
     private lateinit var contextProvider: AndroidContextProvider
 
     override fun setup(amplitude: Amplitude) {
@@ -26,8 +24,6 @@ open class AndroidContextPlugin : Plugin {
                 configuration.trackingOptions.shouldTrackAdid(),
                 configuration.trackingOptions.shouldTrackAppSetId(),
             )
-        initializeDeviceId(configuration)
-
         amplitude.diagnosticsClient.setTag(
             name = "sdk.${SDK_LIBRARY}.version",
             value = SDK_VERSION,
@@ -39,45 +35,56 @@ open class AndroidContextPlugin : Plugin {
         return event
     }
 
-    fun initializeDeviceId(configuration: Configuration) {
-        // Check configuration
-        var deviceId = configuration.deviceId
-        if (deviceId != null) {
-            setDeviceId(deviceId)
-            return
-        }
-
-        // Check store
-        deviceId = amplitude.store.deviceId
-        if (deviceId != null && validDeviceId(deviceId) && !deviceId.endsWith("S")) {
-            return
-        }
+    /**
+     * Create a device ID from available sources.
+     * Priority: advertising ID -> app set ID -> random UUID
+     */
+    internal fun createDeviceId(): String {
+        val configuration = amplitude.configuration as Configuration
 
-        // Check new device id per install
+        // Check advertising ID (if enabled and not per-install)
         if (!configuration.newDeviceIdPerInstall &&
             configuration.useAdvertisingIdForDeviceId &&
             !contextProvider.isLimitAdTrackingEnabled()
         ) {
-            val advertisingId = contextProvider.advertisingId
-            if (advertisingId != null && validDeviceId(advertisingId)) {
-                setDeviceId(advertisingId)
-                return
+            contextProvider.advertisingId?.let { advertisingId ->
+                if (validDeviceId(advertisingId)) {
+                    return advertisingId
+                }
             }
         }
 
-        // Check app set id
+        // Check app set ID (if enabled)
         if (configuration.useAppSetIdForDeviceId) {
-            val appSetId = contextProvider.appSetId
-            if (appSetId != null && validDeviceId(appSetId)) {
-                setDeviceId("${appSetId}S")
-                return
+            contextProvider.appSetId?.let { appSetId ->
+                if (validDeviceId(appSetId)) {
+                    return "$appSetId$DEVICE_ID_SUFFIX_APP_SET_ID"
+                }
             }
         }
 
-        // Generate random id
-        val generatedUuid = UUID.randomUUID().toString()
-        val randomId = generatedUuid + "R"
-        setDeviceId(randomId)
+        // Generate random ID
+        return UUID.randomUUID().toString() + DEVICE_ID_SUFFIX_RANDOM
+    }
+
+    @Deprecated(
+        message = "Use createDeviceId() instead. Amplitude now handles setting the deviceId.",
+        replaceWith = ReplaceWith("createDeviceId()"),
+    )
+    fun initializeDeviceId(configuration: Configuration) {
+        val deviceId =
+            configuration.deviceId
+                ?: amplitude.store.deviceId?.takeIf { validDeviceId(it, allowAppSetId = false) }
+                ?: createDeviceId()
+        amplitude.setDeviceId(deviceId)
+    }
+
+    @Deprecated(
+        message = "Use Amplitude.setDeviceId() instead. The plugin should not set identity directly.",
+        replaceWith = ReplaceWith("amplitude.setDeviceId(deviceId)"),
+    )
+    protected open fun setDeviceId(deviceId: String) {
+        amplitude.setDeviceId(deviceId)
     }
 
     private fun applyContextData(event: BaseEvent) {
@@ -171,19 +178,37 @@ open class AndroidContextPlugin : Plugin {
         }
     }
 
-    protected open fun setDeviceId(deviceId: String) {
-        amplitude.setDeviceId(deviceId)
-    }
-
     companion object {
         const val PLATFORM = "Android"
         const val SDK_LIBRARY = "amplitude-analytics-android"
         const val SDK_VERSION = BuildConfig.AMPLITUDE_VERSION
+
+        /**
+         * Device ID suffix indicating the ID was derived from App Set ID.
+         *
+         * When a stored device ID ends with this suffix, [createDeviceId] will attempt
+         * to regenerate it to potentially upgrade to a better identifier (e.g., advertising ID
+         * if the user later grants permission).
+         */
+        private const val DEVICE_ID_SUFFIX_APP_SET_ID = "S"
+
+        /**
+         * Device ID suffix indicating the ID is a randomly generated UUID.
+         */
+        private const val DEVICE_ID_SUFFIX_RANDOM = "R"
+
         private val INVALID_DEVICE_IDS =
             setOf("", "9774d56d682e549c", "unknown", "000000000000000", "Android", "DEFACE", "00000000-0000-0000-0000-000000000000")
 
-        fun validDeviceId(deviceId: String): Boolean {
-            return !(deviceId.isEmpty() || INVALID_DEVICE_IDS.contains(deviceId))
+        fun validDeviceId(
+            deviceId: String,
+            allowAppSetId: Boolean = true,
+        ): Boolean {
+            return when {
+                deviceId.isEmpty() || INVALID_DEVICE_IDS.contains(deviceId) -> false
+                !allowAppSetId && deviceId.endsWith(DEVICE_ID_SUFFIX_APP_SET_ID) -> false
+                else -> true
+            }
         }
     }
 }