Hop til hovedindhold

Prøv Extensions Developer API'en

Brug denne vejledning, hvis du vil bygge en Chastify-udvidelse, hoste en iframe-udvidelsesside eller kalde Developer API'en fra din egen backend.

Denne side er udgangspunktet: hvilken tilstand skal man vælge, hvad skal man ringe til først, og hvor skal man gå hen derefter.

For konkret udvidelsesadfærd såsom oplåsning af blokeringer, regelmæssige nødvendige handlinger, belønninger og straffe, se Extension API Features.

tip

Vil du bare styre din egen lås?

Hvis du ikke behøver at bygge en offentlig udvidelse, er siden Ekstern API og programmer den nemmeste måde at komme i gang på. Du opretter blot et DEV-token og kalder simple REST-slutpunkter – ingen udvidelsesopsætning, ingen iframe, ingen sessionsstyring kræves. Den understøtter tilføj/fjern tid, frysning, opgaver, enhedskommandoer og mere.

Hvad denne API er til​

Med Extensions Developer API'en kan du bygge udvidelsesoplevelser fra tredjepart, der kører i Chastify-låsesessioner.

Med den kan du:

  • Læs sessions- og låsekontekst (session.get for udvidelser, /api/apps/v1/session for din egen låseautomatisering)
  • Læs udvidelsesejede data pr. låsesession (state.get) og skriv dem fra din backend (PUT/PATCH /state)
  • Gem udvidelsesejede billedfiler med Chastify-administreret R2-lager (files.*)
  • Tilføj handlinger i udvidelsesgrænsefladen på låsekort (metadata.homeActions)
  • Oplåsningsflow for porte med udvidelsesejede oplåsningsblokkere (metadata.unlockBlockers)
  • Udløs låsehandlinger fra en betroet backend (tilføj/fjern tid, frys/frigør, indstillingsrettelse)
  • Udløs opgave og hygiejnehandlinger (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Indsend regelmæssige handlinger med tællere/kadenceunderstøttelse
  • Send understøttede enhedskommandoer, når de er tilgængelige
  • Skriv brugerdefinerede udvidelseslogposter for at låse historikken

Hvad du kan bygge​

Det rigtige sæt funktioner afhænger af, hvor tilliden findes.

Frontend-kun iframe-udvidelser kan bygge brugergrænseflade-første oplevelser, der ikke kræver betroet låsemutation:

  • Opsætningssider, der indsamler udvidelseskonfiguration
  • Dashboards, der læser sessionskontekst
  • Brugergrænseflader til puslespil, tjeklister eller spil, der læser sessionsstatus og sender verificerede fremskridt via en backend
  • Mediebaserede flows, der læser udvidelsesfiler, der allerede er gemt af Chastify
  • Startsidehandlingsindgangspunkter, der åbner din iframe med en hensigt

Serverbaserede udvidelser kan bygge funktioner, der påvirker låsning, fordi din backend verificerer resultater, før privilegerede API'er kaldes:

  • Opgave- eller vanesystemer med oplåsningskrav
  • Daglige eller ugentlige krav med planlagte straffe for missede vinduer
  • Spil, der belønner succes eller straffer fiasko med ændringer i låsetidspunktet
  • Bekræftelsesflows, der fjerner oplåsningsblokeringer efter validering på serversiden
  • Enhedsstyringsledsagende flows ved hjælp af understøttede enhedskommandoer
  • Webhook/database-arbejdsgange, der holder udvidelsestilstanden uden for iframe'en

Eksterne programmer er til privat automatisering af din egen aktive lås:

  • Lokale scripts
  • Personlige dashboards
  • Automatiseringsværktøjer, der bruger en brugeromfattende DEV-nøgle

Vælg din tilstand​

Vælg en af ​​disse tilstande:

  1. Hosted iframe extension: Vær vært for en statisk iframe-brugergrænseflade på Cloudflare Pages eller en lignende tjeneste. Brug broen til opsætning, sessionskontekst og sikker læsning. Brug ikke denne tilstand alene til tilstandsskrivninger, belønninger, straffe, fuldførelse af oplåsning eller fremskridt med betroede krav.
  2. Server-backed extension: Vær vært for iframe-brugergrænsefladen og kør din egen backend. Iframen sender sin opstarts-mainToken til din backend, og din backend kalder Chastify Extension API'en med en app-scoped Developer API-nøgle plus x-chastify-main-token. Brug denne tilstand til privilegerede handlinger, oplåsning af blokkere, betroede fremskridt, belønninger, straffe, webhooks og eksterne databaser.
  3. External API & Programs: Brug en brugeromfattende DEV-nøgle til scripts, lokale programmer eller automatiseringer, der styrer din egen aktive lås. Dette er ikke tilstanden for tredjepartsbrugere, der installerer din udvidelse.

Hvis du tester hurtigt, så start med iframe-tilstand til brugergrænseflade og sikker læsning. Tilføj en backend, før du implementerer tilstandsskrivninger, betroede belønninger, tidsændringer, planlagt kravfremdrift eller fuldførelse af oplåsningsblokering.

caution

Iframe-kode er ikke en tillidsgrænse. Alt, der er synligt for iframen, inklusive hash-nyttelast og launch-tokens, kan inspiceres og afspilles af brugeren.

Første 10 minutter (iframe-tilstand)​

  1. Læs location.hash-nyttelasten fra Chastify iframe ved åbning.
  2. Opret en broanmodning for session.get.
  3. Bekræft svaret med type: "chastify:ext:resp" og ok: true.
  4. Testtilstand læses med state.get.
  5. Tilføj automatisk størrelsesændring + temaunderstøttelse, så iframe'en opfører sig korrekt i brugergrænsefladen.

Temaunderstøttelse er en del af en produktionsklar iframe. Chastify sender ui-værdier i lancerings-hashen og sender live-temaopdateringer, mens iframen er åben. Se Iframe Theming for lyse/mørke eksempler og kontrastsikre Tailwind-mønstre.

Nødvendige nyttelastværdier:

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

Eksempel på broanmodning:

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

Eksempel på brorespons:

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

Kernehandlinger at lære først​

  • session.get
  • state.get
    Læs udvidelsesejet JSON-lager til låsesessionen. Skriv tilstand fra din backend med Developer API-legitimationsoplysninger.
  • files.capabilities, files.list, files.get Brug fillagringslæsninger til binære medier såsom puslespilbilleder eller genererede forhåndsvisninger. Gem fil-id'er i backend-skrevet tilstand, og opdater derefter signerede URL'er med files.get.
  • metadata.get Læs blokeringer for oplåsning af låsesessioner og handlinger/intentioner for udvidelseskort.
  • regularActions.get

Sessionsmutationer såsom tilstandsskrivninger, indsendelse af almindelige handlinger, upload/sletning af runtime-filer, tidsændringer, opdateringer af oplåsningsblokering, opgaveafslutning, hygiejnestart og enhedskommandoer skal kaldes fra din backend med en Developer API-nøgle. Browserens iframe-kode er ikke betroet til disse handlinger.

Fuld API-URL'er (understøttet)​

Basisdomæne: https://chastify.net

API'er til udvidelsessessioner (/api/extensions/*)​

Disse ruter har forskellige adgangsmetoder. Behandl ikke hele /api/extensions/*-overfladen som iframe-sikker.

Sikre iframe-broruter dirigeres via Chastify-forælderen efter postMessage-broanmodninger:

  • 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

Backend-kun installerede udvidelsesruter kræver en app-scoped Developer API-nøgle og iframe-starttokenet:

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

Denne model med to tokens binder en backend-anmodning til både udvidelsesudvikleren (Authorization) og den aktuelt åbne udvidelsessession (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/*)​

Brug Authorization: Bearer <user-wide DEV token>. Disse slutpunkter administrerer tokenejerens egne aktive låsesessioner og er beregnet til eksterne API-scripts/programmer, ikke installerede tredjepartsudvidelsessessioner.

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

Bridge-kommandonyttelast sendes via iframe (chastify:ext:req) og routes af Chastify-forælderen. Bridgen er bevidst begrænset til sikre/sessionsbaserede brugergrænsefladeoperationer.

  • 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

Sessionsmutationsslutpunkter er direkte backend-API-kald, ikke iframe-brokommandoer. Dette inkluderer tilstandsskrivninger, almindelig handlingsindsendelse og upload/sletning af filer under kørsel, fordi iframe-kode kan styres af brugeren.

Eksempler på backend-sessions-API'er​

Din backend skal sende begge headere for privilegerede kald af installerede udvidelser:

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

Eksempler på backend-handlinger:

  • 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, omfang, tilbagekaldelse og revisionsadfærd​

Brug det rigtige token til den rigtige tillidsgrænse.

warning

Udvikler-API-nøgler er hemmeligheder. Hvis man bliver eksponeret for browserkode, skal den straks tilbagekaldes og backend-miljøvariablen roteres.

Iframe-lanceringstoken (mainToken)​

  • Leveres i iframe-hashen, når en bruger åbner en installeret udvidelsesside.
  • Synlig i browseren. Den identificerer den åbnede udvidelsessession, men det er ikke en backend-hemmelighed.
  • Kortvarig. Nuværende lanceringstokens udløber efter 10 timer; opdater ved at genåbne udvidelsessiden.
  • Kræves som x-chastify-main-token, når din backend kalder installed-extension-sessionsruter, så Chastify kan binde backend-anmodningen til den bruger/session, der åbnede udvidelsen.
  • Må ikke bruges alene til at godkende tidsændringer, oplåse blokeringsfuldførelse, opgavefuldførelse, enhedskommandoer, uploads/sletning under kørsel, brugerdefinerede logfiler eller brugerdefinerede notifikationer.

App-scoped Developer API-nøgle​

  • Oprettet fra udviklergrænsefladen til én udvidelsesapp.
  • Kun backend-hemmelighed. Angiv den aldrig i iframe JavaScript, mobilapp-bundter, statisk hostingkonfiguration eller browserlæsbare logfiler.
  • Bruges sammen med Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY og x-chastify-main-token.
  • Kan kun kalde installed-extension session API'er for sessioner, der matcher udvidelsesappen og starttokenet.
  • Udløber ikke automatisk. Tilbagekald den med det samme, hvis den eksponeres, og roter din backend-miljøvariabel.

Brugeromfattende udvikler-API-nøgle​

  • Oprettet fra udviklergrænsefladen uden at vælge en udvidelsesapp.
  • Kun backend-hemmelighed for /api/apps/v1/*.
  • Styrer nøgleejerens egne nuværende/fremtidige aktive låsesessioner.
  • Kan ikke bruges som en installeret tredjepartsudvidelses backend-legitimationsoplysninger.

Tilbagekaldelse​

  • Tilbagekaldte Developer API-nøgler stopper med at godkende nye anmodninger.
  • Tilbagekaldte nøgler kan slettes permanent fra udviklergrænsefladen.
  • Nye iframe-lanceringer modtager nye lanceringstokens. Gem ikke mainToken som en langsigtet legitimationsoplysninger.

Omfang og roller​

  • Udvidelsesapp-omfang beskriver, hvad appen har tilladelse til at anmode om.
  • Sikre iframe-bridge-kald er begrænset til UI-bootstrap, sessionslæsninger, udvidelsesejet tilstand, metadatalæsninger, almindelige handlingslæsninger og fillæsninger.
  • Privilegerede mutationer i installerede sessioner kræver backend-legitimationsoplysninger, selv når udvidelsen har et matchende omfang.
  • Rolleafhængige handlinger kan stadig blive afvist baseret på, om lanceringen tilhører en bærer eller nøgleholder.

Revision og grænser​

  • Metadata for sidst anvendte Developer API-nøgler opdateres, når nøgler bruges.
  • Privilegerede handlingsruter er hastighedsbegrænsede og returnerer eksplicitte fejl såsom server_credentials_required eller user_wide_dev_key_required, når den forkerte legitimationstype bruges.
  • Brugerdefinerede logfiler skriver synlige poster i låsehistorikken.
  • Brugerdefinerede notifikationer opretter Chastify-notifikationer for det anmodede mål.
  • Fuld revisionsdækning for hver mutation i privilegerede udvidelser spores som et produktionshærdende element.

Understøttede kommandoværdier​

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

name understøtter:

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

Handlingsbegrænsninger:

  • Opgavehandlinger kræver, at Opgaver-udvidelsen/modulet er aktiveret på låsen.
  • hygienic_unlock.start kræver aktiveret hygiejnisk åbning og ingen aktiv hygiejnesession.

session.get låsedatahjælpere​

session.get / GET /api/apps/v1/session inkluderer også lockData med runtime-venlige booleaner, tal og strenge til regelmotorer.

Eksempler:

  • booleske værdier: frozen, unlockable, trusted, taskAssigned (true når en åben TaskRun findes)
  • numre: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • strenge: lockTitle, felter for bærer-/nøgleholderprofil

Privatliv:

  • wearerLastSeenTimestamp og keyholderLastSeenTimestamp er null, når den pågældende bruger har deaktiveret onlinestatus (showOnlineStatus === false).

Enhedskommandoer​

Udvidelsessessioner kan bruge det sessionsbaserede slutpunkt:

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

Eksterne programmer med et DEV-token kan bruge det enklere v1-slutpunkt (intet sessions-ID nødvendigt):

POST /api/apps/v1/device-command

Begge accepterer den samme anmodningstekst og returnerer det samme svar. Se Ekstern API og programmer for at få alle detaljer.

Opsætningsside (valgfri, anbefalet)​

Hvis din udvidelse har en opsætnings-/konfigurationsgrænseflade:

  1. Forælder sender chastify:ext:setup:init (gemt konfiguration + kontekst).
  2. Din opsatte iframe returnerer opdateringer med chastify:ext:setup:config.
  3. Forælder kan anmode om den aktuelle konfiguration med chastify:ext:setup:get_config.

Backend-tokenflow (når du har brug for server-side-kald)​

Til simple scripts og eksterne programmer skal du bruge et brugeromfattende DEV-token fra Developer API-siden. Se Ekstern API og programmer.

Standardflow i udvidelsens iframe-tilstand:

  1. Chastify udsteder et kortlivet, browser-synligt starttoken til den aktive udvidelsessession.
  2. Launch-tokenet er integreret i iframe-hash-nyttelasten som mainToken.
  3. Din iframe videresender mainToken til din backend.
  4. Din backend kalder https://chastify.net/api/extensions/sessions/:sessionId/* med Authorization: Bearer <app-scoped Developer API key> og x-chastify-main-token: <mainToken>.

Send ikke Developer API-nøgler til iframe/browserkode. mainToken identificerer den åbnede udvidelsessession; det er ikke en backend-hemmelighed og kan ikke bruges alene til privilegerede handlinger.

Manuel reserve:

  • Hvis du har brug for at hente/rotere iframe-starttokenet eksplicit fra førsteparts-brugergrænsefladen, skal du kalde GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Brug backend-tilstand, hvis du har brug for planlagte job, webhooks eller automatisering, mens Chastify-siden ikke er åben. Aktuelle mutationer af installerede udvidelser kræver stadig et gyldigt 10-timers iframe-starttoken, så uovervågede job bør gemme ventende bevis og indsende det ved den næste gyldige start, medmindre du bruger et førsteparts-/indbygget serverflow, der er designet til baggrundskørsel.

info

For fuldt uovervåget produktionsadfærd, foretræk et indbygget/førsteparts serverflow eller vent på eksplicitte baggrundsudvidelsestildelinger. App-scoped session API'er er i øjeblikket launch-token-bundne.

Backend vs. Cloudflare-sider (ingen server)​

Brug Cloudflare Pages (ingen backend-server) når:​

  • Du ønsker den nemmeste og billigste opsætning (kan hostes gratis).
  • Du behøver kun brugergrænsefladedrevne handlinger, mens brugeren aktivt er på din udvidelsesside.
  • Du behøver ikke server-persisterende udvidelsestilstandsskrivninger.
  • Du prototyper eller bygger hurtigt lette udvidelser.

Eksempel på lokal testning (PowerShell):

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

Brug den genererede offentlige URL som din iframe-URL under testning.

Brug en backend-server når:​

  • Du har brug for planlagte job (cron-lignende adfærd).
  • Du har brug for webhooks eller eksterne integrationer.
  • Du har brug for automatisering/baggrundsbehandling, når der ikke er nogen på udvidelsessiden.
  • Du har brug for serverstyrede arbejdsgange, der skal køre kontinuerligt.

Vigtig begrænsning uden backend:

  • Ingen baggrundsudførelse. Din udvidelse kan kun udføre handlinger, mens en bruger i øjeblikket har udvidelsens iframe åben og interagerer med den.

Almindelige problemer​

  • 403 extension_not_enabled: Udvidelsen er ikke aktiveret for denne lås.
  • 409 lock_ended: låsen er ikke længere aktiv.
  • 429: hastighedsgrænse nået.
  • Ingen svar i iframe: tjek nonce, targetOrigin (parentOrigin) og tilladte oprindelser.

Næste guider​