Zum Hauptinhalt springen

SDK-Referenz

Das Mini-Programm SDK ist eine ~2 KB JavaScript-Bibliothek, die in jeden Mini-Programm-iframe injiziert wird. Es stellt den window.ais-Namespace mit Methoden zur Interaktion mit der AISCouncil Plattform über eine sichere postMessage-Bridge bereit.

Wie das SDK funktioniert​

Das SDK wird als <script>-Tag vor Ihrem App-HTML im srcdoc des iframes injiziert. Sie müssen es nicht selbst einbinden – es ist immer als window.ais verfügbar, wenn Ihr Code ausgeführt wird.

Jeder Methodenaufruf (außer platform.*-Eigenschaften) sendet eine Nachricht an die Host-Seite und gibt ein Promise zurück. Der Host validiert Berechtigungen, führt die Anfrage aus und sendet das Ergebnis zurück.

Ihr App-Code               SDK                    Host-Plattform
     |                        |                          |
     |-- ais.chat.send("hi")-->|                          |
     |                        |-- postMessage({           |
     |                        |     method: "chat.send",  |
     |                        |     args: {text: "hi"}    |
     |                        |   }) ---------------------->|
     |                        |                          |-- Berechtigungen prüfen
     |                        |                          |-- AIS.Chat.send() ausführen
     |                        |<-- postMessage({result}) --|
     |<-- Promise wird aufgelöst ---|                    |
Info

Alle SDK-Methoden sind synchron als Funktionsreferenzen verfügbar, geben aber Promises zurück, die asynchron aufgelöst werden. Verwenden Sie immer await oder .then(), um Ergebnisse zu erhalten.

TypeScript-Unterstützung​

TypeScript-Typdefinitionen sind in sdk/ais.d.ts verfügbar. Fügen Sie eine Referenz zu Ihrem Projekt hinzu:

/// <reference path="./ais.d.ts" />

ais.ready(async () => {
  const history = await ais.chat.getHistory(10);
  // history ist als ais.ChatMessage[] typisiert
});

Oder kopieren Sie die AisManifest- und AisPermission-Typen für Manifest-Validierung in Ihren Build-Tools.

Lebenszyklus​

ais.ready(callback)​

Registriert einen Callback, der ausgelöst wird, wenn die Plattform-Bridge verbunden und bereit ist. Dies ist der Einstiegspunkt für Ihre App – wickeln Sie alle Initialisierungslogik in diesen Callback.

ParameterTypBeschreibung
callback() => voidFunktion, die aufgerufen wird, wenn die Bridge bereit ist
ais.ready(async function () {
  // Plattform ist verbunden, SDK-Aufrufe funktionieren jetzt
  const user = await ais.auth.getUser();
  document.getElementById("greeting").textContent = "Hallo, " + user.name;
});
Vorsicht

Rufen Sie keine anderen ais.*-Methoden auf, bevor ais.ready() ausgelöst wurde. Die postMessage-Bridge ist möglicherweise noch nicht eingerichtet, und Aufrufe werden unbegrenzt hängen.

ais.onShow(callback)​

Registriert einen Callback, der jedes Mal ausgelöst wird, wenn das Mini-Programm sichtbar wird (z.B. Benutzer schaltet zurück zum App-Tab).

ParameterTypBeschreibung
callback() => voidFunktion, die bei Anzeige aufgerufen wird
ais.onShow(function () {
  // Daten aktualisieren, wenn Benutzer zur App zurückkehrt
  refreshDashboard();
});

ais.onHide(callback)​

Registriert einen Callback, der ausgelöst wird, wenn das Mini-Programm ausgeblendet wird (z.B. Benutzer wechselt zu Chat oder einer anderen App).

ParameterTypBeschreibung
callback() => voidFunktion, die bei Ausblendung aufgerufen wird
ais.onHide(function () {
  // Teure Operationen pausieren
  stopPolling();
});

ais.close()​

Schließt das Mini-Programm und kehrt zur Chat-Ansicht zurück. Der iframe wird nach diesem Aufruf zerstört.

Rückgabe: Promise<boolean>

document.getElementById("done-btn").addEventListener("click", function () {
  ais.close();
});

Speicher​

