Apps sideloading

Sideloading ermöglicht die Installation von Mini-Programmen außerhalb der offiziellen App Store Registry. Dies ist der primäre Workflow während der Entwicklung und auch wie Benutzer Apps installieren, die direkt von Entwicklern geteilt werden.

Es gibt drei Sideloading-Methoden:

Methode	Eingabe	Am besten für
URL-Install	Manifest-URL	Gehostete Apps, Entwicklung mit lokalem Server
HTML-Upload	Einzelne `.html`-Datei	Schnelles Prototyping, Single-File-Apps
.ais-Bundle	ZIP-Datei (`.ais`-Erweiterung)	Multi-File-Apps, Offline-Verbreitung

Alle drei Methoden sind im Sideload-Bereich des Apps-Panels verfügbar.

URL-Install

Der Standardweg, ein Mini-Programm von einer gehosteten Quelle zu installieren.

Wie es funktioniert

Sie geben eine URL an, die auf eine manifest.json-Datei zeigt
Die Plattform ruft das Manifest ab und validiert es
Die Entry-HTML-Datei wird von {base_url}{entry} abgerufen
Ein Berechtigungsdialog zeigt App-Name, Beschreibung und angeforderte Berechtigungen
Bei Genehmigung werden Manifest und gecachtes HTML in IndexedDB gespeichert
Die App erscheint im installierten Apps-Grid

Schritte

Öffnen Sie das Apps-Panel (klicken Sie auf das Apps-Symbol in der linken Seitenleiste)
Scrollen Sie zum Sideload-Bereich
Fügen Sie die Manifest-URL in das Textfeld ein:
```
https://example.com/my-app/manifest.json
```
Klicken Sie auf Installieren
Überprüfen Sie die Berechtigungen und klicken Sie auf Erlauben

Entwicklung mit Localhost

Während der Entwicklung stellen Sie Ihre App lokal bereit und installieren von localhost:

cd my-app
python3 -m http.server 8080

Dann installieren von: http://localhost:8080/manifest.json

Tipp

Die meisten lokalen HTTP-Server stellen Dateien standardmäßig mit permisiven CORS-Headern bereit. Wenn Sie "Failed to fetch manifest"-Fehler erhalten, stellen Sie sicher, dass Ihr Server Access-Control-Allow-Origin: * in seinen Antworten enthält.

Eine sideloaded App aktualisieren

Die Plattform cacht Entry-HTML zur Installationszeit. Um Code-Änderungen zu übernehmen:

Deinstallieren Sie die App (X-Button auf der App-Karte klicken)
Neu installieren von der gleichen URL

Es gibt keinen automatischen Update-Mechanismus für sideloaded Apps. Registry-Apps prüfen während des Registry-Refresh-Zyklus mittels Versionsvergleich auf Updates.

HTML-Upload

Der schnellste Weg, ein Mini-Programm zu testen. Laden Sie eine einzelne HTML-Datei hoch und die Plattform erstellt automatisch ein synthetisches Manifest.

Wie es funktioniert

Sie wählen eine .html- oder .htm-Datei von Ihrem Computer
Die Plattform liest den Dateiinhalt (max. 5 MB)
Ein synthetisches Manifest wird generiert:
- name: abgeleitet vom Dateinamen (Kleinbuchstaben, Bindestriche, max. 64 Zeichen)
- version: 1.0.0
- entry: index.html
- base_url: local://
- permissions: ["storage"] (minimal)
- description: "Sideloaded from {filename}"
Ein Berechtigungsdialog wird angezeigt
Das HTML wird als Entry-Content gecacht

Schritte

Öffnen Sie das Apps-Panel
Klicken Sie im Sideload-Bereich auf App hochladen
Wählen Sie Ihre .html-Datei
Überprüfen Sie die Berechtigungen und klicken Sie auf Erlauben

Einschränkungen

Nur Einzeldatei – Externes CSS, JS und Bilder, auf die durch relative URLs verwiesen wird, werden nicht geladen, da der iframe eine null origin hat und base_url auf local:// gesetzt ist
Minimale Berechtigungen – Das synthetische Manifest gewährt nur storage. Wenn Ihre App chat:read oder andere Berechtigungen benötigt, verwenden Sie stattdessen URL-Install oder ein .ais-Bundle
5 MB Max – Dateien größer als 5 MB werden abgelehnt
Keine Manifest-Anpassung – Sie können keine benutzerdefinierte Beschreibung, kein Icon oder keine Berechtigungen setzen

Info

HTML-Upload ist für schnelles Prototyping gedacht. Für Apps, die mehrere Dateien oder spezifische Berechtigungen benötigen, verwenden Sie ein .ais-Bundle oder URL-Install.

Single-File-Apps funktionieren lassen

