Bridge reference & troubleshooting
The managed browser exposes an immutable window.mojoware object to top-level documents. No interface is provided inside an iframe. Successful readiness and every privileged call require a valid native context.
Start here · Complete Markdown
Public interface
| Member | Input | Result |
|---|---|---|
ready |
Await the Promise; do not call it | Resolves when identity is ready; rejects when unavailable |
device_id |
Read after readiness | Public device ID string |
sn |
Read after readiness | Alias of device_id |
getAuthKey(audience?) |
Omit audience to use the assigned app; explicit nonempty string must match | Promise of stable mwk1 bearer string |
getAuthProof({nonce, audience}) |
Nonce 16–256 characters; matching audience up to 128 characters | Promise of {payload, signature} |
showCard({key, seconds?}) |
Allowed key; integer duration 1–300, default 300 | Promise of {screens, seconds, key} |
clearCard() |
None | Promise of {screens, seconds: 0, key: null} |
pauseAds({seconds?}) |
Integer duration 1–300, default 300 | Promise of {screens, seconds, key: "paused"} |
resumeAds() |
None | Same owned-lease clear as clearCard() |
getAuthKey is async. There is no API to change the assigned audience or select another monitor. The page never receives a management token, private signing key, or general command interface.
Troubleshooting
| Symptom | Check |
|---|---|
window.mojoware is undefined |
Ordinary browser, unsupported installation, or iframe. Test in the assigned top-level kiosk WebApp. |
ready rejects / “Native bridge unavailable” |
Current managed browser/native host, approved origin, assigned app, business eligibility, and live runtime. The bridge intentionally hides detailed denial reasons. |
| “Invalid audience” | Use getAuthKey(), or supply a nonempty string matching the app's configured audience. Do not guess wmwx for an unrelated app. |
| “Invalid proof request” | Pass an object containing a 16–256-character nonce and a valid configured audience. Your server must issue the nonce. |
| “Invalid card request” / “Invalid advertising pause” | Check key syntax and integer seconds 1–300; omit unknown option fields. |
| “Advertising control unavailable” | Check the receiving Advertising screen's selected source WebApp and allowed keys, both live monitor contexts, and business authorization. Rejection or the roughly five-second timeout does not identify one unique cause. |
| Card accepted but not visible | Check operator override priority, downloaded media, target card status, and a fresh capture. Acceptance alone is not physical playback confirmation. |
Clear accepted with screens: [] |
No lease owned by this runtime remained to clear; inspect target state rather than assuming an operator override was removed. |
| Verifier returns HTTP 200 but login must fail | Require data.ok === true. The response envelope can have status: true while the credential is invalid. |
| Auth works but cards fail | App authentication and Advertising permission are separate. Enable WebApp cards on the receiving screen. |
Integration checklist
- Test the app in its real assigned top-level HTTPS context.
- Await readiness and use
getAuthKey()unless an explicit audience is coordinated. - Verify credentials server-side and check authorized product/device association.
- Keep product bearers and verifier API keys out of browser logs and URLs.
- Configure the receiving Advertising screen, source app, allowed keys, and media.
- Exercise show, renewal, explicit clear, expiry, and operator override priority.
- Surface failures to the operator without a request storm.
- Confirm visible behavior using monitor status or a capture when it matters.
Source and version
Reviewed 16 October 2026 against server main 78bd60203b68cb00da448111fd8417602db8e6c3; the bridge/API implementation is unchanged from the previously deployed kiosk work. This is documentation verification, not a new physical-device test.
Maintainer sources:
docs/web_developer/kiosk_api.md: device identity bridge, local advertising pause, and screen cards.apps/mojoware/kiosk/pi/bridge/page.js: public methods, input validation, and timeouts.apps/mojoware/kiosk/pi/agent/agent/bridge.py: native origin, audience, assignment, and lease checks.apps/mojoware/kiosk/pi/agent/agent/advertising.py: target selection, lease ownership, return values, and card priority.apps/mojoware/kiosk/rest/identity.pyandutils/identity.py: server verification contract.- Portal
AdvertisingPanel.tsx: current operator setup labels.
The task for the original authentication/identity bridge is Maestro #7015; task access requires workspace membership.