docs: clarify deviceId is created in admin dashboard, not by SDK

Author: FitzAfful

README.md

@@ -38,14 +38,14 @@ Minimum SDK: **API 29 (Android 10)**
 
 ## Device pairing
 
-Before calling `SquareScreen.init()`, a device must be paired with a SquareScreen workspace. Pairing is a two-step admin-confirm flow:
+Before calling `SquareScreen.init()`, a device must be paired with a SquareScreen workspace. There are two pairing paths — choose whichever fits your setup.
+
+### Path 1 — Register (admin confirms by OS identifier)
 
 1. An admin pre-registers the device in the SquareScreen dashboard using its Android ID.
 2. The SDK calls the register endpoint with that ID and polls for admin approval.
 3. On approval, the SDK receives a `deviceId` and `deviceToken` — store them securely and pass them to `SquareScreen.init()`.
 
-### Usage
-
 ```kotlin
 val androidId = Settings.Secure.getString(contentResolver, Settings.Secure.ANDROID_ID)
 val pairing = SquareScreenPairing.create(
@@ -71,6 +71,38 @@ pairing.pairingStatus.collect { status ->
 }
 ```
 
+### Path 2 — Activate (developer-supplied credentials)
+
+Use this when an admin has already created a device in the SquareScreen dashboard and given you its device ID. You supply that ID alongside your own device token — the token can be anything stable (IMEI, installation UUID, etc.), it is your choice.
+
+1. Admin creates the device in the SquareScreen dashboard — this generates the `deviceId`.
+2. The SDK calls the activate endpoint with that `deviceId` and your chosen `deviceToken`, then polls for admin approval exactly like Path 1.
+3. On approval, call `SquareScreen.init()` with the same `deviceId` and `deviceToken`.
+
+```kotlin
+val pairing = SquareScreenPairing.createWithActivation(
+    context = applicationContext,
+    deviceId = "AB12CD34",           // created in the SquareScreen admin dashboard
+    deviceToken = telephonyManager.imei ?: myInstallationUuid,
+    logger = if (BuildConfig.DEBUG) SquareScreenDebugLogger() else null
+)
+
+pairing.pairingStatus.collect { status ->
+    when (status) {
+        is PairingStatus.Approved -> {
+            credentialStore.save(status.deviceId, status.deviceToken)
+            initializeSdk(status.deviceId, status.deviceToken)
+        }
+        PairingStatus.Pending        -> showAwaitingApprovalUI()
+        PairingStatus.DeviceNotFound -> showDeviceNotFoundUI()
+        PairingStatus.AlreadyPaired  -> initializeFromStoredCredentials()
+        PairingStatus.Expired        -> showExpiredUI()
+        PairingStatus.InvalidToken   -> showInvalidTokenUI()
+        is PairingStatus.Error       -> showGenericError(status.throwable)
+    }
+}
+```
+
 ### How it works
 
 - On first launch (no stored token): calls `register`, persists the returned pairing token, then begins polling `pair-status`.

squarescreen-network/src/main/kotlin/io/squarescreen/network/PairingNetworkClient.kt

@@ -87,7 +87,7 @@ class PairingNetworkClient {
      * Calls `POST /screen/activate` with the developer-supplied device ID and token.
      *
      * An alternative to [register] for integrators who already hold a SquareScreen device ID
-     * (8-character alphanumeric) and supply their own device token (IMEI, UUID, etc.).
+     * (created in the admin dashboard) and supply their own device token (IMEI, UUID, etc.).
      * Returns the same [PairingRegistration] as [register] on success.
      */
     suspend fun activate(deviceId: String, deviceToken: String): SquareScreenResult<PairingRegistration> {

squarescreen-player/src/main/kotlin/io/squarescreen/player/SquareScreenPairing.kt

@@ -26,7 +26,7 @@ private const val TAG = "SquareScreenPairing"
  * Two factory methods cover the two registration paths:
  * - [create] — register path: SDK sends an OS identifier; admin confirms in the dashboard.
  * - [createWithActivation] — activate path: developer supplies a SquareScreen device ID
- *   (8-character alphanumeric) and their own device token (IMEI, UUID, etc.).
+ *   (created in the admin dashboard) and their own device token (IMEI, UUID, etc.).
  *
  * Both paths converge at the same `pair-status` polling loop and emit the same
  * [PairingStatus] states.
@@ -195,14 +195,14 @@ class SquareScreenPairing private constructor(
         }
 
         /**
-         * Activate path: the developer supplies a SquareScreen [deviceId] (8-character
-         * alphanumeric string issued by SquareScreen) and their own [deviceToken]
-         * (IMEI, UUID, or any stable identifier they choose).
+         * Activate path: the developer supplies a SquareScreen [deviceId] (created in the
+         * admin dashboard) and their own [deviceToken] (IMEI, UUID, or any stable identifier
+         * they choose).
          *
          * The flow then polls `pair-status` identically to the register path.
          *
          * @param context Application or Activity context (used for token persistence).
-         * @param deviceId 8-character alphanumeric SquareScreen device ID.
+         * @param deviceId SquareScreen device ID created in the admin dashboard.
          * @param deviceToken Developer-chosen device token (e.g. IMEI, installation UUID).
          * @param logger Optional logger for debug output. Null (default) = silent.
          */