WebApps bauen & API-Schlüssel sicher einbinden

1 · Überblick

Eine WebApp ist eine ganz normale Website aus HTML, CSS und JavaScript. Du lädst sie als ZIP im Studio hoch, und Besucher starten sie direkt im Browser – ohne Download, ohne Installation. Der Store liefert deine Dateien in einer isolierten Sandbox aus: Deine App läuft abgeschirmt von den anderen Inhalten und hat keinen Zugriff auf Konten, Cookies oder die Verwaltung des Stores.

Viele kleine Tools brauchen eine externe API (KI, Karten, Wetter …), die einen Schlüssel verlangt. Würdest du den Schlüssel direkt in deine HTML/JS schreiben, könnte ihn jeder im Browser-Quelltext lesen und missbrauchen. Dagegen gibt es den Schlüssel-Proxy: Du hinterlegst den Schlüssel einmal im Studio, und deine WebApp ruft die API nur über einen kurzen Pfad wie /api/… auf. Der Store setzt den echten Schlüssel erst auf dem Server ein und leitet die Antwort zurück. Der Browser – und damit auch deine App – sieht den Schlüssel nie.

2 · Schnellstart in fünf Schritten

1. WebApp bauen – eine index.html plus CSS/JS, die ohne Server auskommt (statische Dateien).
2. Als ZIP packen – die Dateien in ein ZIP legen. Die Startseite muss in der ZIP erreichbar sein (z. B. index.html ganz oben). Tipp: Hast du versehentlich den ganzen Ordner gepackt (meine-webapp/index.html), erkennt der Store das und legt die Dateien automatisch eine Ebene höher.
3. Im Studio eine App anlegen – Studio → Neue App, beim Angebot „WebApp (Sandbox)" aktivieren (zusammen mit „Android (APK)", wenn du beides anbieten willst), ZIP hochladen, Startseite eintragen, Beschreibungen ausfüllen.
4. Veröffentlichen – die Version geht erst nach der Freigabe durch den Betreiber in den Store; danach startet sie über „WebApp öffnen" (Einreichung und Prüfung: Abschnitt 12).
5. (Optional) API-Schlüssel hinterlegen – im Abschnitt API-Schlüssel den Schlüssel speichern und in der App über den Präfix-Pfad aufrufen (Abschnitt 5 und 6).

3 · Projekt & ZIP richtig bauen

Deine WebApp ist ein Ordner mit statischen Dateien. Ein typischer Aufbau:

meine-webapp/
├─ index.html      ← Startseite (die du im Studio einträgst)
├─ app.js          ← deine Logik
├─ style.css       ← dein Design
└─ img/logo.png    ← Bilder, Schriften, …

Zum Veröffentlichen packst du den Inhalt in ein ZIP – die Dateien sollten direkt im ZIP liegen. Ist stattdessen genau ein Ordner im ZIP (z. B. meine-webapp/index.html), entfernt der Store diesen Ordner beim Auspacken automatisch, damit index.html und alle relativen Verweise funktionieren. Bei mehreren Ordnern im ZIP trägst du den Unterordner als Startseite ein, z. B. build/index.html.

Eigene Dateien: relative Pfade benutzen

Deine App läuft im Store nicht auf der Wurzel /, sondern unter einem Unterpfad wie /web/<sitzung>/<app>/index.html. Deshalb verweist du innerhalb deiner App relativ auf eigene Dateien – ohne führenden Slash:

<!-- richtig: relativ zur index.html -->
<link rel="stylesheet" href="style.css">
<script src="app.js"></script>
<img src="img/logo.png" alt="">

<!-- falsch: /app.js würde im Store ins Leere führen -->
<script src="/app.js"></script>

Erlaubte Dateitypen