Pro-App isolierter Schlüssel-Wert-Speicher, unterstützt durch IndexedDB. Schlüssel werden automatisch mit mp:{app-name}: vorangestellt, sodass Apps nicht auf die Daten anderer Apps zugreifen können.

Berechtigung: Immer erlaubt – keine Berechtigung erforderlich.

ais.storage.get(key)​

Ruft einen Wert anhand des Schlüssels ab. Gibt undefined zurück, wenn der Schlüssel nicht existiert.

ParameterTypBeschreibung
keystringDer Speicherschlüssel

Rückgabe: Promise<unknown> – der gespeicherte Wert oder undefined

const count = await ais.storage.get("visit-count");
console.log("Besuche:", count); // number, string, object, array oder undefined

ais.storage.set(key, value)​

Speichert ein Schlüssel-Wert-Paar. Der Wert kann jeder JSON-serialisierbare Typ sein (string, number, boolean, object, array, null).

ParameterTypBeschreibung
keystringDer Speicherschlüssel
valueunknownDer zu speichernde Wert (muss JSON-serialisierbar sein)

Rückgabe: Promise<boolean> – true bei Erfolg

await ais.storage.set("visit-count", 42);
await ais.storage.set("preferences", { theme: "dark", fontSize: 16 });

ais.storage.remove(key)​

Löscht einen Schlüssel aus dem Speicher.

ParameterTypBeschreibung
keystringDer zu entfernende Schlüssel

Rückgabe: Promise<boolean> – true bei Erfolg

await ais.storage.remove("temporary-data");

ais.storage.keys()​

Listet alle von diesem Mini-Programm gespeicherten Schlüssel auf (ohne das interne mp:{name}:-Präfix).

Rückgabe: Promise<string[]>

const keys = await ais.storage.keys();
console.log("Gespeicherte Schlüssel:", keys); // ['visit-count', 'preferences']

Chat​

Chat-Verlauf lesen, Nachrichten senden und neue Nachrichten in der aktiven Konversation abonnieren.

Erforderliche Berechtigungen: chat:read zum Lesen, chat:write zum Senden.

ais.chat.getHistory(limit?)​

Holt aktuelle Nachrichten aus der aktiven Chat-Sitzung.

ParameterTypStandardBeschreibung
limitnumber50Maximale Anzahl der zurückzugebenden Nachrichten

Rückgabe: Promise<ChatMessage[]>

interface ChatMessage {
  role: "user" | "assistant" | "system";
  content: string;
  timestamp?: number;
}
const messages = await ais.chat.getHistory(20);
messages.forEach(function (msg) {
  console.log(msg.role + ": " + msg.content);
});

ais.chat.send(text)​

Sendet eine Nachricht als Benutzer. Dies löst aus, dass das aktive KI-Modell eine Antwort generiert.

ParameterTypBeschreibung
textstringDer zu sendende Nachrichtentext

Rückgabe: Promise<boolean> – true bei Erfolg

await ais.chat.send("Fasse die letzten 5 Nachrichten zusammen");
Warnung

Der Aufruf von ais.chat.send() löst einen tatsächlichen API-Aufruf an den konfigurierten KI-Anbieter des Benutzers aus. Dies verbraucht Tokens und kann Kosten verursachen. Verwenden Sie es verantwortungsvoll und informieren Sie den Benutzer immer, bevor Sie Nachrichten programmatisch senden.

ais.chat.onMessage(callback)​

Abonniert neue Chat-Nachrichten. Der Callback wird für jede neue Nachricht ausgelöst (sowohl Benutzer als auch Assistant).

ParameterTypBeschreibung
callback(msg: ChatMessage) => voidHandler für eingehende Nachrichten
ais.chat.onMessage(function (msg) {
  if (msg.role === "assistant") {
    // KI-Modell hat geantwortet
    updateResponseDisplay(msg.content);
  }
});

Config​

Liest die Konfiguration des aktiven Bots (Anbieter, Modell, System-Prompt, etc.).

Erforderliche Berechtigung: config:read

ais.config.get()​

Holt das vollständige Bot-Konfigurationsobjekt.

Rückgabe: Promise<BotConfig>

