Iframe-thema's

Chastify stuurt thema-informatie naar iframe-extensies, zodat uw gebruikersinterface overeenkomt met de vergrendelpagina waarin deze is ingesloten.

Ga er niet vanuit dat de gebruiker een donker thema gebruikt. Je extensie kan worden geopend in lichte, donkere, aangepaste, transparante en contrastrijke thema's.

tip

De veiligste standaardmethode is om de iframe-payload ui als de bron van waarheid te beschouwen voor de pagina-achtergrond, tekstkleur en randkleur, en vervolgens uw eigen leesbare panelen en badges af te leiden van ui.isDark.

Thema-payload

Wanneer Chastify uw iframe opent, voegt het een URI-gecodeerde JSON-payload toe aan location.hash.

De payload bevat ui:

{
  "bridge": {
    "v": 1,
    "nonce": "request-nonce",
    "parentOrigin": "https://chastify.net"
  },
  "sessionId": "extension-session-id",
  "lockId": "lock-id",
  "ui": {
    "isDark": true,
    "bg": "rgb(10, 10, 10)",
    "text": "#e5e7eb",
    "border": "#27272a"
  }
}

Betekenis van de velden:

ui.isDark: of de hostpagina momenteel een donker thema gebruikt.
ui.bg: pagina-/oppervlakachtergrond van de host. Dit kan een kleur of een complexe CSS-achtergrond zijn.
ui.text: primaire leesbare tekstkleur.
ui.border: randkleur die overeenkomt met het thema van de host.

pas op

ui.bg kan een volledige CSS-achtergrondstring zijn, niet alleen een hexadecimale kleur. Gebruik het als een CSS background-waarde, niet als een waarde die je handmatig parseert.

Ontleed de hash

type ChastifyThemePayload = {
  ui?: {
    isDark?: boolean;
    bg?: string;
    text?: string;
    border?: string;
  };
};

export function parseHashPayload(): ChastifyThemePayload | null {
  const raw = window.location.hash.startsWith("#")
    ? window.location.hash.slice(1)
    : window.location.hash;

  if (!raw) return null;

  try {
    return JSON.parse(decodeURIComponent(raw));
  } catch {
    return null;
  }
}

Minimale CSS-variabelen

Converteer de payload eenmalig bij het opstarten naar CSS-variabelen:

const payload = parseHashPayload();
const ui = payload?.ui ?? {};
const isDark = ui.isDark !== false;

document.documentElement.style.setProperty("--chastify-bg", ui.bg || (isDark ? "#040711" : "#f8fafc"));
document.documentElement.style.setProperty("--chastify-text", ui.text || (isDark ? "#e5e7eb" : "#0f172a"));
document.documentElement.style.setProperty("--chastify-border", ui.border || (isDark ? "#27272a" : "#e2e8f0"));
document.documentElement.dataset.themeMode = isDark ? "dark" : "light";

Gebruik deze variabelen in de shell van je app:

html,
body,
#root {
  min-height: 100%;
  margin: 0;
}

body {
  background: var(--chastify-bg);
  color: var(--chastify-text);
}

.panel {
  border: 1px solid var(--chastify-border);
}

React-voorbeeld

import { useMemo } from "react";

function getTheme(payload: any) {
  const ui = payload?.ui ?? {};
  const isDark = ui.isDark !== false;

  return {
    isDark,
    pageStyle: {
      background: ui.bg || (isDark ? "#040711" : "#f8fafc"),
      color: ui.text || (isDark ? "#e5e7eb" : "#0f172a"),
    } satisfies React.CSSProperties,
    panelClass: isDark
      ? "border-white/10 bg-black/35 text-slate-100"
      : "border-slate-200 bg-white/85 text-slate-950 shadow-sm",
    mutedClass: isDark ? "text-slate-400" : "text-slate-600",
    badgeClass: isDark
      ? "bg-sky-400/15 text-sky-200"
      : "bg-sky-50 text-sky-900 ring-1 ring-sky-200",
  };
}