Um das Meiste aus HTML-Upload herauszuholen, halten Sie alles inline in Ihrem HTML:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      /* Alles CSS hier inline */
      body {
        font-family: system-ui;
        padding: 16px;
        color: #e0e0e0;
        background: #1a1a2e;
      }
    </style>
  </head>
  <body>
    <h1>Meine App</h1>
    <script>
      // Alles JavaScript hier inline
      ais.ready(function () {
        ais.ui.toast("App geladen!");
      });
    </script>
  </body>
</html>

Bilder können als Data-URIs eingebettet werden:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." />

.ais-Bundle

Ein .ais-Bundle ist ein Standard-ZIP-Archiv mit einer .ais-Dateierweiterung. Es enthält das Manifest, Entry-HTML und alle Assets. Die Plattform extrahiert das ZIP und inlineiert alle referenzierten Assets zur Installationszeit in ein einzelnes HTML-Dokument.

Wie es funktioniert

Sie laden eine .ais-Datei hoch (max. 50 MB)
Die Plattform parst das ZIP mit nativem DecompressionStream
manifest.json wird extrahiert und validiert (aus dem ZIP-Root)
Die Entry-HTML-Datei (referenziert durch entry im Manifest) wird extrahiert
Alle anderen Dateien im ZIP sind als Assets für Inlining verfügbar
Asset-Inlining transformiert das HTML:
- <link rel="stylesheet" href="style.css"> wird zu <style>{CSS-Inhalt}</style>
- <script src="app.js"></script> wird zu <script>{JS-Inhalt}</script>
- <img src="icon.png"> wird zu <img src="data:image/png;base64,{base64}">
- url(bg.png) in inline-Styles wird zu url(data:image/png;base64,...)
Der Berechtigungsdialog zeigt die Berechtigungen des Manifests
Das inlineierte HTML wird in IndexedDB gecacht

Bundle-Struktur

my-app.ais (ZIP-Archiv)
  |-- manifest.json      (erforderlich, im Root)
  |-- index.html         (erforderlich, referenziert durch Manifest "entry")
  |-- style.css          (optional, inlineiert in <style>)
  |-- app.js             (optional, inlineiert in <script>)
  |-- icon.png           (optional, inlineiert als Data-URI)
  |-- images/
  |     |-- logo.svg     (optional, inlineiert als Data-URI)
  |-- fonts/
        |-- custom.woff2 (optional, inlineiert als Data-URI)

Ein Bundle erstellen

# In Ihr App-Verzeichnis navigieren
cd my-app

# Dateien überprüfen
ls
# manifest.json  index.html  style.css  app.js  icon.png

# Bundle erstellen
zip -r ../my-app.ais manifest.json index.html style.css app.js icon.png

Oder zippen Sie das gesamte Verzeichnis:

cd my-app
zip -r ../my-app.ais .

Vorsicht

Die manifest.json muss im Root des ZIP sein, nicht in einem Unterverzeichnis. Wenn Ihr ZIP eine Struktur wie my-app/manifest.json hat, wird die Plattform sie nicht finden.

Was inlineiert wird

Der Asset-Inliner verarbeitet das Entry-HTML und ersetzt relative Referenzen durch inline-Inhalte:

Muster	Ersetzung
`<link rel="stylesheet" href="X">`	`<style>{Inhalt von X}</style>`
`<script src="X"></script>`	`<script>{Inhalt von X}</script>`
`<img src="X">`	`<img src="data:{mime};base64,{daten}">`
`<audio src="X">`	`<audio src="data:{mime};base64,{daten}">`
`<video src="X">`	`<video src="data:{mime};base64,{daten}">`
`<source src="X">`	`<source src="data:{mime};base64,{daten}">`
`url(X)` in inline-Styles	`url(data:{mime};base64,{daten})`

Referenzen, die mit data:, http://, https:// oder // beginnen, bleiben unverändert – nur relative Pfade werden inlineiert.

Unterstützte MIME-Types

Die Plattform erkennt MIME-Types anhand von Dateierweiterungen:

Erweiterung	MIME-Type
`.css`	`text/css`
`.js`, `.mjs`	`text/javascript`
`.json`	`application/json`
`.png`	`image/png`
`.jpg`, `.jpeg`	`image/jpeg`
`.gif`	`image/gif`
`.svg`	`image/svg+xml`
`.webp`	`image/webp`
`.ico`	`image/x-icon`
`.woff`	`font/woff`
`.woff2`	`font/woff2`
`.ttf`	`font/ttf`
`.mp3`	`audio/mpeg`
`.mp4`	`video/mp4`
`.webm`	`video/webm`
`.ogg`	`audio/ogg`
`.wav`	`audio/wav`

