Hoppa till huvudinnehåll

Prova Extensions Developer API

Använd den här guiden om du vill bygga ett Chastify-tillägg, vara värd för en iframe-tilläggssida eller anropa Developer API:et från din egen backend.

Den här sidan är utgångspunkten: vilket läge man ska välja, vad man ska anropa först och vart man ska gå härnäst.

För konkreta beteenden i tillägg, såsom upplåsning av blockerare, regelbundna obligatoriska åtgärder, belöningar och straff, se Extension API Features.

tips

Vill du bara styra ditt eget lås?

Om du inte behöver bygga ett offentligt tillägg är sidan Externt API och program det enklaste sättet att komma igång. Du skapar bara en DEV-token och anropar enkla REST-slutpunkter – ingen tilläggskonfiguration, ingen iframe, ingen sessionshantering krävs. Den stöder lägg till/ta bort tid, frysning, uppgifter, enhetskommandon och mer.

Vad detta API är till för​

Med Extensions Developer API kan du bygga tredjepartstilläggsupplevelser som körs inuti Chastify-låssessioner.

Med den kan du:

  • Läs sessions- och låskontext (session.get för tillägg, /api/apps/v1/session för din egen låsautomation)
  • Läs tilläggsägd data per låssession (state.get) och skriv den från din backend (PUT/PATCH /state)
  • Lagra tilläggsägda bildfiler med Chastify-hanterad R2-lagring (files.*)
  • Lägg till tilläggsgränssnittsåtgärder på låskort (metadata.homeActions)
  • Flöde för upplåsning av grindar med upplåsningsblockerare som ägs av tillägget (metadata.unlockBlockers)
  • Utlösa låsåtgärder från en betrodd backend (lägg till/ta bort tid, frys/tina upp, inställningspatch)
  • Utlösande av uppgifter och hygienåtgärder (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Skicka in regelbundna åtgärder med stöd för räknare/kadens
  • Skicka enhetskommandon som stöds när de är tillgängliga
  • Skriv anpassade loggposter för tillägg för att låsa historiken

Vad du kan bygga​

Rätt funktionsuppsättning beror på var förtroendet finns.

Frontend-end-iframe-tillägg kan bygga användargränssnittsbaserade upplevelser som inte kräver mutation av betrodda lås:

  • Installationssidor som samlar in tilläggskonfiguration
  • Instrumentpaneler som läser sessionskontext
  • Pussel-, checklista- eller spelgränssnitt som läser sessionsstatus och skickar verifierade framsteg via en backend
  • Mediebaserade flöden som läser tilläggsfiler som redan lagrats av Chastify
  • Startpunkter för startåtgärder som öppnar din iframe med en avsikt

Serverbaserade tillägg kan bygga funktioner som påverkar låsningar eftersom din backend verifierar resultat innan privilegierade API:er anropas:

  • Uppgifts- eller vanesystem med upplåsningskrav
  • Dagliga eller veckovisa krav med schemalagda straff för missade fönster
  • Spel som belönar framgång eller straffar misslyckanden med tidsändringar för låsning
  • Verifieringsflöden som rensar upplåsningsblockerare efter validering på serversidan
  • Kompletterande flöden för enhetskontroll med hjälp av enhetskommandon som stöds
  • Webhook/databasarbetsflöden som håller tilläggets tillstånd utanför iframe

Externa program är avsedda för privat automatisering av ditt eget aktiva lås:

  • Lokala skript
  • Personliga instrumentpaneler
  • Automatiseringsverktyg som använder en användaromfattande DEV-nyckel

Välj ditt läge​

Välj ett av dessa lägen:

  1. Hosted iframe extension: värd för ett statiskt iframe-gränssnitt på Cloudflare Pages eller en liknande tjänst. Använd bryggan för installation, sessionskontext och säkra läsningar. Använd inte detta läge enbart för tillståndsskrivningar, belöningar, straff, upplåsningsslutförande eller framsteg för betrodda krav.
  2. Server-backed extension: värd för iframe-gränssnittet och kör din egen backend. Iframen skickar sin start-mainToken till din backend, och din backend anropar Chastify Extension API med en app-scope Developer API-nyckel plus x-chastify-main-token. Använd det här läget för privilegierade åtgärder, upplåsning av blockerare, betrodda framsteg, belöningar, straff, webhooks och externa databaser.
  3. External API & Programs: använd en användaromfattande DEV-nyckel för skript, lokala program eller automatiseringar som styr ditt eget aktiva lås. Detta är inte läget för tredjepartsanvändare som installerar ditt tillägg.

Om du testar snabbt, börja med iframe-läge för användargränssnitt och säkra läsningar. Lägg till en backend innan du implementerar tillståndsskrivningar, betrodda belöningar, tidsändringar, schemalagd kravförlopp eller slutförande av upplåsningsblockerare.

varning

Iframe-kod är inte en förtroendegräns. Allt som är synligt för iframen, inklusive hash-nyttolaster och starttokens, kan inspekteras och spelas upp av användaren.

Första 10 minuterna (iframe-läge)​

  1. Läs location.hash-nyttolasten från Chastify iframe öppen.
  2. Skapa en bryggbegäran för session.get.
  3. Bekräfta svaret med type: "chastify:ext:resp" och ok: true.
  4. Testtillstånd läses med state.get.
  5. Lägg till automatisk storleksändring + temastöd så att iframe-bilden beter sig korrekt i användargränssnittet.

Temasupport är en del av en produktionsklar iframe. Chastify skickar ui-värden i lanseringshashen och skickar live-temauppdateringar medan iframen är öppen. Se Iframe Theming för ljusa/mörka exempel och kontrastsäkra Tailwind-mönster.

Nödvändiga nyttolastvärden:

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

Exempel på bryggförfrågan:

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

Exempel på bryggsvar:

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

Kärnåtgärder att lära sig först​

  • session.get
  • state.get
    Läs tilläggsägd JSON-lagring för låssessionen. Skriv tillstånd från din backend med Developer API-inloggningsuppgifter.
  • files.capabilities, files.list, files.get Använd fillagringsläsningar för binära medier som pusselbilder eller genererade förhandsvisningar. Lagra fil-ID:n i backend-skrivet tillstånd och uppdatera sedan signerade URL:er med files.get.
  • metadata.get Läs blockerare för upplåsning av låssessioner och åtgärder/avsikter för tilläggskort.
  • regularActions.get

Sessionsmutationer som tillståndsskrivningar, inlämning av vanliga åtgärder, uppladdning/borttagning av filer vid körning, tidsändringar, uppdateringar av upplåsningsblockerare, slutförande av uppgifter, hygienstarter och enhetskommandon måste anropas från din backend med en Developer API-nyckel. Webbläsarens iframe-kod är inte betrodd för dessa åtgärder.

Fullständiga API-URL:er (stöds)​

Basdomän: https://chastify.net

API:er för tilläggssessioner (/api/extensions/*)​

Dessa rutter har olika åtkomstlägen. Behandla inte hela /api/extensions/*-ytan som iframe-säker.

Säkra iframe-bryggrutter dirigeras via Chastify-föräldern efter postMessage-bryggförfrågningar:

  • 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

Rutter för installerade tillägg endast i backend kräver en app-omfattande Developer API-nyckel och iframe-starttoken:

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

Denna två-token-modell binder en backend-begäran till både tilläggsutvecklaren (Authorization) och den för närvarande öppna tilläggssessionen (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:er (/api/apps/v1/*)​

Använd Authorization: Bearer <user-wide DEV token>. Dessa slutpunkter hanterar tokenägarens egna aktiva låssessioner och är avsedda för externa API-skript/program, inte installerade tredjepartstilläggssessioner.

  • 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-kommandon​

Bryggkommandon skickas via iframe (chastify:ext:req) och dirigeras av Chastify-föräldern. Bryggan är avsiktligt begränsad till säkra/sessionsbaserade UI-operationer.

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

Slutpunkter för sessionsmutationer är direkta backend-API-anrop, inte iframe-bryggkommandon. Detta inkluderar tillståndsskrivningar, regelbunden åtgärdsinlämning och uppladdning/borttagning av filer vid körning, eftersom iframe-kod kan styras av användaren.

Exempel på backend-sessions-API​

Din backend måste skicka båda rubrikerna för privilegierade anrop av installerade tillägg:

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

Exempel på backend-åtgärder:

  • 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 med { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action med { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action med { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action med { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action med { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action med { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action med { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action med { "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, omfattning, återkallelse och granskningsbeteende​

Använd rätt token för rätt förtroendegräns.

warning

Utvecklarens API-nycklar är hemligheter. Om någon exponeras för webbläsarkod, återkalla den omedelbart och rotera backend-miljövariabeln.

Iframe-lanseringstoken (mainToken)​

  • Levereras i iframe-hashen när en användare öppnar en sida med installerat tillägg.
  • Synlig i webbläsaren. Den identifierar den öppnade tilläggssessionen, men är inte en backend-hemlighet.
  • Kortlivad. Nuvarande lanseringstokens upphör att gälla efter 10 timmar; uppdatera genom att öppna tilläggssidan igen.
  • Krävs som x-chastify-main-token när din backend anropar sessionsrutter för installed-extension, så att Chastify kan binda backend-begäran till användaren/sessionen som öppnade tillägget.
  • Får inte användas ensamt för att auktorisera tidsändringar, låsa upp blockeringsslutförande, slutföra uppgifter, enhetskommandon, uppladdningar/borttagningar under körning, anpassade loggar eller anpassade aviseringar.

App-scoped Developer API-nyckel​

  • Skapad från utvecklargränssnittet för en tilläggsapp.
  • Endast backend-hemlighet. Lägg den aldrig i iframe-JavaScript, mobilappspaket, statisk hostingkonfiguration eller webbläsarläsbara loggar.
  • Används med Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY och x-chastify-main-token.
  • Kan endast anropa sessions-API:er för installerade tillägg för sessioner som matchar tilläggsappen och starttoken.
  • Upphör inte att gälla automatiskt. Återkalla den omedelbart om den exponeras och rotera din backend-miljövariabel.

Användaromfattande utvecklar-API-nyckel​

  • Skapad från utvecklargränssnittet utan att välja en tilläggsapp.
  • Endast backend-hemlighet för /api/apps/v1/*.
  • Styr nyckelinnehavarens egna nuvarande/framtida aktiva låssessioner.
  • Kan inte användas som en installerad tredjepartstilläggsautentiseringsuppgift för backend.

Återkallande​

  • Återkallade Developer API-nycklar slutar auktorisera nya förfrågningar.
  • Återkallade nycklar kan tas bort permanent från utvecklargränssnittet.
  • Nya iframe-lanseringar får nya lanseringstokens. Spara inte mainToken som en långsiktig autentiseringsuppgift.

Omfattningar och roller​

  • Tilläggsappens omfattningar beskriver vad appen får begära.
  • Säkra iframe-brygganrop är begränsade till UI-bootstrap, sessionsläsningar, tilläggsägt tillstånd, metadataläsningar, vanliga handlingsläsningar och filläsningar.
  • Privilegierade mutationer i installerade sessioner kräver backend-autentiseringsuppgifter även om tillägget har ett matchande omfång.
  • Rollkänsliga åtgärder kan fortfarande avvisas baserat på om lanseringen tillhör en bärare eller nyckelinnehavare.

Revision och gränser​

  • Metadata för senast använda Developer API-nyckel uppdateras när nycklar används.
  • Privilegierade åtgärdsvägar är hastighetsbegränsade och returnerar explicita fel som server_credentials_required eller user_wide_dev_key_required när fel autentiseringsuppgifter används.
  • Anpassade loggar skriver synliga poster i låshistoriken.
  • Anpassade aviseringar skapar Chastify-aviseringar för det begärda målet.
  • Fullständig granskningstäckning för varje mutation i privilegierad tillägg spåras som en produktionshärdningspost.

Stödda kommandovärden​

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

name stöder:

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

Åtgärdsbegränsningar:

  • Uppgiftsåtgärder kräver att tillägget/modulen Uppgifter är aktiverad på låset.
  • hygienic_unlock.start kräver att Hygienisk öppning är aktiverad och att ingen hygiensession är aktiv.

session.get låsdatahjälpare​

session.get / GET /api/apps/v1/session inkluderar även lockData med körtidsvänliga booleska värden, siffror och strängar för regelmotorer.

Exempel:

  • booleska värden: frozen, unlockable, trusted, taskAssigned (true när en öppen TaskRun finns)
  • nummer: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • strängar: lockTitle, fält för bärare/nyckelinnehavarprofil

Privatliv:

  • wearerLastSeenTimestamp och keyholderLastSeenTimestamp är null när användaren har inaktiverat onlinestatusen (showOnlineStatus === false).

Enhetskommandon​

Utökningssessioner kan använda den sessionsbaserade slutpunkten:

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

Externa program med en DEV-token kan använda den enklare v1-slutpunkten (inget sessions-ID behövs):

POST /api/apps/v1/device-command

Båda accepterar samma förfrågningstext och returnerar samma svar. Se Externt API och program för fullständig information.

Installationssida (valfritt, rekommenderas)​

Om ditt tillägg har ett konfigurationsgränssnitt:

  1. Föräldern skickar chastify:ext:setup:init (sparad konfiguration + kontext).
  2. Din konfigurerade iframe returnerar uppdateringar med chastify:ext:setup:config.
  3. Förälder kan begära aktuell konfiguration med chastify:ext:setup:get_config.

Backend-tokenflöde (när du behöver serversidesanrop)​

För enkla skript och externa program, använd en användaromfattande DEV-token från sidan Developer API. Se Externt API och program.

Standardflöde i tilläggets iframe-läge:

  1. Chastify utfärdar en kortlivad webbläsarsynlig starttoken för den aktiva tilläggssessionen.
  2. Lanseringstoken är inbäddad i iframe-hash-nyttolasten som mainToken.
  3. Din iframe vidarebefordrar mainToken till din backend.
  4. Din backend anropar https://chastify.net/api/extensions/sessions/:sessionId/* med Authorization: Bearer <app-scoped Developer API key> och x-chastify-main-token: <mainToken>.

Skicka inte Developer API-nycklar till iframe/webbläsarkod. mainToken identifierar den öppnade tilläggssessionen; det är inte en backend-hemlighet och kan inte användas ensamt för privilegierade åtgärder.

Manuell reserv:

  • Om du behöver hämta/rotera iframe-starttoken explicit från förstapartsgränssnittet, anropa GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Använd backend-läge om du behöver schemalagda jobb, webhooks eller automatisering medan Chastify-sidan inte är öppen. Aktuella sessionsmutationer för installerade tillägg kräver fortfarande en giltig 10-timmars iframe-starttoken, så obevakade jobb bör lagra väntande bevis och skicka in det vid nästa giltiga start om du inte använder ett förstaparts-/inbyggt serverflöde som är utformat för bakgrundskörning.

info

För helt obevakat produktionsbeteende, föredra ett inbyggt/förstapartsserverflöde eller vänta på explicita bakgrundstillägg. App-scoped session API:er är för närvarande bundna till launch-token.

Backend vs Cloudflare-sidor (ingen server)​

Använd Cloudflare Pages (ingen backend-server) när:​

  • Du vill ha den enklaste och billigaste installationen (kan hostas gratis).
  • Du behöver bara användargränssnittsdrivna åtgärder medan användaren aktivt är på din tilläggssida.
  • Du behöver inte serverbeständiga tillståndsskrivningar för tillägg.
  • Du prototyper eller bygger lättviktiga tillägg snabbt.

Exempel på lokal testning (PowerShell):

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

Använd den genererade offentliga URL:en som din iframe-URL när du testar.

Använd en backend-server när:​

  • Du behöver schemalagda jobb (cron-liknande beteende).
  • Du behöver webhooks eller externa integrationer.
  • Du behöver automatisering/bakgrundsbearbetning när ingen är på tilläggssidan.
  • Du behöver serverstyrda arbetsflöden som måste köras kontinuerligt.

Viktig begränsning utan backend:

  • Ingen bakgrundskörning. Ditt tillägg kan bara vidta åtgärder medan en användare för närvarande har tilläggets iframe öppen och interagerar med den.

Vanliga problem​

  • 403 extension_not_enabled: tillägget är inte aktiverat för detta lås.
  • 409 lock_ended: låset är inte längre aktivt.
  • 429: hastighetsgränsen har uppnåtts.
  • Inga svar i iframe: kontrollera nonce, targetOrigin (parentOrigin) och tillåtna ursprung.

Nästa guider​