Package web apps that run inside Studio and Player.

A modern app ships at least an index.html (the runtime), config.html (the in-Studio settings form), an app.json schema, an icon.svg, and a mandatory locales/de.json file. Banner and featured images are generated separately and required before the first upload.

my-app/
├── app.json                # required: schema, no display copy
├── index.html              # required: the app itself (1920×1080)
├── config.html             # required: config UI rendered inside Studio
├── icon.svg                # required: 512×512 brand mark
├── locales/
│   ├── de.json             # required: primary fallback locale
│   └── en.json             # optional: additional locale
├── build.sh                # ships with the skeleton: packages the folder into a ZIP
├── README.md               # ships with the skeleton: excluded from the upload ZIP
├── banner.png              # 1200×400, required for App Store visibility
├── banner.en.png           # optional: localised banner per locale
├── featured.png            # 1920×1080, required for App Store visibility
├── featured.en.png         # optional: localised featured image
├── mobile.html             # optional: QR-code controller view
└── assets/                 # optional: images, videos, fonts, audio
    ├── images/
    ├── videos/
    └── fonts/

• index.html: the runtime entry point
• config.html: the in-Studio settings form, no outer card
• app.json: technical metadata and config_schema
• icon.svg: 512×512 brand mark, no wordmark
• locales/de.json: primary fallback, contains every visible string
• banner.png (1200×400) and featured.png (1920×1080) for App Store visibility
• build.sh + README.md ship in the skeleton and are excluded from the upload ZIP
• mobile.html and assets/ are optional and slot in around the required files

app.json is the stable technical schema. Display copy stays in the locale files. Never put a label, description, or option title here.

{
  "name": "Lobby Weather",
  "slug": "lobby-weather",
  "version": "1.0.0",
  "category": "utility",
  "is_free": true,
  "price_monthly": 0,
  "config_schema": {
    "fields": [
      { "key": "title", "type": "text",   "default": "Berlin", "required": true },
      { "key": "fontSize", "type": "number", "default": 120, "min": 24, "max": 320 },
      { "key": "accent", "type": "color", "default": "#0EA5E9" },
      {
        "key": "locale",
        "type": "select",
        "default": "de",
        "options": [{ "value": "de" }, { "value": "en" }]
      }
    ]
  }
}

Supported field types

Studio merges locales/<chosen>.json over locales/de.json. Missing keys fall back to German automatically. Apps must keep de.json complete.

{
  "description": "Live weather and forecast for any city.",
  "featured": {
    "title": "Always-current weather on every screen",
    "description": "Pick a city, choose your accent colour, mount on any display."
  },
  "config_schema": {
    "fields": {
      "title":    { "label": "City",        "placeholder": "Berlin" },
      "fontSize": { "label": "Font size" },
      "accent":   { "label": "Accent colour" }
    }
  },
  "runtime": {
    "today": "Today",
    "fallback": { "title": "Weather", "subtitle": "Set a city in app settings." }
  }
}

Locale resolution chain

1. If the instance config has locale set, Studio uses that value.
2. Otherwise the Studio user's App-Store locale is used (the language they picked when browsing apps).
3. Otherwise de wins.

Studio injects window.APP_CONFIG at the <script id="app-config"></script> placeholder before your app script runs. Treat it as read-only.

interface AppConfig {
  instanceId: string       // UUID for this configured instance
  instanceName: string     // user-defined display name
  appId: string            // app UUID
  appSlug: string          // e.g. "lobby-weather"
  appName: string          // e.g. "Lobby Weather"
  version: string          // e.g. "v1.0.0"
  config: Record<string, unknown>   // values matching config_schema
  locale: {
    code: string           // resolved BCP-47 (e.g. "de", "en", "de-CH")
    strings: Record<string, unknown> // runtime.* merged with de.json runtime.*
  }
  mobileUrl?: string       // only set when the bundle ships mobile.html
}

• Always guard the read: var cfg = (window.APP_CONFIG && window.APP_CONFIG.config) || {}
• Fall back to inline defaults so local dev works without Studio
• Read runtime strings from window.APP_CONFIG.locale.strings
• Use Intl.DateTimeFormat with locale.code for dates and numbers
• Set document.body.style.opacity = "1" only after applying config to avoid flicker
• transparentBackground in config means the app should render over a transparent body
• mobileUrl is only set when the bundle ships mobile.html. Check before using

