Ga naar hoofdinhoud

Probeer de Extensions Developer API.

Gebruik deze handleiding als u een Chastify-extensie wilt bouwen, een iframe-extensiepagina wilt hosten of de ontwikkelaars-API vanuit uw eigen backend wilt aanroepen.

Deze pagina is het uitgangspunt: welke modus te kiezen, wie als eerste te bellen en waarheen te gaan.

Voor concrete uitbreidingsfunctionaliteiten zoals het ontgrendelen van blokkades, regelmatig vereiste acties, beloningen en straffen, zie Extension API Features.

tip

Wil je gewoon je eigen slot bedienen?

Als u geen openbare extensie hoeft te bouwen, is de pagina Externe API & Programma's de gemakkelijkste manier om te beginnen. U maakt gewoon een DEV-token aan en roept eenvoudige REST-eindpunten aan — geen extensie-configuratie, geen iframe, geen sessiebeheer vereist. Het ondersteunt het toevoegen/verwijderen van tijd, bevriezen, taken, apparaatopdrachten en meer.

Waarvoor dient deze API?

Met de Extensions Developer API kunt u extensies van derden bouwen die binnen Chastify-vergrendelingssessies draaien.

Hiermee kunt u:

  • Lees de sessie- en vergrendelingscontext (session.get voor extensies, /api/apps/v1/session voor uw eigen vergrendelingsautomatisering).
  • Lees extensie-eigendomsgegevens per vergrendelingssessie (state.get) en schrijf deze vanuit uw backend (PUT/PATCH /state).
  • Sla afbeeldingsbestanden die eigendom zijn van de extensie op met behulp van de door Chastify beheerde R2-opslag (files.*).
  • Voeg extensie-UI-acties toe aan vergrendelingskaarten (metadata.homeActions)
  • Poortontgrendelingsproces met extensie-eigendom ontgrendelingsblokkers (metadata.unlockBlockers)
  • Activeer vergrendelingsacties vanuit een vertrouwde backend (tijd toevoegen/verwijderen, bevriezen/ontvriezen, instellingen wijzigen).
  • Activeer taak- en hygiëneacties (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Dien regelmatig acties in met tellers/frequentieondersteuning.
  • Verzend ondersteunde apparaatopdrachten indien beschikbaar.
  • Schrijf aangepaste logboekvermeldingen voor extensies om de geschiedenis te vergrendelen.

Wat je kunt bouwen

De juiste set functies hangt af van waar het vertrouwen ligt.

Frontend-only iframe-extensies kunnen UI-first ervaringen creëren die geen vertrouwde vergrendelingsmutatie vereisen:

  • Instellingenpagina's voor het verzamelen van extensieconfiguraties
  • Dashboards die de sessiecontext lezen
  • Puzzel-, checklist- of game-UI's die de sessiestatus uitlezen en de geverifieerde voortgang via een backend verzenden.
  • Mediagebaseerde flows die extensiebestanden lezen die al zijn opgeslagen door Chastify
  • Startpagina-actie-ingangspunten die uw iframe openen met een intentie

Servergestuurde extensies kunnen functionaliteiten creëren die van invloed zijn op vergrendelingen, omdat uw backend de resultaten verifieert voordat geprivilegieerde API's worden aangeroepen:

  • Taak- of gewoontesystemen met ontgrendelingsvereisten
  • Dagelijkse of wekelijkse verplichtingen met vastgestelde sancties bij het niet naleven ervan.
  • Spellen die succes belonen of falen bestraffen met veranderingen in de lock-tijd.
  • Verificatieprocessen die blokkades opheffen na validatie aan de serverzijde.
  • Begeleidende workflows voor apparaatbesturing met behulp van ondersteunde apparaatcommando's
  • Webhook-/databaseworkflows die de extensiestatus buiten de iframe houden.

Externe programma's zijn bedoeld voor privéautomatisering van uw eigen actieve slot:

  • Lokale scripts
  • Persoonlijke dashboards
  • Automatiseringstools die een gebruikersbrede DEV-sleutel gebruiken

Kies uw modus

Kies een van deze modi:

  1. Hosted iframe extension: host een statische iframe-gebruikersinterface op Cloudflare Pages of een vergelijkbare service. Gebruik de bridge voor configuratie, sessiecontext en veilige leesbewerkingen. Gebruik deze modus niet alleen voor het schrijven naar de status, beloningen, straffen, het voltooien van ontgrendelingen of de voortgang van vertrouwde vereisten.
  2. Server-backed extension: host de iframe-gebruikersinterface en voer je eigen backend uit. De iframe stuurt zijn opstartcode mainToken naar je backend, en je backend roept de Chastify Extension API aan met een app-specifieke Developer API-sleutel plus x-chastify-main-token. Gebruik deze modus voor acties met verhoogde bevoegdheden, het ontgrendelen van blokkades, betrouwbare voortgang, beloningen, straffen, webhooks en externe databases.
  3. External API & Programs: gebruik een gebruikersbrede DEV-sleutel voor scripts, lokale programma's of automatiseringen die uw eigen actieve vergrendeling beheren. Dit is niet de modus voor externe gebruikers die uw extensie installeren.

Als je snel wilt testen, begin dan met de iframe-modus voor de gebruikersinterface en veilige leesbewerkingen. Voeg een backend toe voordat je statuswijzigingen, vertrouwde beloningen, tijdswijzigingen, voortgang van geplande vereisten of het ontgrendelen van blokkades implementeert.

pas op

Iframe-code vormt geen vertrouwensgrens. Alles wat zichtbaar is voor de iframe, inclusief hash-payloads en launch tokens, kan door de gebruiker worden geïnspecteerd en opnieuw worden uitgevoerd.

Eerste 10 minuten (iframe-modus)

  1. Lees de payload location.hash uit het geopende iframe Chastify.
  2. Maak een bridge-verzoek aan voor session.get.
  3. Bevestig het antwoord met type: "chastify:ext:resp" en ok: true.
  4. Teststatus leest met state.get.
  5. Voeg ondersteuning voor automatisch formaat aanpassen en thema's toe, zodat de iframe zich correct gedraagt ​​in de gebruikersinterface.

Themaondersteuning maakt deel uit van een productiegereed iframe. Chastify geeft ui-waarden door in de launch-hash en verzendt live thema-updates zolang het iframe open is. Zie Iframe Theming voor voorbeelden van lichte/donkere thema's en contrastveilige Tailwind-patronen.

Vereiste payloadwaarden:

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

Voorbeeld van een bridge-verzoek:

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

Voorbeeld van een brugreactie:

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

Kernacties die je eerst moet leren

  • session.get
  • state.get
    Lees de JSON-opslag van de extensie voor de vergrendelingssessie. Schrijf de status vanuit uw backend met de inloggegevens van de ontwikkelaars-API.
  • files.capabilities, files.list, files.get Gebruik bestandsopslagleesbewerkingen voor binaire media zoals puzzelafbeeldingen of gegenereerde voorbeelden. Sla bestands-ID's op in de backend-status en vernieuw vervolgens de ondertekende URL's met files.get.
  • metadata.get Lees de blokkeringen voor het ontgrendelen van de vergrendelingssessie en de acties/intenties van de extensiekaart.
  • regularActions.get

Sessiemutaties zoals het schrijven van de status, het verzenden van reguliere acties, het uploaden/verwijderen van bestanden tijdens runtime, tijdswijzigingen, het bijwerken van ontgrendelingsblokkeringen, het voltooien van taken, het starten van hygiëneprocessen en apparaatopdrachten moeten vanuit uw backend worden aangeroepen met een API-sleutel voor ontwikkelaars. Code in browser-iframes wordt niet vertrouwd voor deze acties.

Volledige API-URL's (ondersteund)

Basisdomein: https://chastify.net

Extensiesessie-API's (/api/extensions/*)

Deze routes hebben verschillende toegangsmodi. Beschouw het gehele /api/extensions/*-oppervlak niet als iframe-veilig.

Veilige iframe-brugroutes worden via de Chastify-ouder gerouteerd na postMessage-brugverzoeken:

  • 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

Routes voor geïnstalleerde extensies die alleen toegankelijk zijn via de backend, vereisen een app-specifieke Developer API-sleutel en het iframe-opstarttoken:

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

Dit model met twee tokens koppelt een backend-verzoek aan zowel de extensieontwikkelaar (Authorization) als de momenteel geopende extensiesessie (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-API's (/api/apps/v1/*)

Gebruik Authorization: Bearer <user-wide DEV token>. Deze eindpunten beheren de actieve vergrendelingssessies van de tokenhouder zelf en zijn bedoeld voor externe API-scripts/programma's, niet voor geïnstalleerde extensies van derden.

  • 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 Bridge-opdrachten

De payloads van de bridge-opdracht worden verzonden via een iframe (chastify:ext:req) en doorgestuurd door het parent-proces Chastify. De bridge is opzettelijk beperkt tot veilige/sessie-UI-bewerkingen.

  • 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 met { "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

Sessiemutatie-eindpunten zijn directe API-aanroepen naar de backend, geen iframe-bridge-opdrachten. Dit omvat het schrijven van de status, het indienen van reguliere acties en het uploaden/verwijderen van bestanden tijdens de uitvoering, omdat de iframe-code door de gebruiker kan worden beheerd.

Voorbeelden van API's voor backend-sessies

Uw backend moet beide headers verzenden voor geprivilegieerde aanroepen naar geïnstalleerde extensies:

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

Voorbeelden van backend-acties:

  • 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 met { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action met { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action met { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action met { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action met { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action met { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action met { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action met { "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-, bereik-, intrekkings- en auditgedrag

Gebruik het juiste token voor de juiste vertrouwensgrens.

waarschuwing

Ontwikkelaars-API-sleutels zijn geheim. Als er een sleutel wordt blootgesteld aan browsercode, moet deze onmiddellijk worden ingetrokken en de backend-omgevingsvariabele worden gewijzigd.

Iframe-starttoken (mainToken)

  • Wordt geleverd in de iframe-hash wanneer een gebruiker een pagina van een geïnstalleerde extensie opent.
  • Het is opzettelijk zichtbaar in de browser. Het identificeert de geopende extensiesessie, maar het is geen geheim van de backend.
  • Tijdelijk geldig. De huidige lanceringstokens verlopen na 10 uur; vernieuw ze door de extensiepagina opnieuw te openen.
  • Vereist als x-chastify-main-token wanneer uw backend sessieroutes van geïnstalleerde extensies aanroept, zodat Chastify het backendverzoek kan koppelen aan de gebruiker/sessie die de extensie heeft geopend.
  • Mag niet op zichzelf worden gebruikt om tijdswijzigingen te autoriseren, blokkeringen te ontgrendelen, taken te voltooien, apparaatopdrachten uit te voeren, bestanden tijdens de uitvoering te uploaden/verwijderen, aangepaste logboeken te genereren of aangepaste meldingen te genereren.

App-specifieke ontwikkelaars-API-sleutel

  • Gemaakt vanuit de ontwikkelaarsinterface voor één extensie-app.
  • Dit is een geheim dat alleen voor de backend bedoeld is. Plaats het nooit in iframe-JavaScript, mobiele app-bundels, statische hostingconfiguraties of browserleesbare logbestanden.
  • Te gebruiken met Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY en x-chastify-main-token.
  • API's voor geïnstalleerde extensiesessies kunnen alleen worden aangeroepen voor sessies die overeenkomen met de extensie-app en het opstarttoken.
  • Verloopt niet automatisch. Trek het onmiddellijk in als het wordt blootgesteld en roteer uw backend-omgevingsvariabele.

API-sleutel voor ontwikkelaars die voor de hele gebruiker geldt

  • Gemaakt vanuit de ontwikkelaarsinterface zonder een extensie-app te selecteren.
  • Een geheim dat alleen voor de backend geldt voor /api/apps/v1/*.
  • Hiermee kunt u de huidige en toekomstige actieve slotsessies van de sleutelhouder beheren.
  • Kan niet worden gebruikt als inloggegevens voor een geïnstalleerde extensie van een derde partij.

intrekking

  • Als een API-sleutel voor ontwikkelaars is ingetrokken, kunnen er geen nieuwe aanvragen meer worden geautoriseerd.
  • Ingetrokken sleutels kunnen permanent worden verwijderd via de ontwikkelaarsinterface.
  • Bij het starten van een nieuwe iframe worden nieuwe opstarttokens gebruikt. Bewaar mainToken niet als een permanente authenticatiecode.

Taken en verantwoordelijkheden

  • De scope van een extensie-app beschrijft wat de app mag aanvragen.
  • Veilige iframe bridge-aanroepen zijn beperkt tot UI-bootstrap, sessielezingen, extensie-eigendomsstatus, metadatalezingen, reguliere actielezingen en bestandslezingen.
  • Mutaties van geprivilegieerde geïnstalleerde sessies vereisen backend-referenties, zelfs wanneer de extensie een overeenkomend bereik heeft.
  • Acties die afhankelijk zijn van de rol van de gebruiker kunnen nog steeds worden afgewezen, afhankelijk van of de lancering toebehoort aan een drager of sleutelhouder.

Controle en limieten

  • De metadata van de laatst gebruikte API-sleutel voor ontwikkelaars wordt bijgewerkt wanneer sleutels worden gebruikt.
  • Routes voor geprivilegieerde acties hebben een snelheidsbeperking en retourneren expliciete fouten zoals server_credentials_required of user_wide_dev_key_required wanneer het verkeerde type inloggegevens wordt gebruikt.
  • Aangepaste logboeken schrijven zichtbare vergrendelingsgeschiedenisvermeldingen.
  • Aangepaste notificaties genereren Chastify-notificaties voor het aangevraagde doel.
  • Volledige auditdekking voor elke wijziging van een geprivilegieerde extensie wordt bijgehouden als een beveiligingsmaatregel in de productieomgeving.

Ondersteunde opdrachtwaarden

/api/extensions/sessions/:sessionId/action en /api/apps/v1/action

name ondersteunt:

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

Actiebeperkingen:

  • Voor taakacties is het vereist dat de extensie/module 'Taken' is ingeschakeld op het slot.
  • hygienic_unlock.start vereist dat de functie 'Hygiënische opening' is ingeschakeld en dat er geen actieve hygiënesessie is.

session.get vergrendelingsgegevens helpers

session.get / GET /api/apps/v1/session omvat ook lockData met runtime-vriendelijke booleaanse waarden, getallen en tekenreeksen voor regelengines.

Voorbeelden:

  • booleans: frozen, unlockable, trusted, taskAssigned (true wanneer een open TaskRun bestaat)
  • nummers: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • tekenreeksen: lockTitle, profielvelden van de drager/sleutelhouder

Privacy:

  • wearerLastSeenTimestamp en keyholderLastSeenTimestamp worden null wanneer die gebruiker de online status heeft uitgeschakeld (showOnlineStatus === false).

Apparaatcommando's

Uitbreidingssessies kunnen gebruikmaken van het sessiegebaseerde eindpunt:

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

Externe programma's met een DEV-token kunnen het eenvoudigere v1-eindpunt gebruiken (geen sessie-ID nodig):

POST /api/apps/v1/device-command

Beide accepteren dezelfde aanvraagbody en retourneren hetzelfde antwoord. Zie Externe API & Programma's voor meer informatie.

Als uw extensie een installatie-/configuratie-interface heeft:

  1. De ouder stuurt chastify:ext:setup:init (opgeslagen configuratie + context).
  2. Uw setup-iframe retourneert updates met chastify:ext:setup:config.
  3. Ouders kunnen de huidige configuratie opvragen met chastify:ext:setup:get_config.

Backend-tokenflow (wanneer server-side aanroepen nodig zijn)

Voor eenvoudige scripts en externe programma's kunt u een gebruikersbreed DEV-token gebruiken van de pagina met de ontwikkelaars-API. Zie Externe API & Programma's.

Standaard workflow in extensie iframe-modus:

  1. Chastify geeft een kortstondig, in de browser zichtbaar opstarttoken uit voor de actieve extensiesessie.
  2. Het opstarttoken is ingebed in de hash-payload van de iframe als mainToken.
  3. Uw iframe stuurt mainToken door naar uw backend.
  4. Uw backend roept https://chastify.net/api/extensions/sessions/:sessionId/* aan met Authorization: Bearer <app-scoped Developer API key> en x-chastify-main-token: <mainToken>.

Verstuur geen API-sleutels voor ontwikkelaars naar iframe-/browsercode. mainToken identificeert de geopende extensiesessie; het is geen backend-geheim en kan niet op zichzelf worden gebruikt voor acties met verhoogde bevoegdheden.

Handmatige terugvaloptie:

  • Als u het iframe-opstarttoken expliciet vanuit de eigen gebruikersinterface wilt ophalen/roteren, roept u GET https://chastify.net/api/extensions/sessions/:sessionId/auth aan.

Gebruik de backend-modus als u geplande taken, webhooks of automatisering nodig hebt terwijl de Chastify-pagina niet geopend is. Voor de huidige sessiemutaties van geïnstalleerde extensies is nog steeds een geldig iframe-starttoken van 10 uur vereist. Daarom moeten taken die niet automatisch worden uitgevoerd, een bewijs van in behandeling zijnde status opslaan en dit bij de volgende geldige start verzenden, tenzij u een eigen/ingebouwde serverflow gebruikt die is ontworpen voor uitvoering op de achtergrond.

info

Voor volledig onbeheerd productiegedrag kunt u het beste een ingebouwde/eigen serverflow gebruiken of wachten op expliciete toekenningen van achtergrondextensies. App-specifieke sessie-API's zijn momenteel gebonden aan een launch-token.

Backend versus Cloudflare Pages (geen server)

Gebruik Cloudflare Pages (zonder backend-server) wanneer:

  • Je wilt de eenvoudigste en goedkoopste oplossing (kan gratis gehost worden).
  • Je hebt alleen UI-gestuurde acties nodig wanneer de gebruiker actief op je extensiepagina is.
  • U hoeft de extensiestatus niet permanent op de server op te slaan.
  • Je bent bezig met het snel ontwikkelen of bouwen van lichtgewicht extensies.

Lokaal testvoorbeeld (PowerShell):

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

Gebruik de gegenereerde openbare URL als iframe-URL tijdens het testen.

Gebruik een backend-server wanneer:

  • Je hebt geplande taken nodig (vergelijkbaar met cron).
  • Je hebt webhooks of externe integraties nodig.
  • Je hebt automatisering/achtergrondverwerking nodig voor de momenten dat er niemand op de extensiepagina is.
  • Je hebt servergestuurde workflows nodig die continu moeten draaien.

Belangrijke beperking zonder backend:

  • Geen achtergronduitvoering. Je extensie kan alleen acties uitvoeren als een gebruiker de iframe van de extensie geopend heeft en ermee interacteert.

Veelvoorkomende problemen

  • 403 extension_not_enabled: extensie is niet ingeschakeld voor dit slot.
  • 409 lock_ended: vergrendeling is niet langer actief.
  • 429: snelheidslimiet bereikt.
  • Geen reacties in iframe: controleer nonce, targetOrigin (parentOrigin) en toegestane origins.

Volgende handleidingen