Device registration and remote actions
Checks for admin commands sent to the user (such as forced logout or data wipe) and, when enabled, binds the user to a single device. A user logged in on another device is blocked until they resolve the conflict.
FactsheetOnboarding & setup
- Who uses it
- CadreUnit In-Charge / FMT L1
- How you get here
- Opens on top of Home on every start in release builds; also before Village selection when device binding is on.
- APIs
- 5 calls today, 11 App Service operations
- Offline
- Skipped when offline; the user continues without any check.
Screens
| Screen | What it does | Source |
|---|---|---|
| Device Registration | Status text, progress and Retry while remote actions and device binding are checked. | app/src/main/java/org/platformcommons/urvi/view/deviceregistration/DeviceRegistrationActivity.kt |
Rules
Conditions from the code, rewritten as plain decision rules.
| When | Then |
|---|---|
| The screen opens | A full-screen "Checking remote app actions..." lock shows while remote actions are fetched for today. |
| Remote actions fail or none exist | Continue to device binding if enabled, otherwise close. |
| One or more remote actions exist | Show the first action's message with only an OK button. |
| The action is ACTION_TYPE.LOGOUT or ACTION_TYPE.CLEAR_APP_DATA | If unsynced items have been attempted, zip and upload app data; report the action as EXECUTION_STATUS.COMPLETED; log out. CLEAR_APP_DATA also wipes the app. |
| The action is any other type | Mark it executed, then continue to device binding or close. |
| DEVICE_BINDING_EXTERNAL_SWITCH is not 1 | Skip device binding. |
| Binding is on and there is no internet | The screen closes and the user continues without a check. |
| The server has no session for this user | Register this device (status DEVICE_STATUS.LIVE), store the returned id and continue. |
| The server says deviceMatchStatus = true | Continue. |
| The server says deviceMatchStatus = false | Show a non-dismissable "Device Session Conflict" dialog listing the other device's brand, model and login time. |
| In the conflict dialog, setup is complete | Show Check Sync, which opens Pending Sync with a cleared back stack. |
| In the conflict dialog, REMOVE_DEVICE_BINDING_ON_NEW_DEVICE_EXTERNAL_SWITCH = 1 | Show Login Here, which removes the old binding (remark BINDING_REMOVED) and registers this device. |
| In the conflict dialog, the user taps Logout | All data is cleared. |
| An HTTP or network error occurs during binding | Show "Registration Error" with Retry / Cancel; Cancel closes the screen and the user continues. |
| The user logs out and REMOVE_DEVICE_BINDING_ON_LOGOUT_EXTERNAL_SWITCH = 1 | The binding is expired with remark USER_LOGOUT. |
API contracts
Each call opens to its use case, headers, request and response bodies, and errors.
| Today: call | Use | Replaced by |
|---|---|---|
GET /gateway/urvi-app-service/api/v1/user-device-sessions/user | Check whether this device is the one bound to the user. | |
POST /gateway/urvi-app-service/api/v1/user-device-session | Bind this device to the user. | |
PATCH /gateway/urvi-app-service/api/v1/user-device-sessions/users/{userId}?remarks= | Expire all device sessions of the user. | |
GET /gateway/urvi-app-service/api/v1/remote-app-actions/actor | Fetch pending remote commands (LOGOUT, CLEAR_APP_DATA) for this user. | |
PATCH /gateway/urvi-app-service/api/v1/remote-app-actions/{id}/execution | Report a remote command as done, optionally attaching a zip of the app databases. |
| App Service v2: operation | Use |
|---|---|
POST /auth/logout | Log out and revoke tokens |
GET /session/bootstrap | Session bootstrap after login and on cold start |
GET /config | Typed config bundle (ETag) |
POST /files | Create a file upload (resumable or single-shot) |
PATCH /files/{fileId} | Append a chunk to a resumable upload |
HEAD /files/{fileId} | Current offset of a resumable upload |
PUT /devices/{deviceId} | Register or update this device |
PUT /devices/{deviceId}/push-token | Store or rotate the FCM push token |
POST /devices/{deviceId}/binding/takeover | "Login here": move the binding to this device |
GET /devices/{deviceId}/actions | Pending remote actions for this device |
POST /devices/{deviceId}/actions/{actionId}/complete | Report a remote action as executed |
Behaviour notes
- Device id is ANDROID_ID. Registration sends device type, brand, manufacturer, model, fingerprint, MAC, IP, OS, OS version, app version and login time.
- The returned session id is stored in private prefs device_registration_prefs.
- Possible bug · unverified binding can be bypassed by going offline or pressing Cancel on the error dialog; it only blocks when online.
- Possible bug · unverified Check Sync opens Pending Sync with a cleared task, so Back exits the app and Home is not reachable until relaunch.
- Only runs in release builds when opened from Home.
Improve in the rewrite
- Enforce device binding on the server if it is a security control.
- Use a feature flag instead of build type so debug and release behave the same.
- Combine blocking issues (device conflict, automatic time, session expired) into one blocking-issues screen.