Web-Apps paketieren, die in Studio und Player laufen.

Eine moderne App liefert mindestens index.html (die Runtime), config.html (das in-Studio-Settings-Formular), ein app.json-Schema, ein icon.svg und ein Pflicht-locales/de.json. Banner- und Featured-Bilder werden separat erzeugt und sind vor dem ersten Upload erforderlich.

my-app/
├── app.json                # Pflicht: Schema, kein Anzeige-Text
├── index.html              # Pflicht: die App selbst (1920×1080)
├── config.html             # Pflicht: Konfigurations-UI im Studio-iFrame
├── icon.svg                # Pflicht: 512×512 Brand-Symbol
├── locales/
│   ├── de.json             # Pflicht: primärer Fallback-Locale
│   └── en.json             # Optional: weiterer Locale
├── build.sh                # im Skeleton enthalten: paketiert den Ordner
├── README.md               # im Skeleton enthalten: wird aus dem Upload-ZIP exkludiert
├── banner.png              # 1200×400, für App-Store-Sichtbarkeit erforderlich
├── banner.en.png           # Optional: lokalisierter Banner pro Locale
├── featured.png            # 1920×1080, für App-Store-Sichtbarkeit erforderlich
├── featured.en.png         # Optional: lokalisiertes Featured-Bild
├── mobile.html             # Optional: QR-Code-Controller-View
└── assets/                 # Optional: Bilder, Videos, Fonts, Audio
    ├── images/
    ├── videos/
    └── fonts/

• index.html: Runtime-Einstieg
• config.html: in-Studio-Settings-Formular, kein äußerer Card
• app.json: technische Metadaten und config_schema
• icon.svg: 512×512 Brand-Symbol, ohne Wortmarke
• locales/de.json: primärer Fallback, enthält jeden sichtbaren String
• banner.png (1200×400) und featured.png (1920×1080) für App-Store-Sichtbarkeit
• build.sh + README.md liegen im Skeleton und werden aus dem Upload-ZIP exkludiert
• mobile.html und assets/ sind optional und fügen sich um die Pflichtdateien

app.json ist das stabile technische Schema. Anzeige-Texte bleiben in den Locale-Files. Niemals Label, Beschreibung oder Option-Titel hier einsetzen.

{
  "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" }]
      }
    ]
  }
}

Unterstützte Field-Typen

Studio merged locales/<chosen>.json über locales/de.json. Fehlende Keys fallen automatisch auf Deutsch zurück. Apps müssen de.json vollständig halten.

{
  "description": "Live-Wetter und Vorhersage für jede Stadt.",
  "featured": {
    "title": "Immer aktuelles Wetter auf jedem Screen",
    "description": "Stadt wählen, Akzentfarbe setzen, auf jedem Display einsetzen."
  },
  "config_schema": {
    "fields": {
      "title":    { "label": "Stadt",       "placeholder": "Berlin" },
      "fontSize": { "label": "Schriftgröße" },
      "accent":   { "label": "Akzentfarbe" }
    }
  },
  "runtime": {
    "today": "Heute",
    "fallback": { "title": "Wetter", "subtitle": "Stadt in den App-Einstellungen festlegen." }
  }
}

Locale-Resolution-Chain

1. Hat die Instance-Config locale gesetzt, nutzt Studio diesen Wert.
2. Sonst greift der App-Store-Locale des Studio-Users (die Sprache, in der er die Apps durchstöbert hat).
3. Sonst gewinnt de.

Studio injiziert window.APP_CONFIG am <script id="app-config"></script> -Platzhalter, bevor Ihr App-Script läuft. Read-only behandeln.

interface AppConfig {
  instanceId: string       // UUID dieser konfigurierten Instanz
  instanceName: string     // benutzerdefinierter Anzeigename
  appId: string            // App-UUID
  appSlug: string          // z. B. "lobby-weather"
  appName: string          // z. B. "Lobby Weather"
  version: string          // z. B. "v1.0.0"
  config: Record<string, unknown>   // Werte gemäß config_schema
  locale: {
    code: string           // aufgelöster BCP-47 (z. B. "de", "en", "de-CH")
    strings: Record<string, unknown> // runtime.* gemerged mit de.json runtime.*
  }
  mobileUrl?: string       // nur gesetzt, wenn das Bundle mobile.html mitliefert
}

