Campaigns

Campaign data model

Groups and waves

Menu items

GameBus app menu items define what a participant sees in the app menu. They can link to built-in GameBus routes, external URLs, account controls, compact embedded menu widgets, or full-page embedded experiences.

Menu items are loaded for the authenticated participant when all access constraints match:

• The item is linked to a group through AppMenuItemForGroup, and the user has any membership role in that group.
• The item is linked to a wave through AppMenuItemForWave, and that wave is active at the current time.

Ordering is resolved per slot. Items are sorted by slot, then by order, then by id. A missing order sorts last inside the slot.

Input collections are resolved in the browser using the same request semantics as embedded task widgets. Every linked InputCollection is fetched request-by-request, keyed as collection.key -> inputRequest.key -> response value. JSON responses are parsed as JSON; other responses are returned as text. Failed or empty requests are ignored unless their doFailOnError or doFailOnEmpty flag requires a hard failure.

Menu item fields route, url, title, and subtitle can contain expression tokens such as $template.name or interpolation expressions such as $collectionReference.endpointReference.missions.[*].name. Expressions are resolved against the resolved input collections. Dot segments select object properties, [3] selects a single array item, and [*] expands all array items.

LIST_OF_ITEMS uses iterable as a plain path expression, not an interpolated string. Use values like collectionReference.endpointReference.missions[*], collectionReference.endpointReference.missions[3].tasks, or key1.key2[3].key3. Each resolved row is exposed as row, so row fields can use expressions like $row.template.name. item is also available as a backwards-compatible alias for row.

CUSTOM_EMBED menu items render their configured url directly inside the side menu as a compact iframe. The iframe sends IFRAME_READY, can include a measured height, receives INPUT_COLLECTIONS, and can send NAVIGATE, ACTIVITY, or SILENT_ACTIVITY messages back to GameBus. See Custom menu items for the external iframe protocol.

Menu items of any type that are associated with an AppEmbedPage route to /embed/[appEmbedPageId]. The embed page validates the same group/wave access as the side menu, renders the external URL in an iframe, and posts MENU_ITEM and INPUT_COLLECTIONS messages after the iframe sends IFRAME_READY. EMBED_FULLSCREEN omits the standard app header; EMBED_WITH_HEADER keeps it. See Custom pages for the external iframe protocol.

ACCOUNT menu items render the authenticated user's account dropdown. They use the same group, wave, slot, and ordering rules as other menu items, so the account dropdown only appears when an ACCOUNT item is resolved for the participant.

Example input collection data available to menu item expressions and embedded iframes:

participant:
  current:
    name: Ada Lovelace
    team: Analytical Engines
progress:
  summary:
    completedTasks: 7
    totalTasks: 10

Example fields using those values:

title: $participant.current.name
subtitle: $progress.summary.completedTasks completed tasks
url: https://widgets.example.org/progress?team=$participant.current.team