The skeleton ships in Canvas-mode. Pick the alternative if your content needs to reflow.

Studio renders config.html inside an iframe and handles the surrounding card, title, and Save button. The form communicates with Studio over postMessage.

// config.html boots inside Studio's iframe.
// Use postMessage to read and write config values.

// 1) Tell Studio we are ready to receive values
window.parent.postMessage({ type: 'CONFIG_READY' }, '*')

// 2) Studio responds with the saved config
window.addEventListener('message', (event) => {
  if (event.data?.type === 'LOAD_CONFIG') {
    applyToForm(event.data.config)
  }
})

// 3) On every input change, push the new config back
function emitChange(config) {
  window.parent.postMessage({ type: 'CONFIG_CHANGED', config }, '*')
}

URL-encoded configs are capped by the browser. For apps with long arrays (quiz questions, ticker items, big media lists) fetch the saved config directly from /api/app-instances/{instanceId}/config instead of relying on URL parameters.

async function loadConfig() {
  const urlParams = new URLSearchParams(window.location.search)
  const instanceId = urlParams.get('instanceId') || window.APP_CONFIG?.instanceId

  if (instanceId) {
    const res = await fetch(`/api/app-instances/${instanceId}/config`)
    if (res.ok) {
      const { config } = await res.json()
      return config
    }
  }

  return window.APP_CONFIG?.config ?? {}
}

Player devices include Android sticks, smart TVs, and embedded screens. The baseline target is Chrome 66 / ES2017. The Universal App Scaler is intentionally written in plain ES5/ES2017 so it runs anywhere.

Run any static file server from the bundle root and open index.html. With no APP_CONFIG present, your inline defaults take over. Design for that path from day one.

cd my-app
python3 -m http.server 8000
# index.html  → http://localhost:8000/
# config.html → http://localhost:8000/config.html

Drive the config locally with URL parameters. The app skeleton already parses them back into the same shape as APP_CONFIG.config:

http://localhost:8000/?title=Test&fontSize=200&transparentBackground=true

Studio shows two images for every app: in the catalogue grid, on the app detail page, and on instance previews. Both files live at the bundle root next to app.json.

Design rules

Producing the PNGs

• HTML mockup + Chrome screenshot: render at exact dimensions in a normal browser tab, open DevTools, toggle the device toolbar, set custom size (1200×400 or 1920×1080) at DPR 1, then Capture full size screenshot.
• Headless via Puppeteer: page.setViewport with deviceScaleFactor: 1, navigate to a local HTML file,page.screenshot.
• Design tool: Figma / Sketch / Affinity export at exact dimensions, DPR 1× (not retina-doubled).

Studio admins onboard apps into the catalogue. Self-service uploads are on the roadmap. Until they ship, every catalogue entry goes through the ScreenWay team after a short review.

# Inside your app folder. The skeleton ships build.sh
./build.sh                # build at the current version
./build.sh --bump-patch   # 1.0.0 → 1.0.1
./build.sh --bump-minor   # 1.0.0 → 1.1.0
./build.sh --bump-major   # 1.0.0 → 2.0.0

# Result: my-app-v1.0.1.zip in the current directory.
# Requires: bash, zip, jq (brew install jq / apt install jq).

# Fallback if bash + jq are not available
cd my-app
zip -r ../my-app-v1.0.0.zip . \
  -x "*.DS_Store" -x "__MACOSX/*" \
  -x "build.sh" -x "README.md" -x ".git/*"

Versioning

Upload validation

• Rejected: missing app.json, index.html, icon.svg, or locales/de.json at the ZIP root
• Rejected: invalid JSON in app.json or any locale file
• Rejected: app.json without name or slug, or with an invalid config_schema
• Rejected: duplicate slug. Upload as a new version of the existing app instead
• Rejected: not a ZIP, corrupted ZIP, or nested-folder layout
• Accepted but hidden: missing banner.png or featured.png. App uploads but stays out of the App Store grid
• Accepted with fallback: missing config.html. Studio auto-generates a basic form (visually inconsistent with the catalogue)