export function ExtensionApp({ payload }: { payload: any }) {
  const theme = useMemo(() => getTheme(payload), [payload]);

  return (
    <main style={theme.pageStyle} className="min-h-screen p-4">
      <section className={`rounded-2xl border p-4 ${theme.panelClass}`}>
        <h1 className="text-xl font-bold">My Extension</h1>
        <p className={`mt-2 text-sm ${theme.mutedClass}`}>
          This text stays readable on light and dark Chastify themes.
        </p>
        <span className={`mt-3 inline-flex rounded-full px-3 py-1 text-xs font-semibold ${theme.badgeClass}`}>
          Connected
        </span>
      </section>
    </main>
  );
}

Rugwindpatroon

Als je Tailwind gebruikt, maak dan een vertakking vanuit ui.isDark voor elk oppervlak dat tekst bevat.

const isDarkTheme = payload?.ui?.isDark !== false;

const panelClass = isDarkTheme
  ? "border-white/10 bg-black/30 text-slate-100"
  : "border-slate-200 bg-white/85 text-slate-950 shadow-sm";

const successClass = isDarkTheme
  ? "border-emerald-300/20 bg-emerald-400/10 text-emerald-100"
  : "border-emerald-500/25 bg-emerald-50 text-emerald-950";

const errorClass = isDarkTheme
  ? "border-rose-300/20 bg-rose-400/10 text-rose-100"
  : "border-rose-500/25 bg-rose-50 text-rose-950";

Gebruik de gekozen klassen op de plek waar de tekst wordt weergegeven:

<div className={`rounded-xl border px-3 py-2 text-sm ${result.ok ? successClass : errorClass}`}>
  <div className="font-semibold">{result.title}</div>
  <div className="mt-1 opacity-85">{result.message}</div>
</div>

Live thema-updates

De ouder kan live thema-updates verzenden terwijl uw iframe geopend is:

type UiUpdateMessage = {
  type: "chastify:ext:ui";
  v: 1;
  nonce: string;
  ui: {
    isDark?: boolean;
    bg?: string;
    text?: string;
    border?: string;
  };
};

Luister naar dat bericht en controleer de nonce:

const nonce = payload.bridge.nonce;
const parentOrigin = payload.bridge.parentOrigin;

window.addEventListener("message", (event) => {
  if (event.origin !== parentOrigin) return;

  const msg = event.data as Partial<UiUpdateMessage>;
  if (msg.type !== "chastify:ext:ui" || msg.v !== 1) return;
  if (msg.nonce !== nonce) return;

  applyTheme(msg.ui);
});

Veelgemaakte fouten

Het hardcoderen van text-white of de bleke kleur text-*-100 in kaarten zonder een alternatief met een licht thema.
De pagina-achtergrond is wel vormgegeven, maar de geneste kaarten, badges, voortgangsringen en resultatenfeeds zijn vergeten.
ui.bg wordt behandeld als een eenvoudige hexadecimale kleur. Het kan een verloop of een door de browser genormaliseerde CSS-achtergrondkleur zijn.
Het gebruik van standaard formulierbesturingselementen zonder zowel de achtergrond- als de tekstkleur in te stellen. Selectieopties kunnen onleesbaar worden in donkere thema's.
Ervan uitgaande dat een iframe-herlaadactie nodig is bij themawijzigingen. Luister naar chastify:ext:ui voor live updates.

waarschuwing

Thema-gegevens zijn uitsluitend presentatiegegevens. Gebruik ze niet voor autorisatie, vertrouwensbeslissingen, ontgrendelingslogica, beloningen, straffen of backend-sessie-identificatie.

Checklist

Voordat u uw iframe-extensie publiceert:

Test het lichte thema.
Test het donkere thema.
Test een aangepast thema indien beschikbaar.
Controleer of alle kaarten, knoppen, badges, formulierbesturingselementen, voortgangsindicatoren en resultaatberichten een leesbaar contrast hebben.
Controleer of de tekst nog steeds op het mobiele scherm past.
Controleer of de iframe automatisch van formaat verandert na wijzigingen in het thema of de inhoud.

Volgende: Iframe Quickstart of API-voorbeelden.

Thema-payload​

Ontleed de hash​

Minimale CSS-variabelen​

React-voorbeeld​

Rugwindpatroon​

Live thema-updates​

Veelgemaakte fouten​

Checklist​