feat: Add server-stored ID support and rename device identifiers

This commit implements server-generated stored IDs (similar to browser
cookies in the JS implementation) and renames the existing device-generated
identifiers for clarity.

Changes:
- Rename StoredIDs → DeviceIDs for device-generated hardware identifiers
  (MediaDRM ID, Android ID)
- Add StoredID model for server-generated IDs (format: "{uuid}:{hmac}")
- Add StoredIDStorage using SharedPreferences for persistence
- Add StoredIDCollector to read stored IDs during collection
- Update DeviceApiClient to parse server response and return stored ID
- Update DeviceTracker to save stored ID from server response
- Add @SerialName annotations for snake_case JSON serialization

JSON field names use snake_case for consistency with other MaxMind services:
- stored_id, device_ids, media_drm_id, android_id

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: oschwald

device-sdk/src/main/java/com/maxmind/device/DeviceTracker.kt

@@ -6,6 +6,7 @@ import com.maxmind.device.collector.DeviceDataCollector
 import com.maxmind.device.config.SdkConfig
 import com.maxmind.device.model.DeviceData
 import com.maxmind.device.network.DeviceApiClient
+import com.maxmind.device.storage.StoredIDStorage
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
@@ -44,7 +45,8 @@ public class DeviceTracker private constructor(
     private val config: SdkConfig,
 ) {
     private val applicationContext: Context = context.applicationContext
-    private val deviceDataCollector = DeviceDataCollector(applicationContext)
+    private val storedIDStorage = StoredIDStorage(applicationContext)
+    private val deviceDataCollector = DeviceDataCollector(applicationContext, storedIDStorage)
     private val apiClient =
         DeviceApiClient(
             serverUrl = config.serverUrl,
@@ -78,12 +80,21 @@ public class DeviceTracker private constructor(
      * Sends device data to MaxMind servers.
      *
      * This is a suspending function that should be called from a coroutine.
+     * On success, saves the server-generated stored ID for future requests.
      *
      * @param deviceData The device data to send
      * @return [Result] indicating success or failure
      */
     public suspend fun sendDeviceData(deviceData: DeviceData): Result<Unit> {
-        return apiClient.sendDeviceData(deviceData).map { Unit }
+        return apiClient.sendDeviceData(deviceData).map { response ->
+            // Save the stored ID from the server response
+            response.storedID?.let { id ->
+                storedIDStorage.save(id)
+                if (config.enableLogging) {
+                    Log.d(TAG, "Stored ID saved from server response")
+                }
+            }
+        }
     }
 
     /**

device-sdk/src/main/java/com/maxmind/device/collector/DeviceDataCollector.kt

@@ -15,6 +15,8 @@ import com.maxmind.device.model.DisplayInfo
 import com.maxmind.device.model.HardwareInfo
 import com.maxmind.device.model.InstallationInfo
 import com.maxmind.device.model.LocaleInfo
+import com.maxmind.device.model.StoredID
+import com.maxmind.device.storage.StoredIDStorage
 import java.util.Locale
 import java.util.TimeZone
 
@@ -23,9 +25,16 @@ import java.util.TimeZone
  *
  * This class is responsible for gathering various device attributes
  * that are available through the Android APIs.
+ *
+ * @param context Application context for accessing system services
+ * @param storedIDStorage Optional storage for server-generated stored IDs
  */
-internal class DeviceDataCollector(private val context: Context) {
-    private val storedIDsCollector = StoredIDsCollector(context)
+internal class DeviceDataCollector(
+    private val context: Context,
+    storedIDStorage: StoredIDStorage? = null,
+) {
+    private val storedIDCollector = storedIDStorage?.let { StoredIDCollector(it) }
+    private val deviceIDsCollector = DeviceIDsCollector(context)
     private val gpuCollector = GpuCollector()
     private val audioCollector = AudioCollector(context)
     private val sensorCollector = SensorCollector(context)
@@ -42,9 +51,10 @@ internal class DeviceDataCollector(private val context: Context) {
      *
      * @return [DeviceData] containing collected device information
      */
-    fun collect(): DeviceData {
-        return DeviceData(
-            storedIDs = storedIDsCollector.collect(),
+    fun collect(): DeviceData =
+        DeviceData(
+            storedID = storedIDCollector?.collect() ?: StoredID(),
+            deviceIDs = deviceIDsCollector.collect(),
             build = collectBuildInfo(),
             display = collectDisplayInfo(),
             hardware = collectHardwareInfo(),

…d/device/collector/StoredIDsCollector.kt …d/device/collector/DeviceIDsCollector.ktdevice-sdk/src/main/java/com/maxmind/device/collector/StoredIDsCollector.kt renamed to device-sdk/src/main/java/com/maxmind/device/collector/DeviceIDsCollector.kt device-sdk/src/main/java/com/maxmind/device/collector/StoredIDsCollector.kt renamed to device-sdk/src/main/java/com/maxmind/device/collector/DeviceIDsCollector.kt

@@ -1,31 +1,33 @@
 package com.maxmind.device.collector
 
+import android.annotation.SuppressLint
 import android.content.Context
 import android.media.MediaDrm
-import android.os.Build
 import android.provider.Settings
 import android.util.Base64
-import com.maxmind.device.model.StoredIDs
+import com.maxmind.device.model.DeviceIDs
 import java.util.UUID
 
 /**
- * Collects persistent device identifiers.
+ * Collects device-generated persistent identifiers.
  *
  * This collector gathers hardware-backed and app-scoped identifiers
- * that can be used for device fingerprinting.
+ * that can be used for device fingerprinting. These are distinct from
+ * server-generated stored IDs.
  */
-internal class StoredIDsCollector(private val context: Context) {
+internal class DeviceIDsCollector(
+    private val context: Context,
+) {
     /**
-     * Collects stored device identifiers.
+     * Collects device-generated identifiers.
      *
-     * @return [StoredIDs] containing available device identifiers
+     * @return [DeviceIDs] containing available device identifiers
      */
-    fun collect(): StoredIDs {
-        return StoredIDs(
+    fun collect(): DeviceIDs =
+        DeviceIDs(
             mediaDrmID = collectMediaDrmID(),
             androidID = collectAndroidID(),
         )
-    }
 
     /**
      * Collects the MediaDRM device unique ID.
@@ -35,19 +37,14 @@ internal class StoredIDsCollector(private val context: Context) {
      *
      * @return Base64-encoded device ID, or null if unavailable
      */
-    private fun collectMediaDrmID(): String? {
-        return try {
+    private fun collectMediaDrmID(): String? =
+        try {
             val mediaDrm = MediaDrm(WIDEVINE_UUID)
             try {
                 val deviceId = mediaDrm.getPropertyByteArray(MediaDrm.PROPERTY_DEVICE_UNIQUE_ID)
                 Base64.encodeToString(deviceId, Base64.NO_WRAP)
             } finally {
-                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
-                    mediaDrm.close()
-                } else {
-                    @Suppress("DEPRECATION")
-                    mediaDrm.release()
-                }
+                mediaDrm.close()
             }
         } catch (
             @Suppress("TooGenericExceptionCaught", "SwallowedException")
@@ -56,7 +53,6 @@ internal class StoredIDsCollector(private val context: Context) {
             // MediaDRM may not be available on all devices (e.g., emulators, some custom ROMs)
             null
         }
-    }
 
     /**
      * Collects the Android ID (SSAID).
@@ -67,8 +63,9 @@ internal class StoredIDsCollector(private val context: Context) {
      *
      * @return The Android ID string, or null if unavailable
      */
-    private fun collectAndroidID(): String? {
-        return try {
+    @SuppressLint("HardwareIds") // Intentional for fraud detection fingerprinting
+    private fun collectAndroidID(): String? =
+        try {
             Settings.Secure.getString(context.contentResolver, Settings.Secure.ANDROID_ID)
         } catch (
             @Suppress("TooGenericExceptionCaught", "SwallowedException")
@@ -77,7 +74,6 @@ internal class StoredIDsCollector(private val context: Context) {
             // Settings.Secure may throw on some custom ROMs or restricted contexts
             null
         }
-    }
 
     internal companion object {
         /**

device-sdk/src/main/java/com/maxmind/device/collector/StoredIDCollector.kt

@@ -0,0 +1,21 @@
+package com.maxmind.device.collector
+
+import com.maxmind.device.model.StoredID
+import com.maxmind.device.storage.StoredIDStorage
+
+/**
+ * Collects the server-generated stored ID from local storage.
+ *
+ * This collector retrieves the stored ID that was previously received
+ * from the server and saved to SharedPreferences.
+ */
+internal class StoredIDCollector(
+    private val storage: StoredIDStorage,
+) {
+    /**
+     * Collects the stored ID from local storage.
+     *
+     * @return [StoredID] containing the ID if available, or empty StoredID if not
+     */
+    fun collect(): StoredID = StoredID(id = storage.get())
+}

device-sdk/src/main/java/com/maxmind/device/model/DeviceData.kt

@@ -1,5 +1,6 @@
 package com.maxmind.device.model
 
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
@@ -10,8 +11,12 @@ import kotlinx.serialization.Serializable
  */
 @Serializable
 public data class DeviceData(
-    // Identifiers
-    val storedIDs: StoredIDs = StoredIDs(),
+    // Server-generated stored ID (like browser cookies)
+    @SerialName("stored_id")
+    val storedID: StoredID = StoredID(),
+    // Device-generated identifiers
+    @SerialName("device_ids")
+    val deviceIDs: DeviceIDs = DeviceIDs(),
     // Device info
     val build: BuildInfo,
     val display: DisplayInfo,

…va/com/maxmind/device/model/StoredIDs.kt …va/com/maxmind/device/model/DeviceIDs.ktdevice-sdk/src/main/java/com/maxmind/device/model/StoredIDs.kt renamed to device-sdk/src/main/java/com/maxmind/device/model/DeviceIDs.kt device-sdk/src/main/java/com/maxmind/device/model/StoredIDs.kt renamed to device-sdk/src/main/java/com/maxmind/device/model/DeviceIDs.kt

@@ -1,15 +1,21 @@
 package com.maxmind.device.model
 
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * Device identifiers that persist across sessions.
+ * Device-generated identifiers that persist across sessions.
+ *
+ * These are hardware/system identifiers generated on the device itself,
+ * distinct from server-generated stored IDs.
  *
  * @property mediaDrmID Hardware-backed ID from MediaDRM, persists through factory reset
  * @property androidID App-scoped ID from Settings.Secure, persists across reinstalls
  */
 @Serializable
-public data class StoredIDs(
+public data class DeviceIDs(
+    @SerialName("media_drm_id")
     val mediaDrmID: String? = null,
+    @SerialName("android_id")
     val androidID: String? = null,
 )

device-sdk/src/main/java/com/maxmind/device/model/ServerResponse.kt

@@ -0,0 +1,15 @@
+package com.maxmind.device.model
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * Response from the MaxMind device API.
+ *
+ * @property storedID The server-generated stored ID (format: "{uuid}:{hmac}")
+ */
+@Serializable
+public data class ServerResponse(
+    @SerialName("stored_id")
+    val storedID: String? = null,
+)

device-sdk/src/main/java/com/maxmind/device/model/StoredID.kt

@@ -0,0 +1,19 @@
+package com.maxmind.device.model
+
+import kotlinx.serialization.Serializable
+
+/**
+ * Server-generated identifier stored locally on the device.
+ *
+ * This ID is generated by the MaxMind server and sent back to the client
+ * for storage. It includes an HMAC signature to prevent tampering.
+ * Format: "{uuid}:{hmac}"
+ *
+ * Similar to browser cookies/localStorage stored IDs in the JS implementation.
+ *
+ * @property id The stored ID string in format "{uuid}:{hmac}", or null if not yet received from server
+ */
+@Serializable
+public data class StoredID(
+    val id: String? = null,
+)

device-sdk/src/main/java/com/maxmind/device/network/DeviceApiClient.kt

@@ -1,18 +1,19 @@
 package com.maxmind.device.network
 
 import com.maxmind.device.model.DeviceData
+import com.maxmind.device.model.ServerResponse
 import io.ktor.client.HttpClient
+import io.ktor.client.call.body
 import io.ktor.client.engine.android.Android
 import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
 import io.ktor.client.plugins.logging.LogLevel
 import io.ktor.client.plugins.logging.Logger
 import io.ktor.client.plugins.logging.Logging
-import io.ktor.client.request.header
 import io.ktor.client.request.post
 import io.ktor.client.request.setBody
-import io.ktor.client.statement.HttpResponse
 import io.ktor.http.ContentType
 import io.ktor.http.contentType
+import io.ktor.http.isSuccess
 import io.ktor.serialization.kotlinx.json.json
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.buildJsonObject
@@ -61,7 +62,7 @@ internal class DeviceApiClient(
      * Sends device data to the MaxMind API.
      *
      * @param deviceData The device data to send
-     * @return [Result] containing the HTTP response or an error
+     * @return [Result] containing the server response with stored ID, or an error
      */
     suspend fun sendDeviceData(deviceData: DeviceData): Result<ServerResponse> {
         return try {
@@ -74,14 +75,27 @@ internal class DeviceApiClient(
                         put(key, value)
                     }
                 }
-            Result.success(response)
+
+            if (response.status.isSuccess()) {
+                val serverResponse: ServerResponse = response.body()
+                Result.success(serverResponse)
+            } else {
+                Result.failure(
+                    ApiException("Server returned ${response.status.value}: ${response.status.description}"),
+                )
+            }
         } catch (
             @Suppress("TooGenericExceptionCaught") e: Exception,
         ) {
             Result.failure(e)
         }
     }
 
+    /**
+     * Exception thrown when API request fails.
+     */
+    public class ApiException(message: String) : Exception(message)
+
     /**
      * Closes the HTTP client and releases resources.
      */

device-sdk/src/main/java/com/maxmind/device/storage/StoredIDStorage.kt

@@ -0,0 +1,50 @@
+package com.maxmind.device.storage
+
+import android.content.Context
+import android.content.SharedPreferences
+import androidx.core.content.edit
+
+/**
+ * Manages persistent storage of server-generated stored IDs.
+ *
+ * Uses SharedPreferences for storage, similar to how the JS implementation
+ * uses cookies and localStorage. The stored ID is server-generated and
+ * includes an HMAC signature for validation.
+ */
+internal class StoredIDStorage(
+    context: Context,
+) {
+    private val prefs: SharedPreferences =
+        context.applicationContext.getSharedPreferences(
+            PREFS_NAME,
+            Context.MODE_PRIVATE,
+        )
+
+    /**
+     * Retrieves the stored ID.
+     *
+     * @return The stored ID string, or null if not set
+     */
+    fun get(): String? = prefs.getString(KEY_STORED_ID, null)
+
+    /**
+     * Saves a stored ID.
+     *
+     * @param id The stored ID to save (format: "{uuid}:{hmac}")
+     */
+    fun save(id: String) {
+        prefs.edit { putString(KEY_STORED_ID, id) }
+    }
+
+    /**
+     * Clears the stored ID.
+     */
+    fun clear() {
+        prefs.edit { remove(KEY_STORED_ID) }
+    }
+
+    internal companion object {
+        internal const val PREFS_NAME = "com.maxmind.device.storage"
+        internal const val KEY_STORED_ID = "stored_id"
+    }
+}