Ga naar hoofdinhoud

Iframe Snelstartgids

Dit is de snelste manier om de Developer API uit te proberen zonder eerst een backend te hoeven bouwen.

In iframe-modus communiceert uw app met de Chastify-parent via postMessage, en Chastify roept namens u server-API's aan.

Wat Chastify doorgeeft aan uw iframe​

Bij het openen plaatst Chastify een JSON-payload in location.hash.
Belangrijke velden:

  • bridge.nonce: waarde voor het aanvragen van ondertekening voor bridgeberichten.
  • bridge.parentOrigin: vereiste doeloorsprong voor postMessage.
  • sessionId: stabiele extensiesessie-ID voor dit slot.
  • lockId: actieve vergrendelings-ID.
  • ui: themawaarden van de bovenliggende pagina.
  • Optioneel: homeActionSlug, homeAction, intent, regularActionsSummary, mainToken.

Gebruik helpers van apps/extension/src/lib/ChastifyBridge.ts:

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

Minimale 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>
  );
}

Ruwe postMessage-voorbeeld (zonder hulpklasse)​

Als u ChastifyBridgeClient niet gebruikt, verstuur dan de volledige aanvraag-envelop handmatig:

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

window.parent.postMessage(req, parentOrigin);

Luister naar overeenkomende antwoorden:

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);
});

Testprocedure die u eerst moet uitvoeren​

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

Dit bevestigt de authenticatie via de bridge, veilige leesbewerkingen en de afhandeling van verzoeken en antwoorden. Wijzigingen in de status moeten door uw backend worden uitgevoerd met behulp van de API-referenties voor ontwikkelaars.

Bestanden uploaden vanuit een iframe​

Als uw extensie afbeeldingen of gegenereerde media nodig heeft, gebruik dan de helpers voor bridgebestanden. Chastify uploadt naar beheerde R2-opslag, retourneert een stabiele bestands-ID en geeft u een kortstondige, ondertekende URL voor weergave.

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;
}

Sla uploaded.file.id op, niet de ondertekende URL. Ondertekende URL's verlopen en moeten worden vernieuwd met files.get / client.filesGet(...) wanneer de iframe opnieuw wordt geladen.

Themaondersteuning (ui + themeVars)​

Chastify geeft een ui-object door in de iframe-hash.
themeVars(ui) zet het om in bruikbare ontwerptokens:

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

Gebruik deze waarden als basisstijl voor uw extensie, zodat uw iframe overeenkomt met het thema van de host.

Live thema-updates​

De ouder kan chastify:ext:ui-gebeurtenissen verzenden terwijl uw iframe geopend is.
Als je live themasynchronisatie wilt, luister dan naar die gebeurtenis en werk de lokale themastatus bij.

Voor gedetailleerde informatie over het gebruik van lichte/donkere thema's, contrastvoorbeelden en Tailwind-patronen, zie Iframe Theming.

Ondersteuning voor automatisch formaat aanpassen​

Gebruik startAutoResizeToParent(...) zodat het bovenliggende element de iframe kan aanpassen aan de grootte van uw inhoud.

Waarom dit belangrijk is:

  • Voorkomt dat het scherm vast komt te zitten in de scrollpositie binnen de iframe.
  • Zorgt ervoor dat de configuratievensters en extensiepagina's de juiste afmetingen behouden.
  • Werkt goed voor dynamische secties die uit- en inklappen.

Veelgemaakte fouten​

  • Onjuiste targetOrigin (moet overeenkomen met bridge.parentOrigin).
  • Ontbrekende of verouderde nonce.
  • destroy() wordt niet aangeroepen bij het ontkoppelen van ChastifyBridgeClient.
  • Het verzenden van niet-ondersteunde acties zonder eerst de mogelijkheden van session.get te controleren.

Referentiebestanden​

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