आईफ्रेम क्विकस्टार्ट

बैकएंड बनाए बिना डेवलपर एपीआई को आज़माने का यह सबसे तेज़ तरीका है।

आईफ्रेम मोड में, आपका ऐप postMessage के माध्यम से Chastify पैरेंट से बात करता है, और Chastify आपकी ओर से सर्वर API को कॉल करता है।

Chastify आपके iframe को क्या पास करता है

खोलने पर, Chastify एक JSON पेलोड को location.hash में डालता है।
महत्वपूर्ण क्षेत्र:

• bridge.nonce: ब्रिज संदेशों के लिए अनुरोध हस्ताक्षर मान।
• bridge.parentOrigin: postMessage के लिए आवश्यक लक्ष्य मूल।
• sessionId: इस लॉक के लिए स्थिर एक्सटेंशन सत्र आईडी।
• lockId: सक्रिय लॉक आईडी।
• ui: पैरेंट पेज से थीम मान।
• वैकल्पिक: homeActionSlug, homeAction, intent, regularActionsSummary, mainToken.

ब्रिज लाइब्रेरी के साथ त्वरित शुरुआत (अनुशंसित)

apps/extension/src/lib/ChastifyBridge.ts से सहायक टूल का उपयोग करें:

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

न्यूनतम रिएक्ट बूटस्ट्रैप

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

रॉ postMessage उदाहरण (बिना किसी सहायक क्लास के)

यदि आप ChastifyBridgeClient का उपयोग नहीं करते हैं, तो पूर्ण अनुरोध लिफाफा मैन्युअल रूप से भेजें:

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

window.parent.postMessage(req, parentOrigin);

मिलते-जुलते उत्तरों को ध्यान से सुनें:

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

आपको सबसे पहले कौन सा टेस्ट फ्लो चलाना चाहिए?

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

यह ब्रिज प्रमाणीकरण, सुरक्षित पठन और अनुरोध/प्रतिक्रिया प्रबंधन की पुष्टि करता है। स्टेट राइट्स आपके बैकएंड द्वारा डेवलपर API क्रेडेंशियल्स के साथ किए जाने चाहिए।

आईफ्रेम से फ़ाइल अपलोड करें

यदि आपके एक्सटेंशन को छवियों या जनरेटेड मीडिया की आवश्यकता है, तो ब्रिज फ़ाइल हेल्पर का उपयोग करें। Chastify प्रबंधित R2 स्टोरेज पर अपलोड करता है, एक स्थिर फ़ाइल आईडी लौटाता है, और आपको रेंडरिंग के लिए एक अल्पकालिक हस्ताक्षरित URL देता है।

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

uploaded.file.id को स्टोर करें, हस्ताक्षरित URL को नहीं। हस्ताक्षरित URL की वैधता समाप्त हो जाती है और iframe के पुनः लोड होने पर उन्हें files.get / client.filesGet(...) से पुनः अपडेट किया जाना चाहिए।

थीम समर्थन (ui + themeVars)

Chastify iframe हैश में ui ऑब्जेक्ट पास करता है।
themeVars(ui) इसे प्रयोग करने योग्य डिज़ाइन टोकन में परिवर्तित करता है:

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

इन मानों को अपने एक्सटेंशन की मूल स्टाइलिंग के रूप में उपयोग करें ताकि आपका iframe होस्ट थीम से मेल खाए।

लाइव थीम अपडेट

जब आपका आईफ्रेम खुला हो, तब पैरेंट chastify:ext:ui इवेंट भेज सकता है।
यदि आप लाइव थीम सिंक चाहते हैं, तो उस इवेंट को सुनें और स्थानीय थीम स्थिति को अपडेट करें।

लाइट/डार्क थीम हैंडलिंग, कंट्रास्ट उदाहरण और टेलविंड पैटर्न के विस्तृत विवरण के लिए, Iframe थीमिंग देखें।

ऑटो रीसाइज़ सपोर्ट

startAutoResizeToParent(...) का उपयोग करें ताकि पैरेंट आपके कंटेंट के अनुसार iframe का आकार बदल सके।

यह क्यों महत्वपूर्ण है:

• आईफ्रेम के अंदर स्क्रॉल ट्रैप को रोकता है।
• सेटअप मोडल और एक्सटेंशन पेजों का आकार सही बनाए रखता है।
• यह उन गतिशील अनुभागों के लिए अच्छी तरह काम करता है जो फैलते/सिकुड़ते हैं।

सामान्य गलतियां

• गलत targetOrigin (यह bridge.parentOrigin से मेल खाना चाहिए)।
• nonce कोड गायब है या पुराना है।
• ChastifyBridgeClient के लिए अनमाउंट करते समय destroy() को कॉल नहीं किया जा रहा है।
• session.get की क्षमताओं की पहले जांच किए बिना असमर्थित क्रियाएं भेजना।

संदर्भ फ़ाइलें

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