Zum Hauptinhalt springen

Iframe-Schnellstart

Dies ist der schnellste Weg, die Developer API auszuprobieren, ohne vorher ein Backend entwickeln zu müssen.

Im iFrame-Modus kommuniziert Ihre App mit dem übergeordneten Element Chastify über postMessage, und Chastify ruft in Ihrem Namen Server-APIs auf.

Was Chastify an Ihren iFrame übergibt​

Beim Öffnen speichert Chastify eine JSON-Nutzlast in location.hash.
Wichtige Felder:

  • bridge.nonce: Anforderungswert für die Signatur von Bridge-Nachrichten.
  • bridge.parentOrigin: Erforderlicher Zielursprung für postMessage.
  • sessionId: Stabile Erweiterungssitzungs-ID für diese Sperre.
  • lockId: Aktive Sperr-ID.
  • ui: Designwerte der übergeordneten Seite.
  • Optional: homeActionSlug, homeAction, intent, regularActionsSummary, mainToken.

Verwenden Sie Hilfsfunktionen von apps/extension/src/lib/ChastifyBridge.ts:

  • parseHashPayload()
  • ChastifyBridgeClient
  • startAutoResizeToParent(...)
  • themeVars(...)

Minimales React-Bootstrap​

import { useEffect, useMemo, useState } from "react";
import {
  parseHashPayload,
  ChastifyBridgeClient,
  startAutoResizeToParent,
  themeVars,
} from "../lib/ChastifyBridge";

const payload = parseHashPayload();
if (!payload?.bridge?.nonce || !payload?.bridge?.parentOrigin) {
  throw new Error("Missing bridge payload in iframe hash");
}

export function App() {
  const [client, setClient] = useState<ChastifyBridgeClient | null>(null);
  const [session, setSession] = useState<any>(null);
  const [stateDoc, setStateDoc] = useState<any>(null);
  const vars = useMemo(() => themeVars(payload.ui ?? null), []);

  useEffect(() => {
    const c = new ChastifyBridgeClient({
      nonce: payload.bridge!.nonce,
      targetOrigin: payload.bridge!.parentOrigin,
    });
    setClient(c);
    return () => c.destroy();
  }, []);

  useEffect(() => {
    if (!client) return;
    (async () => {
      const s = await client.request("session.get", {});
      setSession(s);

      const st = await client.request("state.get", {});
      setStateDoc(st);
    })().catch(console.error);
  }, [client]);

  useEffect(() => {
    return startAutoResizeToParent({
      nonce: payload.bridge!.nonce,
      targetOrigin: payload.bridge!.parentOrigin,
      extraPx: 12,
    });
  }, []);

  return (
    <div style={{ background: vars.pageBg, color: vars.text, minHeight: "100%" }}>
      <h2>Extension Quickstart</h2>
      <pre>{JSON.stringify(session, null, 2)}</pre>
      <pre>{JSON.stringify(stateDoc, null, 2)}</pre>
    </div>
  );
}

Rohes postMessage-Beispiel (ohne Hilfsklasse)​

Wenn Sie ChastifyBridgeClient nicht verwenden, senden Sie den vollständigen Anforderungsumschlag manuell:

const req = {
  type: "chastify:ext:req",
  v: 1,
  id: crypto.randomUUID(),
  nonce,
  action: "session.get",
  payload: {},
};

window.parent.postMessage(req, parentOrigin);

Achten Sie auf übereinstimmende Antworten:

window.addEventListener("message", (event) => {
  if (event.origin !== parentOrigin) return;
  const msg = event.data;
  if (!msg || msg.type !== "chastify:ext:resp" || msg.v !== 1) return;
  if (msg.id !== req.id) return;

  if (msg.ok) console.log("Bridge success:", msg.data);
  else console.error("Bridge error:", msg.error);
});

Testablauf, den Sie zuerst ausführen sollten​

  1. session.get
  2. state.get
  3. metadata.get
  4. regularActions.get

Dies bestätigt die Bridge-Authentifizierung, sichere Lesezugriffe und die Verarbeitung von Anfragen und Antworten. Statusänderungen müssen von Ihrem Backend mit den Anmeldeinformationen der Entwickler-API durchgeführt werden.

Datei-Uploads aus dem iFrame​

Falls Ihre Erweiterung Bilder oder generierte Medien benötigt, verwenden Sie die Bridge-Datei-Helfer. Chastify lädt die Datei in den verwalteten R2-Speicher hoch, gibt eine stabile Datei-ID zurück und stellt Ihnen eine kurzlebige signierte URL zum Rendern bereit.

const capabilities = await client.filesCapabilities();
if (capabilities.enabled) {
  const uploaded = await client.filesUpload({
    file,
    filename: file.name,
    purpose: "puzzle-image",
  });

  // Send uploaded.file.id to your backend if it should be stored in session state.

  const refreshed = await client.filesGet(uploaded.file.id);
  image.src = refreshed.file.signedUrl;
}

Speichern Sie uploaded.file.id, nicht die signierte URL. Signierte URLs laufen ab und müssen beim erneuten Laden des iFrames mit files.get / client.filesGet(...) aktualisiert werden.

Theme-Unterstützung (ui + themeVars)​

Chastify übergibt ein ui-Objekt im iframe-Hash.
themeVars(ui) wandelt es in verwendbare Design-Tokens um:

  • pageBg
  • text
  • panel
  • border
  • muted
  • inputBg

Verwenden Sie diese Werte als Basisstyling für Ihre Erweiterung, damit Ihr iFrame zum Host-Design passt.

Live-Theme-Updates​

Das übergeordnete Element kann chastify:ext:ui-Ereignisse senden, während Ihr iFrame geöffnet ist.
Wenn Sie eine Live-Theme-Synchronisierung wünschen, achten Sie auf dieses Ereignis und aktualisieren Sie den lokalen Theme-Status.

Für detaillierte Informationen zur Handhabung von hellen/dunklen Designs, Kontrastbeispielen und Tailwind-Mustern siehe Iframe Theming.

Unterstützung für automatische Größenanpassung​

Verwenden Sie startAutoResizeToParent(...), damit das übergeordnete Element den iFrame an Ihren Inhalt anpassen kann.

Warum das wichtig ist:

  • Verhindert Scroll-Traps innerhalb des iFrames.
  • Sorgt dafür, dass Setup-Modalfenster und Erweiterungsseiten die richtige Größe haben.
  • Eignet sich gut für dynamische Abschnitte, die sich ein- und ausklappen lassen.

Häufige Fehler​

  • Falscher targetOrigin (muss mit bridge.parentOrigin übereinstimmen).
  • Fehlender oder veralteter nonce.
  • Beim Aushängen von ChastifyBridgeClient wird destroy() nicht aufgerufen.
  • Senden nicht unterstützter Aktionen, ohne vorher die Fähigkeiten von session.get zu prüfen.

Referenzdateien​

  • apps/extension/src/lib/ChastifyBridge.ts
  • apps/extension/src/pages/MainPage.tsx
  • apps/extension/src/pages/SetupPage.tsx