Der Store entpackt nur bekannte Web-Typen und lehnt alles andere ab (Schutz vor Server-Skripten). Erlaubt sind u. a.: html, css, js, mjs, json, svg, png, jpg, webp, gif, avif, ico, woff, woff2, ttf, otf, mp3, wav, ogg, mp4, webm, wasm, glb, gltf, txt, csv, xml, vtt. Keine .php, .py, .exe o. Ä.

Grenzen für das Paket

• ZIP insgesamt: maximal 128 MB.
• Einzelne Datei im Paket: maximal 128 MB, höchstens 1200 Dateien.
• Beim Entpacken wird geprüft: keine Pfade, die nach oben zeigen (..), keine Verknüpfungen, keine gepackten „Zip-Bombs".

4 · Die Sandbox: was geht und was nicht

Deine App läuft in einem Browser-iFrame ohne gleiche Herkunft. Das ist gut für Sicherheit, hat aber Folgen, die du kennen solltest:

5 · API-Schlüssel im Studio anlegen

Öffne deine WebApp im Studio. Ganz unten (bzw. im Abschnitt API-Schlüssel) klickst du auf „＋ Schlüssel hinzufügen". (Der Abschnitt erscheint erst, nachdem die App mindestens als Entwurf gespeichert ist.) Du füllst folgende Felder aus:

Nach dem Speichern zeigt die Karte nur noch „Schlüssel gesetzt" – der Wert selbst wird nie wieder im Browser angezeigt und ist auch nicht im Code deiner App.

6 · Den Schlüssel in deiner WebApp nutzen

Deine App ruft die API jetzt über dein Präfix auf – mit führendem Slash und relativ zur Domain, nicht mit der echten Anbieter-URL. Der Store erkennt den Präfix und leitet automatisch weiter.

Wenn dein Präfix /api und die Grundadresse https://api.openai.com ist, gilt diese Übersetzung:

Dein Code                 →   tatsächlicher Aufruf durch den Store
fetch('/api/v1/chat')     →   https://api.openai.com/v1/chat   (+ Schlüssel)

Beispiel: POST mit JSON

async function frageKI(text) {
  const antwort = await fetch('/api/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },   // KEIN Authorization hier!
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: text }]
    })
  });
  if (!antwort.ok) throw new Error('API-Fehler ' + antwort.status);
  const daten = await antwort.json();
  return daten.choices[0].message.content;
}

Beispiel: GET mit Query (z. B. Karten/Wetter)

// Präfix /maps, Grundadresse https://maps.googleapis.com, Modus Query, Name "key"
const r = await fetch('/maps/geocode/json?address=Berlin');
const daten = await r.json();
// Der Store hängt intern &key=DEIN_GEHEIMER_SCHLUESSEL an.

Mit XMLHttpRequest (statt fetch)

Auch ältere XMLHttpRequest-Aufrufe werden automatisch umgeleitet, sobald der Pfad mit deinem Präfix beginnt:

const xhr = new XMLHttpRequest();
xhr.open('GET', '/api/status');   // wird über den Proxy geleitet
xhr.onload = () => console.log(JSON.parse(xhr.responseText));
xhr.send();

7 · App-Daten & Credits

Deine WebApp braucht einen Ort für Nutzerdaten – Chatverläufe, Einstellungen, Profile – und vielleicht ein Guthabensystem? Beides liefert der Store direkt mit: die App-Daten-API speichert pro Nutzer JSON-Dokumente in der Store-Datenbank (klein, verschlüsselt verwaltet, nicht auf dem öffentlichen Cloud-Stick), und das Credit-System verwaltet monatliche Guthaben mit einlösbaren Codes. Alles ohne eigenen Server.

Endpunkte (Bearer = Geräte-Token agd_…)

Geräte-Tokens sind an eine App und einen Nutzer gebunden – das Token einer anderen App wird abgelehnt, und kein Token sieht Daten eines anderen Nutzers. Für deinen eigenen Backend-Prozess gibt es zusätzlich Daten-Schlüssel (agw_…, im Studio erstellbar): gleiche Endpunkte, aber mit ?user=NAME und Zugriff auf alle Kontos deiner App.

