Iframe-pika-aloitus

Tämä on nopein tapa kokeilla kehittäjän API:a ilman taustajärjestelmän rakentamista ensin.

iframe-tilassa sovelluksesi kommunikoi Chastify-pääobjektin kanssa postMessage:n kautta, ja Chastify kutsuu palvelimen API-rajapintoja puolestasi.

Mitä Chastify välittää iframe-kehyksellesi

Avattaessa Chastify sijoittaa JSON-hyötykuorman location.hash:han.
Tärkeitä kenttiä:

• bridge.nonce: pyydä sillan sanomien allekirjoitusarvoa.
• bridge.parentOrigin: pakollinen kohdealkuperä koodille postMessage.
• sessionId: vakaa laajennusistunnon tunnus tälle lukolle.
• lockId: aktiivisen lukon tunnus.
• ui: teeman arvot pääsivulta.
• Valinnainen: homeActionSlug, homeAction, intent, regularActionsSummary, mainToken.

Bridge-kirjaston pika-aloitus (suositus)

Käytä apps/extension/src/lib/ChastifyBridge.ts:n apuohjelmia:

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

Minimalistinen React-käynnistys

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

Raaka postMessage-esimerkki (ei apuluokkaa)

Jos et käytä koodia ChastifyBridgeClient, lähetä koko pyyntökuori manuaalisesti:

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

window.parent.postMessage(req, parentOrigin);

Kuuntele yhteensopivia vastauksia:

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

Testikulku, joka sinun tulisi suorittaa ensin

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

Tämä vahvistaa sillan todennuksen, turvalliset luvut ja pyyntöjen/vastausten käsittelyn. Taustajärjestelmän on suoritettava tilakirjoitukset kehittäjän API-tunnuksilla.

Tiedostojen lataukset iframesta

Jos laajennuksesi tarvitsee kuvia tai luotua mediaa, käytä siltatiedostojen apuohjelmia. Chastify lataa tiedoston hallittuun R2-tallennustilaan, palauttaa vakaan tiedostotunnuksen ja antaa sinulle lyhytikäisen allekirjoitetun URL-osoitteen renderöintiä varten.

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

Säilytä koodi uploaded.file.id, älä allekirjoitettua URL-osoitetta. Allekirjoitetut URL-osoitteet vanhenevat ja ne tulisi päivittää koodilla files.get / client.filesGet(...), kun iframe latautuu uudelleen.

Teeman tuki (ui + themeVars)

Chastify välittää ui-objektin iframe-hajautusarvossa.
themeVars(ui) muuntaa sen käyttökelpoisiksi suunnittelutokeneiksi:

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

Käytä näitä arvoja laajennuksesi perustyylinä, jotta iframe-kehys vastaa isäntäteemaa.

Live-teemapäivitykset

Ylätason objekteja voidaan lähettää chastify:ext:ui-tapahtumilla, kun iframe on auki.
Jos haluat teeman synkronoinnin reaaliajassa, kuuntele kyseistä tapahtumaa ja päivitä teeman paikallinen tila.

Yksityiskohtaisia ​​vaalean/tumman teeman käsittelyohjeita, kontrastiesimerkkejä ja Tailwind-kuvioita varten katso Iframe Theming.

Automaattisen koon muuttamisen tuki

Käytä startAutoResizeToParent(...)-koodia, jotta pääobjekti voi muuttaa iframe-kehyksen kokoa sisältösi mukaan.

Miksi tällä on merkitystä:

• Estää vieritysloukut iframe-kehyksen sisällä.
• Pitää asennusmoduulien ja laajennussivujen koon oikeana.
• Toimii hyvin dynaamisille osioille, jotka laajenevat/kutistuvat.

Yleisiä virheitä

• Väärä targetOrigin (täytyy vastata koodia bridge.parentOrigin).
• Puuttuva tai vanhentunut nonce.
• destroy():ta ei kutsuta ChastifyBridgeClient:n irrotuksen yhteydessä.
• Lähetetään ei-tuettuja toimintoja tarkistamatta ensin session.get:n ominaisuuksia.

Viitetiedostot

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