• Immer defensiv lesen: var cfg = (window.APP_CONFIG && window.APP_CONFIG.config) || {}
• Auf Inline-Defaults zurückfallen, damit lokale Entwicklung ohne Studio funktioniert
• Runtime-Strings aus window.APP_CONFIG.locale.strings lesen
• Intl.DateTimeFormat mit locale.code für Datumsangaben und Zahlen nutzen
• document.body.style.opacity = "1" erst nach Anwenden der Config setzen, um Flicker zu vermeiden
• transparentBackground in der Config bedeutet: App rendert über transparentem Body
• mobileUrl ist nur gesetzt, wenn das Bundle mobile.html mitliefert. Vorher prüfen

Das Skeleton liefert standardmäßig im Canvas-mode aus. Die Alternative ist sinnvoll, wenn Inhalte reflowen sollen.

Studio rendert config.html in einem iFrame und übernimmt den umgebenden Card, den Titel und den Speichern-Button. Das Formular kommuniziert per postMessage mit Studio.

// config.html bootet im Studio-iFrame.
// postMessage zum Lesen und Schreiben der Config-Werte.

// 1) Studio mitteilen, dass wir bereit sind
window.parent.postMessage({ type: 'CONFIG_READY' }, '*')

// 2) Studio antwortet mit der gespeicherten Config
window.addEventListener('message', (event) => {
  if (event.data?.type === 'LOAD_CONFIG') {
    applyToForm(event.data.config)
  }
})

// 3) Bei jeder Änderung Config zurückschicken
function emitChange(config) {
  window.parent.postMessage({ type: 'CONFIG_CHANGED', config }, '*')
}

URL-kodierte Configs sind durch den Browser begrenzt. Bei Apps mit langen Arrays (Quiz-Fragen, Ticker-Items, große Medien-Listen) holen Sie die gespeicherte Config direkt von /api/app-instances/{instanceId}/config statt sich auf URL-Parameter zu verlassen.

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-Geräte umfassen Android-Sticks, Smart-TVs und Embedded-Screens. Baseline: Chrome 66 / ES2017. Der Universal App Scaler ist bewusst in schlichtem ES5/ES2017 geschrieben, damit er überall läuft.

Beliebigen statischen File-Server vom Bundle-Root starten und index.html öffnen. Ohne APP_CONFIG greifen Ihre Inline-Defaults. Von Tag eins für diesen Pfad designen.

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

Lokal die Config per URL-Parameter steuern. Das Skeleton parst sie zurück in dieselbe Shape wie APP_CONFIG.config:

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

Studio zeigt für jede App zwei Bilder: im Katalog-Grid, auf der App-Detailseite und in der Instance-Vorschau. Beide Dateien liegen im Bundle-Root neben app.json.

Design-Regeln

PNGs erzeugen

• HTML-Mockup + Chrome-Screenshot: in einem normalen Browser-Tab in exakter Größe rendern, DevTools öffnen, Device-Toolbar aktivieren, Custom-Size (1200×400 oder 1920×1080) bei DPR 1 setzen, dann Capture full size screenshot.
• Headless via Puppeteer: page.setViewport mit deviceScaleFactor: 1, lokale HTML-Datei laden,page.screenshot.
• Design-Tool: Figma / Sketch / Affinity in exakter Größe als PNG exportieren, DPR 1× (nicht retina-doppelt).

Studio-Admins nehmen Apps in den Katalog auf. Self-Service-Uploads sind in Vorbereitung. Bis dahin geht jeder Katalog-Eintrag über das ScreenWay-Team mit kurzer Prüfung.

# Im App-Ordner. Das Skeleton liefert build.sh mit
./build.sh                # build mit aktueller Version aus app.json
./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

# Ergebnis: my-app-v1.0.1.zip im aktuellen Verzeichnis.
# Benötigt: bash, zip, jq (brew install jq / apt install jq).

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

Versionierung

Upload-Validierung

• Abgelehnt: fehlende app.json, index.html, icon.svg oder locales/de.json im ZIP-Root
• Abgelehnt: ungültiges JSON in app.json oder einem Locale-File
• Abgelehnt: app.json ohne name oder slug oder mit ungültigem config_schema
• Abgelehnt: doppelter slug. Stattdessen als neue Version der bestehenden App hochladen
• Abgelehnt: kein ZIP, kaputtes ZIP oder verschachtelter Ordner
• Akzeptiert aber versteckt: fehlende banner.png oder featured.png. App wird hochgeladen, bleibt aber aus dem App-Store-Grid raus
• Akzeptiert mit Fallback: fehlende config.html. Studio generiert ein einfaches Formular (visuell inkonsistent zum Katalog)