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.
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.getvoor extensies,/api/apps/v1/sessionvoor 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:
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.Server-backed extension: host de iframe-gebruikersinterface en voer je eigen backend uit. De iframe stuurt zijn opstartcodemainTokennaar je backend, en je backend roept de Chastify Extension API aan met een app-specifieke Developer API-sleutel plusx-chastify-main-token. Gebruik deze modus voor acties met verhoogde bevoegdheden, het ontgrendelen van blokkades, betrouwbare voortgang, beloningen, straffen, webhooks en externe databases.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.
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)
- Lees de payload
location.hashuit het geopende iframe Chastify. - Maak een bridge-verzoek aan voor
session.get. - Bevestig het antwoord met
type: "chastify:ext:resp"enok: true. - Teststatus leest met
state.get. - 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.noncebridge.parentOriginsessionIdlockId
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.getstate.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.getGebruik 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 metfiles.get.metadata.getLees 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/:sessionIdGET https://chastify.net/api/extensions/sessions/:sessionId/stateGET https://chastify.net/api/extensions/sessions/:sessionId/metadataGET https://chastify.net/api/extensions/sessions/:sessionId/regular-actionsGET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilitiesGET https://chastify.net/api/extensions/sessions/:sessionId/filesGET 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
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/metadataPUT https://chastify.net/api/extensions/sessions/:sessionId/statePATCH https://chastify.net/api/extensions/sessions/:sessionId/statePATCH https://chastify.net/api/extensions/sessions/:sessionId/regular-actions/configPOST https://chastify.net/api/extensions/sessions/:sessionId/regular-actionsPOST https://chastify.net/api/extensions/sessions/:sessionId/filesDELETE https://chastify.net/api/extensions/sessions/:sessionId/files/:fileIdPOST https://chastify.net/api/extensions/sessions/:sessionId/logs/customPOST https://chastify.net/api/extensions/sessions/:sessionId/notifications/customPOST https://chastify.net/api/extensions/sessions/:sessionId/device-commandPOST https://chastify.net/api/extensions/sessions/:sessionId/actionPOST 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/sessionGET https://chastify.net/api/apps/v1/statePUT https://chastify.net/api/apps/v1/statePATCH https://chastify.net/api/apps/v1/stateGET https://chastify.net/api/apps/v1/metadataPATCH https://chastify.net/api/apps/v1/metadataPOST https://chastify.net/api/apps/v1/actionPOST https://chastify.net/api/apps/v1/lock/apply-timePOST https://chastify.net/api/apps/v1/lock/freezePOST https://chastify.net/api/apps/v1/lock/unfreezePOST 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/:sessionIdstate.get->GET https://chastify.net/api/extensions/sessions/:sessionId/statefiles.capabilities->GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilitiesfiles.list->GET https://chastify.net/api/extensions/sessions/:sessionId/filesfiles.get->GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileIdmet{ "fileId": "file_record_id" }metadata.get->GET https://chastify.net/api/extensions/sessions/:sessionId/metadataregularActions.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/metadataregularActions.submit->POST /api/extensions/sessions/:sessionId/regular-actionsfiles.upload->POST /api/extensions/sessions/:sessionId/filesfiles.delete->DELETE /api/extensions/sessions/:sessionId/files/:fileIdlock.applyTime->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "add_time", "params": <deltaSeconds> }lock.freeze->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "freeze", "params": { "durationSeconds": 900 } }lock.unfreeze->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "unfreeze", "params": {} }lock.settings.patch->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "settings.patch", "params": { ... } }task.assign->POST /api/extensions/sessions/:sessionId/actiontask.start_timer->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "task.start_timer", "params": {} }task.complete->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "task.complete", "params": { "successful": true } }hygienic_unlock.start->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }pillory.end->POST /api/extensions/sessions/:sessionId/actionmet{ "name": "pillory.end", "params": {} }device.command->POST /api/extensions/sessions/:sessionId/device-commandlogs.custom->POST /api/extensions/sessions/:sessionId/logs/customnotifications.custom->POST /api/extensions/sessions/:sessionId/notifications/customrequirements.progress->POST /api/extensions/sessions/:sessionId/requirements/progress
Token-, bereik-, intrekkings- en auditgedrag
Gebruik het juiste token voor de juiste vertrouwensgrens.
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-tokenwanneer 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_KEYenx-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
mainTokenniet 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_requiredofuser_wide_dev_key_requiredwanneer 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_timeremove_timefreezepilloryunfreezetoggle_freezesettings.patchtask.assigntask.start_timertask.completehygienic_unlock.startpillory.end
Actiebeperkingen:
- Voor taakacties is het vereist dat de extensie/module 'Taken' is ingeschakeld op het slot.
hygienic_unlock.startvereist 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(truewanneer een openTaskRunbestaat) - nummers:
timeLockedSeconds,timeRemainingSeconds,maxTimeRemainingSeconds,taskPoints - tekenreeksen:
lockTitle, profielvelden van de drager/sleutelhouder
Privacy:
wearerLastSeenTimestampenkeyholderLastSeenTimestampwordennullwanneer 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.
Instellingenpagina (optioneel, aanbevolen)
Als uw extensie een installatie-/configuratie-interface heeft:
- De ouder stuurt
chastify:ext:setup:init(opgeslagen configuratie + context). - Uw setup-iframe retourneert updates met
chastify:ext:setup:config. - 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:
- Chastify geeft een kortstondig, in de browser zichtbaar opstarttoken uit voor de actieve extensiesessie.
- Het opstarttoken is ingebed in de hash-payload van de iframe als
mainToken. - Uw iframe stuurt
mainTokendoor naar uw backend. - Uw backend roept
https://chastify.net/api/extensions/sessions/:sessionId/*aan metAuthorization: Bearer <app-scoped Developer API key>enx-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/authaan.
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.
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.