Beispiel: Multi-File-App-Bundle

manifest.json:

{
  "name": "dashboard",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "Dashboard",
  "description": "Chat-Analytics-Dashboard",
  "entry": "index.html",
  "base_url": "local://",
  "permissions": ["storage", "chat:read", "auth:read", "ui:toast"]
}

index.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <h1>Dashboard</h1>
    <img src="logo.svg" alt="Logo" width="64" />
    <div id="stats"></div>
    <script src="app.js"></script>
  </body>
</html>

style.css:

body {
  font-family: system-ui;
  padding: 16px;
  color: #e0e0e0;
  background: #1a1a2e;
}
h1 {
  font-size: 22px;
}
#stats {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 12px;
}

app.js:

ais.ready(async function () {
  var history = await ais.chat.getHistory(100);
  document.getElementById("stats").textContent =
    history.length + " Nachrichten";
});

Nach der Bundle-Installation produziert die Plattform ein einzelnes inlineiertes HTML:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      body {
        font-family: system-ui;
        padding: 16px;
        color: #e0e0e0;
        background: #1a1a2e;
      }
      h1 {
        font-size: 22px;
      }
      #stats {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: 12px;
      }
    </style>
  </head>
  <body>
    <h1>Dashboard</h1>
    <img src="data:image/svg+xml;base64,..." alt="Logo" width="64" />
    <div id="stats"></div>
    <script>
      ais.ready(async function () {
        var history = await ais.chat.getHistory(100);
        document.getElementById("stats").textContent =
          history.length + " Nachrichten";
      });
    </script>
  </body>
</html>

Dateigrößen-Limits

Methode	Max. Größe
HTML-Upload	5 MB
.ais-Bundle	50 MB
URL-Install	Kein festes Limit (durch Browser-Speicher begrenzt)

Warnung

Große Bundles mit vielen eingebetteten Bildern oder Mediendateien können zu einem sehr großen gecachten HTML-String in IndexedDB führen. Halten Sie Bundles schlank – komprimieren Sie Bilder vor dem Einfügen und erwägen Sie externe URLs für große Media-Assets.

Sicherheit

Sideloaded Apps erhalten die exakt gleiche Sandbox wie Registry-Apps:

sandbox="allow-scripts allow-forms" (null origin)
Kein Zugriff auf Eltern-DOM, localStorage oder Cookies
Kommunikation ausschließlich über die window.ais postMessage-Bridge
Berechtigungen werden von der Host-Plattform durchgesetzt (nicht vom iframe)

Der einzige Unterschied zu Registry-Apps ist das Fehlen eines Vertrauens-Badges (Community, AI Verified oder Verified) im Apps-Grid. Sideloaded Apps haben kein Badge.

Info

Sideloading ist die "Direct Install"-Stufe des Marktplatz-Vertriebsmodells. Es ist das native Vertriebsmechanismus des Webs – jede App von jeder URL installieren, mit der Sandbox als Basissicherheit.

Die Sideload-UI

Der Sideload-Bereich im Apps-Panel bietet:

URL-Eingabefeld – Manifest-URL einfügen und Installieren klicken
"oder"-Trenner
App hochladen-Button – Öffnet einen Datei-Picker, der .html, .htm, .ais und .zip-Dateien akzeptiert
Hilfetext – "Akzeptiert .html Single-File-Apps oder .ais-Bundles (ZIP mit manifest.json)"

Alle drei Methoden lösen den Standard-Berechtigungsdialog aus, bevor die Installation abgeschlossen wird. Installierte Apps erscheinen oben im Installiert-Bereich mit Öffnen- und Deinstallieren-Buttons.

URL-Install​

Wie es funktioniert​

Schritte​

Entwicklung mit Localhost​

Eine sideloaded App aktualisieren​

HTML-Upload​

Wie es funktioniert​

Schritte​

Einschränkungen​

Single-File-Apps funktionieren lassen​

.ais-Bundle​

Wie es funktioniert​

Bundle-Struktur​

Ein Bundle erstellen​

Was inlineiert wird​

Unterstützte MIME-Types​

Beispiel: Multi-File-App-Bundle​

Dateigrößen-Limits​

Sicherheit​

Die Sideload-UI​

URL-Install

Wie es funktioniert

Schritte

Entwicklung mit Localhost

Eine sideloaded App aktualisieren

HTML-Upload

Wie es funktioniert

Schritte

Einschränkungen

Single-File-Apps funktionieren lassen

.ais-Bundle

Wie es funktioniert

Bundle-Struktur

Ein Bundle erstellen

Was inlineiert wird

Unterstützte MIME-Types

Beispiel: Multi-File-App-Bundle

Dateigrößen-Limits

Sicherheit

Die Sideload-UI