Credits & Codes (Studio)

• Monatliches Guthaben (Standard 200) setzt sich automatisch zurück – keine Wartung.
• Codes: Im Studio unter „App-Daten & Credits" beliebig viele anlegen (Code-Text, Credits, optional max. Einlösungen; aktivieren/deaktivieren/löschen). Deine Nutzer lösen sie selbst in der App ein.
• Bonus geben: Pro Nutzer kannst du im Studio Credits gutschreiben (z. B. Support-Fall).
• Abrechnung: /spend läuft serverseitig – dein Client kann nicht schummeln. Bewährt: spend vor dem teuren Aufruf, bei 402 den Code-Dialog öffnen.

Beispiel: Chat-App mit Credits

// Registrierung (einmalig, Token lokal merken)
const r = await fetch("/data/api/APP_ID/register", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ user: "Arnold" }),
}).then(x => x.json());
const H = { Authorization: `Bearer ${r.token}`, "Content-Type": "application/json" };

// Chat-Verlauf persistieren
await fetch("/data/api/APP_ID/files/chats/heute.json",
  { method: "PUT", headers: H, body: JSON.stringify(messages) });

// 15 Credits für ein Bild abbuchen – 402 = Wallet leer
const paid = await fetch("/data/api/APP_ID/spend",
  { method: "POST", headers: H, body: JSON.stringify({ credits: 15, note: "bild" }) });
if (paid.status === 402) showRedeemDialog();

// Code einlösen
await fetch("/data/api/APP_ID/redeem",
  { method: "POST", headers: H, body: JSON.stringify({ code: "Bester Freund" }) });

8 · Komplettes Beispiel

Eine minimale, fertige WebApp, die einen hinterlegten API-Schlüssel über den Präfix /api nutzt. Lege die beiden Dateien in ein ZIP und lade es im Studio hoch (Startseite: index.html).

index.html

<!doctype html>
<html lang="de">
<head>
  <meta charset="utf-8">
  <title>KI-Grüße</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <h1>Frag die KI</h1>
  <input id="frage" placeholder="Deine Frage">
  <button id="los">Senden</button>
  <pre id="out"></pre>
  <script src="app.js"></script>
</body>
</html>

app.js

document.getElementById('los').addEventListener('click', async () => {
  const out = document.getElementById('out');
  out.textContent = 'Denke nach …';
  try {
    const antwort = await fetch('/api/v1/chat/completions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model: 'gpt-4o-mini',
        messages: [{ role: 'user', content: document.getElementById('frage').value }]
      })
    });
    const daten = await antwort.json();
    out.textContent = daten.choices[0].message.content;
  } catch (fehler) {
    out.textContent = 'Fehler: ' + fehler.message;
  }
});

In den Studio-Einstellungen dieser App trägst du dann den Schlüssel ein: Präfix /api, Grundadresse https://api.openai.com, Modus Header, Name Authorization, Wert Bearer {}, und deinen echten Schlüssel. Fertig – app.js enthält keinen Schlüssel.

9 · Häufige Fehler & Lösungen

10 · Grenzen & Fair Use

Der Schlüssel-Proxy ist ein praktischer Helfer, kein Durchlaufruf zum Selbstkostenpreis. Diese Grenzen schützen dich und den Store:

11 · APK und WebApp zusammen anbieten

Ein Eintrag im Store ist nicht entweder/oder. Du kannst zu derselben App eine APK für Android und ein WebApp-ZIP hinterlegen – Besucher sehen dann auf derselben Produktseite beide Wege: „↓ APK herunterladen" und „▶ WebApp öffnen". Nutzer müssen nicht erst suchen, wo welche Version steht.

