Appearance
Mobile Access
Service path: /json/commerce
Mobile Access turns the phone into a door credential. The patron app lists the doors ("locations") the user can open, and activating one returns either a PDF417 barcode, a temporary code, or both, plus a validity countdown.
NOTE
Both methods are flagged useSessionId = true and useInstitutionId = false, so only sessionId is injected.
List locations
Returns the doors available to the current user, nearest first.
plaintext
POST /json/commerce
method: getMobileLocations| Field | Type | Required | Description |
|---|---|---|---|
filters | string[] | YES | ["Normal", "TempCode", "Attendance"] in the app. |
latitude | number | null | YES | Device latitude. |
longitude | number | null | YES | Device longitude. |
accuracy | number | null | NO | Location accuracy in metres. |
sessionId | string | YES | Injected. |
json
{
"method": "getMobileLocations",
"params": {
"filters": ["Normal", "TempCode", "Attendance"],
"latitude": 43.073052,
"longitude": -89.40123,
"accuracy": 12,
"sessionId": "{SESSION_ID}"
}
}The filter values map to the three kinds of access point:
| Filter | Meaning |
|---|---|
Normal | Standard door readers. |
TempCode | Readers that issue a short-lived numeric code. |
Attendance | Attendance / time-clock readers. |
Response is an array of locations. The app reads locationId, name, distance, and score:
json
{
"response": [
{
"locationId": "{LOCATION_ID}",
"name": "Student Union — East Entrance",
"type": "Normal",
"distance": 84.2,
"color": "#0099cc",
"score": 5
},
{
"locationId": "{LOCATION_ID}",
"name": "Library — Loading Dock",
"type": "TempCode",
"distance": 220.7,
"color": "#0099cc",
"score": 1
}
],
"exception": null
}| Field | Meaning |
|---|---|
locationId | Door id; used to activate it and to store favorites. |
name | Display name. |
type | One of the three filter values. |
distance | Distance from the supplied coordinates (metres; converted to miles in the UI). |
color | Present in the payload, but the app does not read it — the list is coloured by CSS. |
score | Server-side relevance/priority ranking. |
Sorting and favorites
The client sorts the response itself:
- Favorites first.
- Then by descending
score.
Favorites are not a server list. The app stores an array of locationId strings in the user setting mobileaccess_favorites (via /json/user retrieveSetting / saveSetting). Toggling a star rewrites that setting; no rewards/access endpoint is called.
Activate a location
Opens a door, or issues a code/barcode for it.
plaintext
POST /json/commerce
method: activateMobileLocation| Field | Type | Required | Description |
|---|---|---|---|
locationId | string | YES | Door id from getMobileLocations. |
tranDate | string | YES | ISO-8601 timestamp (the app sends new Date().toISOString()). |
latitude | number | null | NO | Device latitude (null if unavailable). |
longitude | number | null | NO | Device longitude. |
accuracy | number | null | NO | Accuracy in metres. |
altitude | number | null | NO | Altitude. |
altitudeAccuracy | number | null | NO | Altitude accuracy. |
speed | number | null | NO | Device speed. |
heading | number | null | NO | Device heading. |
sourceInfo | string | null | NO | Free-form source tag. The app sends null. |
sessionId | string | YES | Injected. |
json
{
"method": "activateMobileLocation",
"params": {
"locationId": "{LOCATION_ID}",
"tranDate": "2026-11-19T14:03:22.145Z",
"latitude": 43.073052,
"longitude": -89.40123,
"accuracy": 12,
"altitude": null,
"altitudeAccuracy": null,
"speed": null,
"heading": null,
"sourceInfo": null,
"sessionId": "{SESSION_ID}"
}
}Response
json
{
"response": {
"message": "Door unlocked",
"responseCode": "00",
"showBarCode": 1,
"showTempCode": 1,
"validityTime": 30,
"issuedCode": "0123456789012345678901234567890123456789"
},
"exception": null
}| Field | Meaning |
|---|---|
message | Human-readable result shown in the dialog. |
responseCode | "00" = success. Any other value is treated as an error. |
showBarCode | 1 = render a PDF417 barcode from issuedCode. |
showTempCode | 1 = display issuedCode as a numeric code. |
validityTime | Seconds the code is valid; drives the countdown timer. |
issuedCode | The payload: barcode data and/or the temporary code. |
Result handling
The app decides what to display from the two show* flags:
showBarCode | showTempCode | UI |
|---|---|---|
1 | 1 | Barcode dialog (PDF417, includetext: false) plus the countdown. |
| any | 1 | Numeric code dialog plus the countdown. |
0 | 0 | Success dialog with message only. |
The barcode is rendered client-side as PDF417 from issuedCode. The countdown uses validityTime; when it expires the dialog closes. If barcode rendering throws, the app shows the error.barcode_render toast.
responseCode is compared as a string, so "00" succeeds and "0" does not.
Error handling
| Condition | Behavior |
|---|---|
responseCode !== "00" | Error dialog titled with the error content string; message is shown verbatim. |
message contains enable location services | Treated as a location-services failure (the user is prompted to enable GPS). |
| Transport/exception error | Toast mobile-access toast_activate-response-error. |
Flow summary
- Request location permission.
getMobileLocationswith the device coordinates.- User picks a door (favorites pinned to the top).
activateMobileLocationwith the current coordinates and timestamp.- If
responseCode === "00", show the barcode/code dialog forvalidityTimeseconds.
The disclosure screen shown before the first activation is content category patron-ui.location_disclosure_screen.