by Intelliverse X

Publish an app or game to a kiosk screen

An app can stay on a phone, run on a smart kiosk, or connect both. A phygital experience joins digital interaction to a physical place: for example, scan a kiosk QR and use your phone to control the game on its screen. Publishing sets the screen mapping; your app backend manages the game and pairing.

Instructional illustration of optional kiosk experiences and acceptance.

Instructional illustration, not a screenshot or evidence of a completed installation.

In Operator: Machine → Publish an app to this screen

  1. Prepare the app. Host the kiosk page, assets and APIs on one public HTTPS origin. Optionally supply a phone-controller URL. Keep API keys on your server.
  2. Open the owned machine in Operator X web or Operator X 3.2.6 on Android (build 47) or iPhone/iPad (signed TestFlight build 44). Under Publish an app to this screen, enter the app ID, name, display URL, optional phone-controller URL and a session duration from 30 to 900 seconds.
  3. Save a disabled draft. Review the mapping before enabling it. Older or unsupported devices can retain a draft. Publishing becomes available when a compatible ZHZN 1.0.30+ device on Android 9+ reports the player capability; capability is not proof it is online or playing content.
  4. Publish and read back. After the physical cabinet has passed acceptance, publish and reload the saved mapping to verify its URLs, enabled state and revision. If another operator changed it, reload their revision and review before trying again. A failed load/save is not a successful publication.
  5. Open on the kiosk. The storefront refreshes the mapping about every 30 seconds. Tap its experience Open control. Confirm the expected content actually renders. A saved mapping is not a playback receipt.
  6. Connect the phone. If a controller URL was supplied, scan the player QR. Your app backend must implement pairing and shared state; publication alone does not pair players, verify quests, grant rewards or record ad impressions.
  7. Return to shopping. Use the native Back to kiosk button or wait for the session to expire. The player has no vending or payment controls.
  8. Disable or recover. Disable and reload the mapping to confirm the saved state. After the next refresh it cannot be opened again; an already-running session ends on exit or timeout. If content fails to load, use native Back, disable the mapping, check the HTTPS origin and its assets, then test again. Do not interpret a save or device capability as confirmed playback.

Release availability

The cloud API and web controls are deployed. Android Operator X 3.2.6/build 47 and signed Apple 3.2.6/build 44 contain the mobile publishing controls; Apple build 44 is available to existing internal TestFlight testers. SDK PR 34 contains the server-side publisher and runnable phone-controller/kiosk-display example; it is a reviewed-preview branch awaiting required CODEOWNER approval, not a published npm release. The preview guide includes setup and API examples.

Test on a non-production cabinet before enabling a real machine. Keep API keys on your server. Mapping a game does not automatically verify quests, grant rewards or record ad impressions.

API and isolation reference

Map a hosted web app or game to an owned machine using GET / PUT /api/v1/machines/{machineNo}/experience. Both the Operator X web and Flutter cards and the Intelliverse JavaScript SDK use this endpoint. PUT takes expectedRevision, enabled, and a nullable manifest with schemaVersion: 1, appId, name, kioskUrl, optional controllerUrl, and sessionSeconds (30–900).

Use the existing operator machines:read / machines:write permissions. Ownership is checked again under the durable machine row lock. A stale revision returns 409. Storage failure returns 503 rather than claiming a save. Ordinary machine updates preserve the authoritative publication. A change of owner hides/disables the previous owner's content until the new owner publishes.

The hosted storefront reads /kiosk/api/experience using its existing machine token. It polls every 30 seconds and only offers the mapping when the device reports experiencePlayerV1. A phone-controller URL receives a locally generated QR in controllerQrBase64 (base64 PNG). This field exists only in kiosk delivery; do not send it in a publish-time manifest. QR images are cached by controller URL in a bounded cache; no external QR service or developer-page fetch is made. The storefront does not embed developer pages inside its privileged WebView and its CSP remains unchanged.

ZHZN Android 9+ requires the corresponding isolated player build. Older devices and Reyeah may save a disabled draft but cannot enable playback. playerReady represents reported capability, not online status or a playback receipt. Delivery is available on next open, never a claim of actual on-screen execution. Disabling prevents subsequent opens after refresh; existing sessions finish within their time limit.

Host the app's resources and APIs on one public HTTPS origin. The player has no native bridges, cookies, camera, microphone or vending rights. The app backend owns pairing/session/game state. No payouts, quest verification, ad impressions, or physical commands are generated by publication.