1. Studio → App bearbeiten – beim Abschnitt Angebot beide Chips aktivieren: „Android (APK)" und „WebApp (Sandbox)".
2. Beide Dateien hochladen – die APK-Datei und das WebApp-ZIP. Beide Abschnitte erscheinen unter Dateien & Version.
3. Startseite angeben – gilt nur für das WebApp-Paket (z. B. index.html).
4. Speichern – die Produktseite zeigt beide Buttons; API-Schlüssel, App-Daten und Credits sind wie bei einer WebApp nutzbar, weil das ZIP vorhanden ist.

API in einer reinen nativen APK

Der Schlüssel-Proxy aus Abschnitt 5–6 funktioniert nur in der Sandbox, weil er an die WebApp-Sitzung gebunden ist. Eine native Android-App hat keine solche Sitzung und muss deshalb direkt mit der API sprechen. Das ist die ehrliche Grenze:

• Store Cloud (Abschnitt „Weiter" in den Cloud-Docs) kann deine APK direkt mit einem agc_…-Schlüssel ansprechen – Dateispeicher, Multimode-Räume und Credits gibt es auch ohne Browser.
• Ein in die APK eingebetteter Schlüssel ist auf jedem Gerät lesbar, sobald jemand die Datei entpackt. Lege dafür einen eigenen Schlüssel an, der nur in die Bucket-Präfixe deiner eigenen App schreiben darf, und rechne mit Missbrauch – oder betreibe einen eigenen kleinen Dienst, der den Schlüssel hält.
• Drittanbieter-KIschlüssel (OpenAI & Co.) gehören nicht in eine APK. Wenn deine App KI-Funktionen braucht, die sofort und sicher laufen soll: WebApp-Version zusätzlich anbieten und den Proxy benutzen.

12 · Veröffentlichung & Freigabe

Nichts geht automatisch online, nur weil eine Datei hochgeladen wurde. Jede Version, die ein Entwickler veröffentlicht, durchläuft diese Stufen:

1. Hochladen – die Datei liegt zunächst privat in deinem Konto. Entwürfe sind nur für dich sichtbar.
2. Automatische Vorprüfung – direkt nach dem Upload zeigt dir das Studio den Prüfbericht unter der APK (Abschnitt „Was geprüft wird").
3. Veröffentlichen – der Knopf Veröffentlichen reicht die Version bei der Store-Leitung ein. Status: Wartet auf Freigabe. Öffentlich ist sie jetzt noch nicht.
4. Manuelle Entscheidung – der Admin prüft den Bericht und entscheidet in der Inbox: freigeben oder ablehnen mit Begründung.
5. Sichtbar – nur ausdrücklich freigegebene Dateien sind im Store zu sehen und herunterladbar. Auf der Produktseite stehen Version, Größe, Freigabedatum, SHA-256 und die Berechtigungen der APK.

Was automatisch geprüft wird

Was ausdrücklich nicht geprüft wird

• Keine kryptografische Verifikation der Signatur: Der Store liest, dass und womit signiert wurde, prüft aber weder Zertifikatskette noch die Signaturblöcke selbst. Ein Signatureintrag beweist nicht, wer signiert hat.
• Kein Code-Review und keine Verhaltensanalyse: Es wird nicht getestet, was die App auf dem Gerät tut.
• Keine Malware-Garantie: Ohne konfigurierten Scanner erfolgt gar kein Virencheck; mit Scanner ist das Ergebnis ein Hinweis, kein Freispruch.
• Keine Bewertung von Berechtigungen: Die Liste und die Markierung auffälliger Einträge sind Entscheidungshilfe – die Einschätzung trifft der Mensch.

Statuswerte im Studio

Noch Fragen? Schreib eine Bewertung / Feedback bei deiner App oder wende dich an den Store-Betreiber. Viel Erfolg beim Bauen! · WebApp fertig? Die Store Cloud gibt denselben Entwicklern 512 MB Objektspeicher, Multimode Mehrspieler-Räume und App-Daten & Credits für deine Nutzer. · Zurück zum Store · Studio