Skip to main content

Submit an external game

A game administrator uploads your bundle directly in the games maestro. There is no vendor catalogue and no per-account subscription step.

Before you start
  • Permission: Games (Pages.Gamification.Games), the permission that protects bundle upload.
  • Edition: see External games for availability.

1. Create the game​

Go to Gamification › Games and click Create New. Enter a Name, choose External as the game type and save. Then open the game with Edit.

2. Upload the bundle​

In the External HTML5 game panel, use Upload bundle (.zip) under Game bundle. You can also pick a ready-made runner under Ready-made runners, or paste an https:// bundle URL. The labels in this panel appear in English.

Bundle rules:

  • The zip must contain an index.html: it is the iframe entry point.
  • Allowed extensions: .html .htm .js .mjs .css .png .jpg .jpeg .webp .svg .gif .wasm .ogg .mp3 .json .ttf .woff .woff2 .txt.
  • Maximum compressed size: 25 MB by default.
  • The uncompressed size is also limited, and a zip can contain at most 5,000 entries.
  • Maximum path depth: 8 segments. Paths cannot contain ...
  • Each account has a total storage quota for its bundles.

If validation fails, the upload is rejected and the game is left as it was. Fix the zip and try again. On success the panel shows the bundle address (/cdn/games/tenant-<id>/…).

3. Set the signal schema​

Under Signal schema (advanced), enter a JSON Schema that the signal from your bundle must match. If you leave it blank, the default is {"score":"number"}.

4. Choose how the outcome is decided​

Minimum score for prize (skill gate) defaults to 0: the score is informational and the prize comes from the game's probability table. Use a value above 0 only with bundles you trust and for low-value prizes. Your bundle must then sign the score. See contract v1, section 8.

5. Add prizes and publish​

Add the Prizes and their probabilities, set the game's status to active and pick the game in a campaign. The steps are in External games.

Update a bundle​

Upload a new zip on the same game. The bundle address is replaced and the old folder is cleaned up automatically after about a day. Players with the old version already open can finish their play.

Common errors​

SymptomCauseWhat to do
Disallowed file extensionThe zip contains a file type outside the allow-list.Remove or rename the file.
Upload rejected for sizeThe zip, its uncompressed content or the number of entries exceeds the limit.Compress assets or remove unused files.
Path errorA zip entry contains ../, an absolute path or is too deep.Rebuild the zip from the project root.
Game shows an error instead of the iframeThe game has no bundle, or the bundle URL is not https:// or not on an allowed host.Upload the zip again or fix the URL.
429 when starting a playThe member already played 10 times this hour, or has a play in progress.Wait and try again.
400 when completingThe signal does not match the signal schema or exceeds 16 KB.Compare your signal with the schema.