interface BotConfig {
  n?: string; // Bot-Name
  p?: string; // Anbieter-ID (z.B. 'anthropic', 'openai', 'gemini')
  m?: string; // Modell-ID (z.B. 'claude-sonnet-4-20250514')
  s?: string; // System-Prompt
  t?: number; // Temperatur (0.0 - 2.0)
  x?: number; // Max. Output-Tokens
  [key: string]: unknown;
}
const config = await ais.config.get();
console.log("Verwendetes Modell:", config.m);
console.log("System-Prompt:", config.s);

ais.config.getProvider()​

Holt die aktive Anbieter-ID.

Rückgabe: Promise<string> – z.B. 'anthropic', 'openai', 'gemini', 'xai', 'openrouter', 'ollama'

const provider = await ais.config.getProvider();
if (provider === "ollama") {
  showLocalModelBanner();
}

ais.config.getModel()​

Holt die aktive Modell-ID.

Rückgabe: Promise<string> – z.B. 'claude-sonnet-4-20250514', 'gpt-4o', 'gemini-2.5-flash'

const model = await ais.config.getModel();
document.getElementById("model-name").textContent = model;

UI​

Benachrichtigungen anzeigen, Bestätigungsdialoge zeigen und den Titel des Apps-Panels aktualisieren.

ais.ui.toast(message, duration?)​

Zeigt eine temporäre Toast-Benachrichtigung in der Plattform-UI.

ParameterTypStandardBeschreibung
messagestring--Benachrichtigungstext (max. 200 Zeichen)
durationnumber3000Dauer in Millisekunden

Rückgabe: Promise<boolean>

Berechtigung: ui:toast (empfohlen, aber nicht strikt erzwungen – Toast ist wenig invasiv)

await ais.ui.toast("Datei erfolgreich gespeichert!");
await ais.ui.toast("Verarbeite...", 5000); // 5-Sekunden-Toast

ais.ui.confirm(title, message)​

Zeigt einen Bestätigungsdialog und wartet auf die Antwort des Benutzers.

ParameterTypBeschreibung
titlestringDialog-Titel (max. 100 Zeichen)
messagestringDialog-Text (max. 500 Zeichen)

Rückgabe: Promise<boolean> – true wenn Benutzer OK geklickt hat, false bei Abbruch

Erforderliche Berechtigung: ui:modal

const confirmed = await ais.ui.confirm(
  "Alle Daten löschen?",
  "Dies entfernt dauerhaft alle gespeicherten Elemente. Diese Aktion kann nicht rückgängig gemacht werden.",
);
if (confirmed) {
  await clearAllData();
}

ais.ui.setTitle(title)​

Setzt den Text, der in der Titelleiste des Apps-Panels angezeigt wird.

ParameterTypBeschreibung
titlestringTiteltext (max. 100 Zeichen)

Rückgabe: Promise<boolean>

ais.ui.setTitle("Wortzähler - 1.234 Wörter");

Auth​

Liest Informationen über den aktuell angemeldeten Benutzer.

Erforderliche Berechtigung: auth:read

ais.auth.getUser()​

Holt die Profilinformationen des aktuellen Benutzers.

Rückgabe: Promise<UserInfo | null> – null wenn nicht angemeldet

interface UserInfo {
  name: string; // Anzeigename
  email: string; // E-Mail-Adresse
  picture: string; // Profilfoto-URL
}
const user = await ais.auth.getUser();
if (user) {
  document.getElementById("avatar").src = user.picture;
  document.getElementById("name").textContent = user.name;
} else {
  document.getElementById("name").textContent = "Gast";
}

ais.auth.getTier()​

Holt das Abonnement-Level des Benutzers.

Rückgabe: Promise<string> – z.B. 'free', 'pro', 'team'

const tier = await ais.auth.getTier();
if (tier === "free") {
  showUpgradePrompt();
}

Secrets​

Liest und schreibt API-Schlüssel für Gerät-zu-Gerät-Übertragungsszenarien. Dies ist eine privilegierte API, die von Apps wie Geräte-Sync verwendet wird.

Erforderliche Berechtigung: secrets:sync

Vorsicht

Die secrets:sync-Berechtigung gewährt Zugriff auf die gespeicherten API-Schlüssel des Benutzers. Fordern Sie diese Berechtigung nur an, wenn Ihre App tatsächlich Credentials übertragen oder sichern muss. Benutzer sehen eine klare Warnung im Berechtigungsdialog.

