Zum Hauptinhalt springen

Probieren Sie die Extensions Developer API aus.

Nutzen Sie diese Anleitung, wenn Sie eine Chastify-Erweiterung erstellen, eine iFrame-Erweiterungsseite hosten oder die Developer API von Ihrem eigenen Backend aus aufrufen möchten.

Diese Seite ist der Ausgangspunkt: Welchen Modus wählen, was zuerst anrufen und wie es weitergeht.

Für konkrete Funktionen der Erweiterung, wie z. B. das Entsperren von Blockern, regelmäßig erforderliche Aktionen, Belohnungen und Bestrafungen, siehe Extension API Features.

tipp

Sie möchten lediglich Ihr eigenes Schloss steuern?

Wenn Sie keine öffentliche Erweiterung erstellen müssen, ist die Seite Externe API & Programme der einfachste Einstieg. Sie erstellen einfach ein DEV-Token und rufen einfache REST-Endpunkte auf – keine Erweiterungseinrichtung, kein iFrame, keine Sitzungsverwaltung erforderlich. Unterstützt werden das Hinzufügen/Entfernen von Zeit, das Einfrieren, Aufgaben, Gerätebefehle und vieles mehr.

Wozu dient diese API?​

Mit der Extensions Developer API können Sie Erweiterungen von Drittanbietern erstellen, die innerhalb von Chastify-Sperrsitzungen ausgeführt werden.

