---
title: "Bridge reference & troubleshooting"
description: "Public window.mojoware methods, return values, error handling, and integration checks."
canonical: "https://mojoware.net/docs/kiosk/bridge-reference/"
---

# 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](/docs/kiosk/home/) · [Complete Markdown](/docs/kiosk/llms-full.txt)

## 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.py` and `utils/identity.py`: server verification contract.
- Portal `AdvertisingPanel.tsx`: current operator setup labels.

The task for the original authentication/identity bridge is [Maestro #7015](https://maestromojo.com/app/#/board/21?item=7015); task access requires workspace membership.