ais.secrets.list()​

Listet Anbieternamen auf, die gespeicherte API-Schlüssel haben.

Rückgabe: Promise<string[]> – z.B. ['anthropic', 'openai', 'gemini']

ais.secrets.get(provider)​

Holt einen API-Schlüsselwert anhand des Anbieternamens.

ParameterTypBeschreibung
providerstringAnbietername (z.B. 'anthropic', 'openai')

Rückgabe: Promise<string | null>

ais.secrets.set(provider, value)​

Speichert einen API-Schlüssel für einen Anbieter.

ParameterTypBeschreibung
providerstringAnbietername
valuestringAPI-Schlüsselwert (max. 1024 Zeichen)

Rückgabe: Promise<boolean>

Sync​

Synchronisiert Profile, Einstellungen und WebRTC-Signalisierung für Gerät-zu-Gerät-Übertragung.

Erforderliche Berechtigung: secrets:sync

ais.sync.getProfiles()​

Holt alle Benutzerprofile von der Host-Plattform.

Rückgabe: Promise<Profile[]>

ais.sync.setProfiles(profiles)​

Importiert Profile in die Host-Plattform.

ParameterTypBeschreibung
profilesProfile[]Array von Profilobjekten zum Importieren

Rückgabe: Promise<number> – Anzahl importierter Profile

ais.sync.getSettings()​

Holt App-Einstellungen (Theme, Locale, etc.) vom Host.

Rückgabe: Promise<Record<string, string>>

ais.sync.setSettings(settings)​

Schreibt App-Einstellungen zum Host.

ParameterTypBeschreibung
settingsRecord<string, string>Schlüssel-Wert-Einstellungen zum Schreiben

Rückgabe: Promise<boolean>

ais.sync.signal(code, type, sdp)​

Postet ein SDP-Offer/Answer zum API-Relay für WebRTC-Signalisierung.

ParameterTypBeschreibung
codestringPairing-Code
type'offer' | 'answer'SDP-Typ
sdpRTCSessionDescriptionInitSDP-Daten

Rückgabe: Promise<boolean>

ais.sync.pollSignal(code, type)​

Pollt nach einem SDP-Offer/Answer vom API-Relay.

ParameterTypBeschreibung
codestringPairing-Code
type'offer' | 'answer'SDP-Typ, nach dem gepollt werden soll

Rückgabe: Promise<RTCSessionDescriptionInit | null>

Hooks​

Registriert und feuert benutzerdefinierte Hook-Events, um Plattform-Verhalten zu erweitern oder zwischen Apps zu kommunizieren.

Erforderliche Berechtigungen: hooks:action zum Feuern von Events, hooks:filter zum Registrieren von Filter-Handlern.

ais.hooks.on(hookName, handler)​

Hört auf ein benanntes Hook-Event.

ParameterTypBeschreibung
hookNamestringHook-Name (z.B. 'chat:before-send')
handler(data: unknown) => voidEvent-Handler

Rückgabe: Promise<boolean>

ais.hooks.on("chat:before-send", function (data) {
  console.log("Nachricht wird gesendet:", data);
});

ais.hooks.fire(hookName, data?)​

Feuert ein benanntes Hook-Event. Alle registrierten Handler für diesen Hook werden aufgerufen.

ParameterTypBeschreibung
hookNamestringHook-Name zum Feuern
dataunknownOptionale Daten-Payload

Rückgabe: Promise<unknown>

await ais.hooks.fire("my-app:data-updated", { count: 42 });

Pages​

Veröffentlicht Webseiten auf bcz.co mit einem benutzerdefinierten Slug. Wird vom App Builder Mini-Programm verwendet.

Erforderliche Berechtigung: pages:publish

ais.pages.getInfo()​

Holt Informationen über die veröffentlichte Seite des Benutzers.

Rückgabe: Promise<PageInfo>

interface PageInfo {
  slug: string | null;
  url: string | null;
  title: string | null;
  updatedAt: number | null;
  hasPage: boolean;
}

ais.pages.claim(slug)​

Beansprucht einen Slug (Benutzername) für bcz.co/@slug.

ParameterTypBeschreibung
slugstringGewünschter Slug

Rückgabe: Promise<{ slug: string; url: string }>