Damit können Sie:

  • Sitzungs- und Sperrkontext lesen (session.get für Erweiterungen, /api/apps/v1/session für Ihre eigene Sperrautomatisierung)
  • Lesen Sie die Erweiterungsdaten pro Sperrsitzung (state.get) und schreiben Sie sie von Ihrem Backend (PUT/PATCH /state).
  • Speichern Sie die der Erweiterung gehörenden Bilddateien im von Chastify verwalteten R2-Speicher (files.*).
  • Füge UI-Aktionen für Erweiterungskarten hinzu (metadata.homeActions)
  • Ablauf zum Entsperren von Toren mit Entsperrblockern, die von Erweiterungen verwaltet werden (metadata.unlockBlockers)
  • Auslösen von Sperraktionen über ein vertrauenswürdiges Backend (Zeit hinzufügen/entfernen, Einfrieren/Auftauen, Ändern von Einstellungen)
  • Aufgaben und Hygieneaktionen auslösen (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Regelmäßige Aktionen mit Zählern/Kadenzunterstützung einreichen
  • Sende unterstützte Gerätebefehle, sofern verfügbar
  • Schreibe benutzerdefinierte Erweiterungsprotokolleinträge, um den Verlauf zu sperren

Was Sie bauen können​

Die richtige Funktionsauswahl hängt davon ab, wo Vertrauen herrscht.

Reine Frontend-iFrame-Erweiterungen ermöglichen die Erstellung von UI-First-Erlebnissen, die keine Trusted Lock Mutation benötigen:

  • Einrichtungsseiten, die die Erweiterungskonfiguration erfassen
  • Dashboards, die den Sitzungskontext lesen
  • Benutzeroberflächen für Rätsel, Checklisten oder Spiele, die den Sitzungsstatus auslesen und den verifizierten Fortschritt über ein Backend senden.
  • Medienbasierte Abläufe, die bereits von Chastify gespeicherte Erweiterungsdateien lesen
  • Startseiten-Einstiegspunkte, die Ihren iFrame mit einer bestimmten Absicht öffnen

Serverbasierte Erweiterungen können Funktionen entwickeln, die Sperren beeinflussen, da Ihr Backend die Ergebnisse überprüft, bevor privilegierte APIs aufgerufen werden:

  • Aufgaben- oder Gewohnheitssysteme mit Freischaltbedingungen
  • Tägliche oder wöchentliche Vorgaben mit festgelegten Strafen bei Nichterfüllung der Frist
  • Spiele, die Erfolg belohnen oder Misserfolg mit Änderungen der Sperrzeit bestrafen
  • Verifizierungsabläufe, die Entsperrblocker nach serverseitiger Validierung aufheben
  • Gerätesteuerungs-Begleitabläufe unter Verwendung unterstützter Gerätebefehle
  • Webhook-/Datenbank-Workflows, die den Erweiterungsstatus außerhalb des iFrames speichern

Externe Programme dienen der privaten Automatisierung Ihres eigenen aktiven Schlosses:

  • Lokale Skripte
  • Persönliche Dashboards
  • Automatisierungstools, die einen benutzerweiten DEV-Schlüssel verwenden

Wählen Sie Ihren Modus​

Wählen Sie einen dieser Modi:

  1. Hosted iframe extension: Hosten Sie eine statische iFrame-Benutzeroberfläche auf Cloudflare Pages oder einem ähnlichen Dienst. Verwenden Sie die Bridge für Einrichtung, Sitzungskontext und sichere Lesezugriffe. Verwenden Sie diesen Modus nicht allein für Statusänderungen, Belohnungen, Strafen, Freischaltungen oder den Fortschritt vertrauenswürdiger Anforderungen.
  2. Server-backed extension: Hosten Sie die iFrame-Benutzeroberfläche und betreiben Sie Ihr eigenes Backend. Der iFrame sendet seinen Startcode mainToken an Ihr Backend, welches daraufhin die Erweiterungs-API Chastify mit einem anwendungsbezogenen Entwickler-API-Schlüssel und x-chastify-main-token aufruft. Verwenden Sie diesen Modus für privilegierte Aktionen, das Entsperren von Sperren, vertrauenswürdigen Fortschritt, Belohnungen, Strafen, Webhooks und externe Datenbanken.
  3. External API & Programs: Verwenden Sie einen benutzerweiten DEV-Schlüssel für Skripte, lokale Programme oder Automatisierungen, die Ihre eigene aktive Sperre steuern. Dies ist nicht der Modus für Drittanbieter, die Ihre Erweiterung installieren.

Für schnelle Tests empfiehlt sich der iFrame-Modus für die Benutzeroberfläche und sichere Lesezugriffe. Ein Backend sollte erst implementiert werden, wenn Statusänderungen, vertrauenswürdige Belohnungen, Zeitänderungen, geplanter Fortschritt von Anforderungen oder das Abschließen von Entsperrblockern implementiert sind.

vorsicht

Der Code eines iFrames stellt keine Vertrauensgrenze dar. Alles, was für den iFrame sichtbar ist, einschließlich Hash-Payloads und Starttoken, kann vom Benutzer eingesehen und wiedergegeben werden.

Die ersten 10 Minuten (Iframe-Modus)​

  1. location.hash-Nutzdaten aus dem geöffneten iFrame Chastify gelesen.
  2. Erstelle eine Brückenanforderung für session.get.
  3. Antwort mit type: "chastify:ext:resp" und ok: true bestätigen.
  4. Teststatus liest mit state.get.
  5. Füge automatische Größenanpassung und Unterstützung für Designs hinzu, damit sich der iFrame in der Benutzeroberfläche korrekt verhält.

Die Unterstützung von Themes ist Teil eines produktionsreifen iFrames. Chastify übergibt ui-Werte im Start-Hash und sendet Live-Theme-Updates, solange der iFrame geöffnet ist. Beispiele für helle/dunkle Designs und kontrastsichere Tailwind-Muster finden Sie unter Iframe-Themes.

Erforderliche Nutzlastwerte:

  • bridge.nonce
  • bridge.parentOrigin
  • sessionId
  • lockId

Beispiel einer Brückenanfrage:

{
  "type": "chastify:ext:req",
  "v": 1,
  "id": "request-id", // unique id per request
  "nonce": "nonce-from-hash",
  "action": "session.get",
  "payload": {}
}

Beispiel einer Brückenantwort:

{
  "type": "chastify:ext:resp",
  "v": 1,
  "id": "request-id",
  "ok": true,
  "data": {}
}

Wichtigste Maßnahmen, die man zuerst lernen sollte​

  • session.get
  • state.get
    Lesen Sie den vom Erweiterungsmodul verwalteten JSON-Speicher für die Sperrsitzung. Schreiben Sie den Status von Ihrem Backend mit den Anmeldeinformationen der Entwickler-API.
  • files.capabilities, files.list, files.get Verwenden Sie Dateispeicherzugriffe für Binärmedien wie Puzzlebilder oder generierte Vorschauen. Speichern Sie Datei-IDs im Backend-Zustand und aktualisieren Sie anschließend signierte URLs mit files.get.
  • metadata.get Lesen Sie Sperr- und Entsperrungsblocker sowie Aktionen/Absichten der Erweiterungskarten-Startseite.
  • regularActions.get

Sitzungsänderungen wie Statusänderungen, reguläre Aktionsübermittlungen, Datei-Uploads/Löschungen zur Laufzeit, Zeitänderungen, Aktualisierungen von Entsperrblockern, Aufgabenabschluss, Hygiene-Starts und Gerätebefehle müssen von Ihrem Backend mit einem Entwickler-API-Schlüssel aufgerufen werden. Browser-iFrame-Code wird für diese Aktionen nicht als vertrauenswürdig eingestuft.

Vollständige API-URLs (unterstützt)​

Basisdomäne: https://chastify.net

Erweiterungssitzungs-APIs (/api/extensions/*)​

Diese Routen haben unterschiedliche Zugriffsmodi. Behandeln Sie die gesamte /api/extensions/*-Oberfläche nicht als iframe-sicher.

Sichere iFrame-Brückenrouten werden nach postMessage-Brückenanfragen über das übergeordnete Chastify geleitet:

  • GET https://chastify.net/api/extensions/sessions/:sessionId
  • GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId

Für Routen, die ausschließlich über das Backend laufen und installierte Erweiterungen nutzen, ist ein anwendungsbezogener Entwickler-API-Schlüssel sowie das iFrame-Starttoken erforderlich:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH
info

Dieses Zwei-Token-Modell bindet eine Backend-Anfrage sowohl an den Erweiterungsentwickler (Authorization) als auch an die aktuell geöffnete Erweiterungssitzung (x-chastify-main-token).

  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • PUT https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/regular-actions/config
  • POST https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • POST https://chastify.net/api/extensions/sessions/:sessionId/files
  • DELETE https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId
  • POST https://chastify.net/api/extensions/sessions/:sessionId/logs/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/notifications/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/device-command
  • POST https://chastify.net/api/extensions/sessions/:sessionId/action
  • POST https://chastify.net/api/extensions/sessions/:sessionId/requirements/progress

Backend-Token-APIs (/api/apps/v1/*)​

Verwenden Sie Authorization: Bearer <user-wide DEV token>. Diese Endpunkte verwalten die aktiven Sperrsitzungen des Token-Inhabers und sind für externe API-Skripte/Programme vorgesehen, nicht für installierte Erweiterungen von Drittanbietern.

  • GET https://chastify.net/api/apps/v1/session
  • GET https://chastify.net/api/apps/v1/state
  • PUT https://chastify.net/api/apps/v1/state
  • PATCH https://chastify.net/api/apps/v1/state
  • GET https://chastify.net/api/apps/v1/metadata
  • PATCH https://chastify.net/api/apps/v1/metadata
  • POST https://chastify.net/api/apps/v1/action
  • POST https://chastify.net/api/apps/v1/lock/apply-time
  • POST https://chastify.net/api/apps/v1/lock/freeze
  • POST https://chastify.net/api/apps/v1/lock/unfreeze
  • POST https://chastify.net/api/apps/v1/logs/custom

Iframe-Brückenbefehle​

Die Nutzdaten der Bridge-Befehle werden per iFrame (chastify:ext:req) gesendet und vom übergeordneten Frame Chastify weitergeleitet. Die Bridge ist absichtlich auf sichere/Sitzungs-UI-Operationen beschränkt.

  • session.get -> GET https://chastify.net/api/extensions/sessions/:sessionId
  • state.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • files.capabilities -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • files.list -> GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • files.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId mit { "fileId": "file_record_id" }
  • metadata.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • regularActions.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions

Sitzungsänderungs-Endpunkte sind direkte Backend-API-Aufrufe, keine iFrame-Bridge-Befehle. Dies umfasst Statusänderungen, reguläre Aktionsübermittlungen und das Hochladen/Löschen von Dateien zur Laufzeit, da der iFrame-Code vom Benutzer gesteuert werden kann.

Beispiele für die Backend-Session-API​

Ihr Backend muss beide Header für privilegierte Aufrufe installierter Erweiterungen senden:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

Beispiele für Backend-Aktionen:

  • metadata.patch -> PATCH /api/extensions/sessions/:sessionId/metadata
  • regularActions.submit -> POST /api/extensions/sessions/:sessionId/regular-actions
  • files.upload -> POST /api/extensions/sessions/:sessionId/files
  • files.delete -> DELETE /api/extensions/sessions/:sessionId/files/:fileId
  • lock.applyTime -> POST /api/extensions/sessions/:sessionId/action mit { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action mit { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action mit { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action mit { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action mit { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action mit { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action mit { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action mit { "name": "pillory.end", "params": {} }
  • device.command -> POST /api/extensions/sessions/:sessionId/device-command
  • logs.custom -> POST /api/extensions/sessions/:sessionId/logs/custom
  • notifications.custom -> POST /api/extensions/sessions/:sessionId/notifications/custom
  • requirements.progress -> POST /api/extensions/sessions/:sessionId/requirements/progress

Token-, Gültigkeitsbereichs-, Widerrufs- und Prüfverhalten​

Verwenden Sie das richtige Token für die richtige Vertrauensgrenze.

warnung

API-Schlüssel für Entwickler sind geheim. Sollte ein solcher Schlüssel in Browsercode gelangen, muss er umgehend widerrufen und die Umgebungsvariable im Backend entsprechend angepasst werden.

Iframe-Starttoken (mainToken)​

  • Wird im iFrame-Hash übermittelt, wenn ein Benutzer eine Seite mit einer installierten Erweiterung öffnet.
  • Vom Browser bewusst sichtbar. Es identifiziert die geöffnete Erweiterungssitzung, ist aber kein Backend-Geheimnis.
  • Nur kurz gültig. Die aktuellen Start-Tokens verfallen nach 10 Stunden; aktualisieren Sie sie, indem Sie die Erweiterungsseite erneut öffnen.
  • Wird als x-chastify-main-token benötigt, wenn Ihr Backend Sitzungsrouten für installierte Erweiterungen aufruft, damit Chastify die Backend-Anfrage an den Benutzer/die Sitzung binden kann, der/die die Erweiterung geöffnet hat.
  • Darf nicht allein verwendet werden, um Zeitänderungen zu autorisieren, die Sperre aufzuheben, Aufgaben abzuschließen, Gerätebefehle auszuführen, Laufzeit-Uploads/Löschungen durchzuführen, benutzerdefinierte Protokolle zu erstellen oder benutzerdefinierte Benachrichtigungen zu erstellen.

App-bezogener Entwickler-API-Schlüssel​

  • Erstellt aus der Entwickler-UI für eine Erweiterungs-App.
  • Dieses Geheimnis ist nur im Backend zugänglich. Es darf niemals in iFrame-JavaScript, in Bundles mobiler Apps, in der Konfiguration statischer Hosting-Dienste oder in für Browser lesbaren Protokollen verwendet werden.
  • Wird mit Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY und x-chastify-main-token verwendet.
  • Installierte Erweiterungssitzungs-APIs können nur für Sitzungen aufgerufen werden, die mit der Erweiterungs-App und dem Starttoken übereinstimmen.
  • Läuft nicht automatisch ab. Widerrufen Sie die Berechtigung umgehend, falls sie offengelegt wurde, und aktualisieren Sie Ihre Backend-Umgebungsvariable.

Benutzerweiter Entwickler-API-Schlüssel​

  • Erstellt über die Entwickler-Benutzeroberfläche, ohne eine Erweiterungs-App auszuwählen.
  • Nur im Backend verfügbarer geheimer Eintrag für /api/apps/v1/*.
  • Steuert die aktuellen/zukünftigen aktiven Sperrsitzungen des Schlüsselbesitzers.
  • Kann nicht als Backend-Anmeldeinformation einer installierten Drittanbietererweiterung verwendet werden.

Widerruf​

  • Widerrufene Entwickler-API-Schlüssel autorisieren keine neuen Anfragen mehr.
  • Entzogene Schlüssel können über die Entwickler-Benutzeroberfläche endgültig gelöscht werden.
  • Neue iFrame-Starts erhalten neue Starttoken. Speichern Sie mainToken nicht als langfristige Anmeldeinformation.

Aufgabenbereiche und Rollen​

  • Die Anwendungsbereiche von Erweiterungen beschreiben, was die App anfordern darf.
  • Sichere iFrame-Bridge-Aufrufe sind beschränkt auf UI-Bootstrap, Sitzungslesevorgänge, Statusabfragen von Erweiterungen, Metadatenlesevorgänge, reguläre Aktionslesevorgänge und Dateilesevorgänge.
  • Privilegierte Änderungen an installierten Sitzungen erfordern Backend-Anmeldeinformationen, selbst wenn die Erweiterung über einen passenden Gültigkeitsbereich verfügt.
  • Rollenabhängige Aktionen können weiterhin abgelehnt werden, je nachdem, ob der Start einem Träger oder Schlüsselinhaber zusteht.

Prüfung und Grenzwerte​

  • Die Metadaten zum zuletzt verwendeten Entwickler-API-Schlüssel werden aktualisiert, sobald die Schlüssel verwendet werden.
  • Privilegierte Aktionsrouten sind ratenbegrenzt und geben explizite Fehler wie server_credentials_required oder user_wide_dev_key_required zurück, wenn der falsche Anmeldeinformationstyp verwendet wird.
  • Benutzerdefinierte Protokolle schreiben sichtbare Sperrverlaufseinträge.
  • Benutzerdefinierte Benachrichtigungen erstellen Chastify-Benachrichtigungen für das angeforderte Ziel.
  • Die vollständige Überwachung jeder Mutation einer privilegierten Erweiterung wird als Maßnahme zur Produktionshärtung protokolliert.

Unterstützte Befehlswerte​

/api/extensions/sessions/:sessionId/action und /api/apps/v1/action​

name unterstützt:

  • add_time
  • remove_time
  • freeze
  • pillory
  • unfreeze
  • toggle_freeze
  • settings.patch
  • task.assign
  • task.start_timer
  • task.complete
  • hygienic_unlock.start
  • pillory.end

Handlungseinschränkungen:

  • Für die Ausführung von Aufgaben muss die Erweiterung/das Modul „Aufgaben“ auf dem Schloss aktiviert sein.
  • hygienic_unlock.start erfordert aktivierte hygienische Öffnung und keine aktive Hygienesitzung.

session.get Sperrdatenhelfer​

session.get / GET /api/apps/v1/session enthält außerdem lockData mit laufzeitfreundlichen Booleschen Werten, Zahlen und Zeichenketten für Regel-Engines.

Beispiele:

  • Boolesche Werte: frozen, unlockable, trusted, taskAssigned (true, falls ein offener TaskRun existiert)
  • Nummern: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • Zeichenketten: lockTitle, Träger-/Schlüsselhalterprofilfelder

Datenschutz:

  • wearerLastSeenTimestamp und keyholderLastSeenTimestamp werden zu null, wenn der Benutzer den Online-Status deaktiviert (showOnlineStatus === false).

Gerätebefehle​

Erweiterungssitzungen können den sitzungsbasierten Endpunkt verwenden:

POST /api/extensions/sessions/:sessionId/device-command

Externe Programme mit einem DEV-Token können den einfacheren v1-Endpunkt verwenden (keine Sitzungs-ID erforderlich):

POST /api/apps/v1/device-command

Beide akzeptieren denselben Anfragetext und geben dieselbe Antwort zurück. Weitere Informationen finden Sie unter Externe API & Programme.

Einrichtungsseite (optional, empfohlen)​

Falls Ihre Erweiterung über eine Einrichtungs-/Konfigurations-UI verfügt:

  1. Der übergeordnete Server sendet chastify:ext:setup:init (gespeicherte Konfiguration + Kontext).
  2. Ihr Setup-iFrame gibt Aktualisierungen mit chastify:ext:setup:config zurück.
  3. Das übergeordnete System kann die aktuelle Konfiguration mit chastify:ext:setup:get_config anfordern.

Backend-Token-Ablauf (Wenn serverseitige Aufrufe erforderlich sind)​

Für einfache Skripte und externe Programme verwenden Sie ein benutzerweites DEV-Token von der Entwickler-API-Seite. Siehe Externe API & Programme.

Standardablauf im Erweiterungs-iFrame-Modus:

  1. Chastify gibt ein kurzlebiges, im Browser sichtbares Starttoken für die aktive Erweiterungssitzung aus.
  2. Das Starttoken ist als mainToken in die Hash-Payload des iFrames eingebettet.
  3. Ihr iFrame leitet mainToken an Ihr Backend weiter.
  4. Ihr Backend ruft https://chastify.net/api/extensions/sessions/:sessionId/* mit Authorization: Bearer <app-scoped Developer API key> und x-chastify-main-token: <mainToken> auf.

Senden Sie keine Entwickler-API-Schlüssel an iFrame-/Browsercode. mainToken identifiziert die geöffnete Erweiterungssitzung; es handelt sich nicht um ein Backend-Geheimnis und es kann nicht allein für privilegierte Aktionen verwendet werden.

Manuelles Fallback:

  • Falls Sie das iFrame-Starttoken explizit von der Benutzeroberfläche des Erstanbieters abrufen/drehen müssen, rufen Sie GET https://chastify.net/api/extensions/sessions/:sessionId/auth auf.

Verwenden Sie den Backend-Modus, wenn Sie geplante Jobs, Webhooks oder Automatisierungen benötigen, während die Seite Chastify nicht geöffnet ist. Aktuell installierte Erweiterungssitzungsänderungen erfordern weiterhin ein gültiges 10-Stunden-iFrame-Starttoken. Daher sollten unbeaufsichtigte Jobs den ausstehenden Nachweis speichern und beim nächsten gültigen Start übermitteln, es sei denn, Sie verwenden einen Server-Flow eines Herstellers/einer integrierten Lösung, der für die Hintergrundausführung ausgelegt ist.

info

Für einen vollständig unbeaufsichtigten Produktionsbetrieb empfiehlt sich ein integrierter/eigener Server-Workflow oder das Warten auf explizite Hintergrund-Erweiterungsberechtigungen. App-bezogene Session-APIs sind derzeit an ein Launch-Token gebunden.

Backend vs Cloudflare Pages (Kein Server)​

Verwenden Sie Cloudflare Pages (ohne Backend-Server), wenn:​

  • Sie wünschen sich die einfachste und günstigste Lösung (kostenloses Hosting möglich).
  • UI-gesteuerte Aktionen sind nur dann erforderlich, wenn sich der Benutzer aktiv auf Ihrer Erweiterungsseite befindet.
  • Sie benötigen keine serverseitig persistenten Erweiterungsstatus-Schreibvorgänge.
  • Sie erstellen schnell Prototypen oder entwickeln schlanke Erweiterungen.

Lokales Testbeispiel (PowerShell):

cloudflared tunnel --url http://localhost:5174

Verwenden Sie die generierte öffentliche URL während des Tests als Ihre iFrame-URL.

Verwenden Sie einen Backend-Server, wenn:​

  • Sie benötigen geplante Aufgaben (ähnlich wie bei Cronjobs).
  • Sie benötigen Webhooks oder externe Integrationen.
  • Sie benötigen Automatisierung/Hintergrundverarbeitung, wenn sich niemand auf der Erweiterungsseite befindet.
  • Sie benötigen servergesteuerte Workflows, die kontinuierlich laufen müssen.

Wichtige Einschränkung ohne Backend:

  • Keine Hintergrundausführung. Ihre Erweiterung kann nur dann Aktionen ausführen, wenn ein Benutzer den Erweiterungs-iFrame geöffnet hat und mit ihm interagiert.

Häufige Probleme​

  • 403 extension_not_enabled: Die Erweiterung ist für dieses Schloss nicht aktiviert.
  • 409 lock_ended: Die Sperre ist nicht mehr aktiv.
  • 429: Ratenlimit erreicht.
  • Keine Antworten im iFrame: Überprüfen Sie nonce, targetOrigin (parentOrigin) und die zulässigen Ursprünge.

Nächste Anleitungen​