Skip to main content

Prøv utvidelsesutvikler-API-et

Bruk denne veiledningen hvis du vil bygge en Chastify-utvidelse, være vert for en iframe-utvidelsesside eller kalle utvikler-API-et fra din egen backend.

Denne siden er utgangspunktet: hvilken modus du skal velge, hva du skal ringe først, og hvor du skal gå videre.

For konkret utvidelsesatferd, som opplåsingsblokkeringer, vanlige nødvendige handlinger, belønninger og straffer, se Extension API Features.

tip

Vil du bare kontrollere din egen lås?

Hvis du ikke trenger å bygge en offentlig utvidelse, er siden Ekstern API og programmer den enkleste måten å komme i gang på. Du oppretter bare et DEV-token og kaller enkle REST-endepunkter – ingen utvidelsesoppsett, ingen iframe, ingen øktadministrasjon kreves. Den støtter legge til/fjerning av tid, frysing, oppgaver, enhetskommandoer og mer.

Hva dette API-et er til for​

Med Extensions Developer API kan du bygge tredjeparts utvidelsesopplevelser som kjører i Chastify-låseøkter.

Med den kan du:

  • Les økt- og låsekontekst (session.get for utvidelser, /api/apps/v1/session for din egen låseautomatisering)
  • Les utvidelseseide data per låseøkt (state.get) og skriv dem fra backend-en din (PUT/PATCH /state)
  • Lagre utvidelseseide bildefiler med Chastify-administrert R2-lagring (files.*)
  • Legg til handlinger i utvidelsesgrensesnittet på låsekort (metadata.homeActions)
  • Opplåsingsflyt for port med opplåsingsblokkeringer som eies av utvidelsen (metadata.unlockBlockers)
  • Utløs låsehandlinger fra en klarert backend (legg til/fjern tid, frys/opphev frysing, innstillingsoppdatering)
  • Utløs oppgaver og hygienehandlinger (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Send inn regelmessige handlinger med støtte for tellere/kadens
  • Send støttede enhetskommandoer når tilgjengelig
  • Skriv tilpassede oppføringer i utvidelsesloggen for å låse historikken

Hva du kan bygge​

Det riktige funksjonssettet avhenger av hvor tilliten ligger.

Iframe-utvidelser kun for frontend kan bygge brukergrensesnitt-første opplevelser som ikke trenger mutasjon av klarerte låser:

  • Oppsettsider som samler inn konfigurasjon av utvidelser
  • Dashboards som leser øktkontekst
  • Brukergrensesnitt for puslespill, sjekklister eller spill som leser øktstatus og sender bekreftet fremgang gjennom en backend
  • Mediebaserte flyter som leser utvidelsesfiler som allerede er lagret av Chastify
  • Inngangspunkter for starthandlinger som åpner iframe-en din med en intensjon

Serverstøttede utvidelser kan bygge funksjoner som påvirker låsing fordi backend-serveren din verifiserer resultater før den kaller privilegerte API-er:

  • Oppgave- eller vanesystemer med opplåsingskrav
  • Daglige eller ukentlige krav med planlagte straffer for tapte vinduer
  • Spill som belønner suksess eller straffer fiasko med endringer i låsetiden
  • Verifiseringsflyter som fjerner opplåsingsblokkeringer etter validering på serversiden
  • Tilhørende flyter for enhetskontroll ved bruk av støttede enhetskommandoer
  • Webhook-/databasearbeidsflyter som holder utvidelsesstatusen utenfor iframe-en

Eksterne programmer er for privat automatisering av din egen aktive lås:

  • Lokale skript
  • Personlige dashbord
  • Automatiseringsverktøy som bruker en brukeromfattende DEV-nøkkel

Velg din modus​

Velg én av disse modusene:

  1. Hosted iframe extension: Vær vert for et statisk iframe-grensesnitt på Cloudflare Pages eller en lignende tjeneste. Bruk broen for oppsett, øktkontekst og sikre lesninger. Ikke bruk denne modusen alene for tilstandsskrivinger, belønninger, straffer, fullføring av opplåsing eller fremdrift av klarerte krav.
  2. Server-backed extension: Vær vert for iframe-grensesnittet og kjør din egen backend. Iframen sender sin oppstarts-mainToken til backend-en din, og backend-en din kaller Chastify Extension API med en app-scoped Developer API-nøkkel pluss x-chastify-main-token. Bruk denne modusen for privilegerte handlinger, opplåsing av blokkeringer, klarert fremgang, belønninger, straffer, webhooks og eksterne databaser.
  3. External API & Programs: bruk en brukeromfattende DEV-nøkkel for skript, lokale programmer eller automatiseringer som kontrollerer din egen aktive lås. Dette er ikke modusen for tredjepartsbrukere som installerer utvidelsen din.

Hvis du tester raskt, start med iframe-modus for brukergrensesnitt og sikre lesninger. Legg til en backend før du implementerer tilstandsskrivinger, klarerte belønninger, tidsendringer, planlagt kravfremdrift eller fullføring av opplåsingsblokkering.

caution

Iframe-kode er ikke en tillitsgrense. Alt som er synlig for iframen, inkludert hash-nyttelaster og oppstartstokener, kan inspiseres og spilles av av brukeren.

Første 10 minutter (iframe-modus)​

  1. Les location.hash-nyttelasten fra Chastify iframe-en når den er åpen.
  2. Opprett en broforespørsel for session.get.
  3. Bekreft svaret med type: "chastify:ext:resp" og ok: true.
  4. Testtilstand leser med state.get.
  5. Legg til automatisk størrelsesendring + temastøtte slik at iframe-en oppfører seg riktig i brukergrensesnittet.

Temastøtte er en del av en produksjonsklar iframe. Chastify sender ui-verdier i lanserings-hashen og sender live temaoppdateringer mens iframen er åpen. Se Iframe-temaer for lyse/mørke eksempler og kontrastsikre Tailwind-mønstre.

Nødvendige nyttelastverdier:

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

Eksempel på broforespørsel:

{
  "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": {}
}

Kjernehandlinger å lære først​

  • session.get
  • state.get
    Les JSON-lagring eid av utvidelsen for låseøkten. Skriv status fra backend-en din med Developer API-legitimasjon.
  • files.capabilities, files.list, files.get Bruk fillagringslesninger for binære medier som puslespillbilder eller genererte forhåndsvisninger. Lagre fil-ID-er i backend-skrevet tilstand, og oppdater deretter signerte URL-er med files.get.
  • metadata.get Les blokkeringer for opplåsing av låseøkter og handlinger/intensjoner for startskjermbildet for utvidelseskort.
  • regularActions.get

Øktmutasjoner som tilstandsskrivinger, innsending av vanlige handlinger, opplasting/sletting av filer under kjøring, tidsendringer, oppdateringer av opplåsingsblokkering, fullføring av oppgaver, hygienestarter og enhetskommandoer må kalles fra backend-en din med en Developer API-nøkkel. Nettleserens iframe-kode er ikke klarert for disse handlingene.

Fullstendige API-URL-er (støttet)​

Basisdomene: https://chastify.net

API-er for utvidelsesøkt (/api/extensions/*)​

Disse rutene har forskjellige tilgangsmoduser. Ikke behandle hele /api/extensions/*-overflaten som iframe-sikker.

Sikre iframe-broruter rutes gjennom Chastify-forelderen etter postMessage-broforespørsler:

  • 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

Ruter for kun installerte utvidelser i backend krever en app-omfattet utvikler-API-nøkkel og iframe-lanseringstokenet:

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

Denne modellen med to tokens binder en backend-forespørsel til både utvidelsesutvikleren (Authorization) og den for øyeblikket åpne utvidelsesøkten (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/*)​

Bruk Authorization: Bearer <user-wide DEV token>. Disse endepunktene administrerer tokeneierens egne aktive låseøkter og er ment for eksterne API-skript/programmer, ikke installerte tredjeparts utvidelsesøkter.

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

Nyttelaster for brokommandoer sendes via iframe (chastify:ext:req) og rutes av Chastify-forelderen. Broen er bevisst begrenset til sikre/øktbaserte brukergrensesnittoperasjoner.

  • 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

Endepunkter for øktmutasjon er direkte API-kall for backend, ikke iframe-brokommandoer. Dette inkluderer tilstandsskrivinger, innsending av vanlige handlinger og opplasting/sletting av filer under kjøring, fordi iframe-kode kan kontrolleres av brukeren.

Eksempler på API-er for backend-økter​

Bakenden din må sende begge overskriftene for privilegerte kall med installerte utvidelser:

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, tilbakekalling og revisjonsatferd​

Bruk riktig token for riktig tillitsgrense.

warning

API-nøkler for utviklere er hemmeligheter. Hvis man blir eksponert for nettleserkode, må den tilbakekalles umiddelbart og backend-miljøvariabelen roteres.

Iframe-lanseringstoken (mainToken)​

  • Leveres i iframe-hashen når en bruker åpner en side for installert utvidelse.
  • Synlig i nettleseren. Den identifiserer den åpnede utvidelsesøkten, men den er ikke en hemmelighet for backend-systemet.
  • Kortvarig. Nåværende oppstartstokener utløper etter 10 timer; oppdater ved å åpne utvidelsessiden på nytt.
  • Kreves som x-chastify-main-token når backend-en kaller installed-extension-øktruter, slik at Chastify kan binde backend-forespørselen til brukeren/økten som åpnet utvidelsen.
  • Må ikke brukes alene til å autorisere tidsendringer, opplåsing av blokkeringsfullføring, oppgavefullføring, enhetskommandoer, opplastinger/slettinger under kjøring, tilpassede logger eller tilpassede varsler.

App-omfattet utvikler-API-nøkkel​

  • Opprettet fra utviklergrensesnittet for én utvidelsesapp.
  • Kun for backend-hemmelighet. Legg den aldri i iframe JavaScript, mobilapppakker, statisk hostingkonfigurasjon eller nettleserlesbare logger.
  • Brukes med Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY og x-chastify-main-token.
  • Kan bare kalle API-er for installerte utvidelser for økter som samsvarer med utvidelsesappen og oppstartstokenet.
  • Utløper ikke automatisk. Tilbakekall den umiddelbart hvis den eksponeres, og roter backend-miljøvariabelen din.

Brukeromfattende utvikler-API-nøkkel​

  • Opprettet fra utviklergrensesnittet uten å velge en utvidelsesapp.
  • Kun backend-hemmelighet for /api/apps/v1/*.
  • Kontrollerer nøkkeleierens egne nåværende/fremtidige aktive låseøkter.
  • Kan ikke brukes som en installert tredjepartsutvidelses backend-legitimasjon.

Tilbakekalling​

  • Tilbakekalte utvikler-API-nøkler slutter å autorisere nye forespørsler.
  • Tilbakekalte nøkler kan slettes permanent fra utviklergrensesnittet.
  • Nye iframe-lanseringer mottar nye lanseringstokener. Ikke lagre mainToken som en langsiktig legitimasjon.

Omfang og roller​

  • Omfang for utvidelsesapp beskriver hva appen har lov til å be om.
  • Sikre iframe-brokall er begrenset til UI-oppstart, øktlesninger, utvidelseseid tilstand, metadatalesninger, vanlige handlingslesninger og fillesninger.
  • Privilegerte mutasjoner i installerte økter krever backend-legitimasjon selv når utvidelsen har et samsvarende omfang.
  • Rollesensitive handlinger kan fortsatt bli avvist basert på om utskytningen tilhører en bruker eller nøkkelinnehaver.

Revisjon og grenser​

  • Metadata for sist brukte Developer API-nøkler oppdateres når nøkler brukes.
  • Privilegerte handlingsruter er hastighetsbegrensede og returnerer eksplisitte feil som server_credentials_required eller user_wide_dev_key_required når feil legitimasjonstype brukes.
  • Tilpassede logger skriver synlige oppføringer i låsehistorikken.
  • Tilpassede varsler oppretter Chastify-varsler for det forespurte målet.
  • Full revisjonsdekning for hver mutasjon i privilegerte utvidelser spores som et produksjonsherdingselement.

Støttede kommandoverdier​

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

name støtter:

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

Handlingsbegrensninger:

  • Oppgavehandlinger krever at Oppgaver-utvidelsen/modulen er aktivert på låsen.
  • hygienic_unlock.start krever aktivert hygienisk åpning og ingen aktiv hygieneøkt.

session.get låsedatahjelpere​

session.get / GET /api/apps/v1/session inkluderer også lockData med kjøretidsvennlige boolske verdier, tall og strenger for regelmotorer.

Eksempler:

  • boolske verdier: frozen, unlockable, trusted, taskAssigned (true når en åpen TaskRun finnes)
  • tall: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • strenger: lockTitle, felt for bruker-/nøkkelholderprofil

Privatliv:

  • wearerLastSeenTimestamp og keyholderLastSeenTimestamp er null når brukeren har deaktivert online-status (showOnlineStatus === false).

Enhetskommandoer​

Utvidelsesøkter kan bruke det øktbaserte endepunktet:

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

Eksterne programmer med et DEV-token kan bruke det enklere v1-endepunktet (ingen økt-ID nødvendig):

POST /api/apps/v1/device-command

Begge godtar samme forespørselstekst og returnerer samme svar. Se Eksternt API og programmer for fullstendige detaljer.

Oppsettside (valgfritt, anbefalt)​

Hvis utvidelsen din har et brukergrensesnitt for oppsett/konfigurasjon:

  1. Foreldre sender chastify:ext:setup:init (lagret konfigurasjon + kontekst).
  2. Din oppsatte iframe returnerer oppdateringer med chastify:ext:setup:config.
  3. Foreldre kan be om gjeldende konfigurasjon med chastify:ext:setup:get_config.

Backend-tokenflyt (når du trenger serversidekall)​

For enkle skript og eksterne programmer, bruk et brukeromfattende DEV-token fra Developer API-siden. Se Eksternt API og programmer.

Standardflyt i iframe-modus for utvidelsen:

  1. Chastify utsteder et kortlivet nettlesersynlig oppstartstoken for den aktive utvidelsesøkten.
  2. Lanseringstokenet er innebygd i iframe-hash-nyttelasten som mainToken.
  3. Iframen din videresender mainToken til backend-en din.
  4. Backend-systemet ditt kaller https://chastify.net/api/extensions/sessions/:sessionId/* med Authorization: Bearer <app-scoped Developer API key> og x-chastify-main-token: <mainToken>.

Ikke send utvikler-API-nøkler til iframe/nettleserkode. mainToken identifiserer den åpnede utvidelsesøkten; den er ikke en backend-hemmelighet og kan ikke brukes alene til privilegerte handlinger.

Manuell reserve:

  • Hvis du trenger å hente/rotere iframe-oppstartstokenet eksplisitt fra førstepartsgrensesnittet, kall GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Bruk backend-modus hvis du trenger planlagte jobber, webhooks eller automatisering mens Chastify-siden ikke er åpen. Gjeldende øktmutasjoner for installerte utvidelser krever fortsatt et gyldig 10-timers iframe-oppstartstoken, så uovervåkede jobber bør lagre ventende bevis og sende det inn ved neste gyldige oppstart, med mindre du bruker en førsteparts-/innebygd serverflyt som er designet for bakgrunnskjøring.

info

For fullstendig uovervåket produksjonsatferd, foretrekk en innebygd/førsteparts serverflyt eller vent på eksplisitte bakgrunnsutvidelsesgodkjenninger. App-omfattede økt-API-er er for øyeblikket bundet til oppstartstoken.

Backend vs. Cloudflare-sider (ingen server)​

Bruk Cloudflare Pages (uten backend-server) når:​

  • Du ønsker det enkleste og billigste oppsettet (kan hostes gratis).
  • Du trenger bare brukergrensesnittdrevne handlinger mens brukeren er aktivt på utvidelsessiden din.
  • Du trenger ikke servervedvarende skriving av utvidelsestilstand.
  • Du prototyper eller bygger lette utvidelser raskt.

Eksempel på lokal testing (PowerShell):

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

Bruk den genererte offentlige URL-en som iframe-URL under testing.

Bruk en backend-server når:​

  • Du trenger planlagte jobber (cron-lignende oppførsel).
  • Du trenger webhooks eller eksterne integrasjoner.
  • Du trenger automatisering/bakgrunnsbehandling når ingen er på utvidelsessiden.
  • Du trenger serverstyrte arbeidsflyter som må kjøre kontinuerlig.

Viktig begrensning uten backend:

  • Ingen bakgrunnskjøring. Utvidelsen din kan bare utføre handlinger mens en bruker har utvidelsens iframe åpen og samhandler med den.

Vanlige problemer​

  • 403 extension_not_enabled: utvidelsen er ikke aktivert for denne låsen.
  • 409 lock_ended: låsen er ikke lenger aktiv.
  • 429: hastighetsgrense nådd.
  • Ingen svar i iframe: sjekk nonce, targetOrigin (parentOrigin) og tillatte opprinnelser.

Neste guider​