ais.pages.publish(specBase64, opts?)​

Veröffentlicht oder aktualisiert eine Seite. Die spec ist ein base64-kodiertes PDL-Dokument.

ParameterTypBeschreibung
specBase64stringBase64-kodierte Page-Spec
opts{ title?: string; description?: string }Optionale Metadaten

Rückgabe: Promise<PublishResult>

ais.pages.unpublish()​

Entfernt die Veröffentlichung und gibt den Slug frei.

Rückgabe: Promise<boolean>

Plattform-Info​

Schreibgeschützte Eigenschaften mit Plattform-Metadaten. Diese sind synchron – kein Promise, keine Berechtigung erforderlich.

ais.platform.version​

Die Plattform-Versionszeichenfolge (semver).

Typ: string – aktuell '1.0.0'

ais.platform.abi​

Die ABI-Versionsnummer. Wird verwendet, um die Kompatibilität zwischen SDK und Host-Plattform zu verifizieren.

Typ: number – aktuell 1

if (ais.platform.abi !== 1) {
  ais.ui.toast("Diese App erfordert ABI-Version 1");
  ais.close();
}

Fehlerbehandlung​

Alle SDK-Aufrufe, die Berechtigungen erfordern, lehnen mit einem PermissionDenied-Fehler ab, wenn die App nicht die erforderliche Berechtigung hat:

try {
  const history = await ais.chat.getHistory();
} catch (err) {
  if (err.message.includes("PermissionDenied")) {
    console.log("App hat keine chat:read-Berechtigung");
  }
}

Unbekannte Methoden geben einen Fehler mit der Nachricht Unknown method: {method} zurück.

Wenn die Host-Plattform auf einen unerwarteten Fehler stößt, lehnt das Promise mit der Fehlermeldungszeichenfolge ab.

Tipp

Wickeln Sie SDK-Aufrufe immer in try/catch-Blöcke ein, insbesondere bei berechtigungsgesteuerten APIs. Dies macht Ihre App robust, selbst wenn die Plattform-Version des Benutzers von der, die Sie getestet haben, abweicht.

Vollständiges Beispiel​

Eine minimale App, die mehrere SDK-Funktionen verwendet:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style>
      body {
        font-family: system-ui;
        padding: 16px;
        color: #e0e0e0;
        background: #1a1a2e;
      }
      button {
        min-height: 48px;
        padding: 8px 16px;
        font-size: 16px;
        border: 1px solid #444;
        border-radius: 6px;
        background: #2a2a4e;
        color: #e0e0e0;
        cursor: pointer;
      }
      button:hover {
        background: #3a3a5e;
      }
      pre {
        background: #111;
        padding: 12px;
        border-radius: 6px;
        overflow: auto;
      }
    </style>
  </head>
  <body>
    <h2>Chat-Inspektor</h2>
    <button id="load">Verlauf laden</button>
    <button id="close">Schließen</button>
    <pre id="output">Klicken Sie auf "Verlauf laden", um zu beginnen...</pre>

    <script>
      ais.ready(async function () {
        // Zeige welches Modell aktiv ist
        var model = await ais.config.getModel();
        ais.ui.setTitle("Chat-Inspektor - " + model);

        document
          .getElementById("load")
          .addEventListener("click", async function () {
            var messages = await ais.chat.getHistory(25);
            var output = messages
              .map(function (m) {
                return "[" + m.role + "] " + m.content.slice(0, 100);
              })
              .join("\n");
            document.getElementById("output").textContent =
              output || "(keine Nachrichten)";
            ais.ui.toast(messages.length + " Nachrichten geladen");
          });

        document.getElementById("close").addEventListener("click", function () {
          ais.close();
        });

        // Abonniere neue Nachrichten in Echtzeit
        ais.chat.onMessage(function (msg) {
          var el = document.getElementById("output");
          el.textContent += "\n[" + msg.role + "] " + msg.content.slice(0, 100);
        });
      });
    </script>
  </body>
</html>

Manifest für dieses Beispiel:

{
  "name": "chat-inspector",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "description": "Chat-Verlauf anzeigen und überwachen",
  "entry": "index.html",
  "base_url": "https://your-cdn.com/chat-inspector/",
  "permissions": ["chat:read", "config:read", "ui:toast"]
}