Skip to main content

Isprobajte API za razvojne programere proširenja

Koristite ovaj vodič ako želite izraditi Chastify proširenje, hostirati stranicu iframe proširenja ili pozvati Developer API iz vlastitog backenda.

Ova stranica je početna točka: koji način rada odabrati, što prvo pozvati i kamo sljedeće ići.

Za konkretno ponašanje proširenja kao što su blokatori otključavanja, redovite potrebne radnje, nagrade i kazne, pogledajte Značajke API-ja proširenja.

tip

Želite li samo kontrolirati vlastitu bravu?

Ako ne trebate izraditi javno proširenje, stranica Vanjski API i programi najlakši je način za početak. Samo izradite DEV token i pozovite jednostavne REST krajnje točke - nije potrebno postavljanje proširenja, nije potreban iframe, nije potrebno upravljanje sesijama. Podržava dodavanje/uklanjanje vremena, zamrzavanje, zadatke, naredbe uređaja i još mnogo toga.

Čemu služi ovaj API​

API za razvojne programere proširenja omogućuje vam izradu proširenja trećih strana koja se pokreću unutar sesija zaključavanja Chastify.

S njim možete:

  • Čitanje sesije i kontekst zaključavanja (session.get za proširenja, /api/apps/v1/session za vašu vlastitu automatizaciju zaključavanja)
  • Čitanje podataka u vlasništvu ekstenzije po sesiji zaključavanja (state.get) i njihovo zapisivanje iz vašeg backenda (PUT/PATCH /state)
  • Pohranite slikovne datoteke u vlasništvu ekstenzije pomoću R2 pohrane kojom upravlja Chastify (files.*)
  • Dodajte akcije korisničkog sučelja proširenja na karticama zaključavanja (metadata.homeActions)
  • Tijek otključavanja vrata s blokatorima otključavanja u vlasništvu ekstenzije (metadata.unlockBlockers)
  • Pokretanje radnji zaključavanja iz pouzdanog pozadinskog sustava (dodavanje/uklanjanje vremena, zamrzavanje/odmrzavanje, zakrpa postavki)
  • Okidanje zadataka i higijenskih radnji (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Slanje redovnih radnji s podrškom za brojače/ritam
  • Pošalji podržane naredbe uređaja kada su dostupne
  • Zapisivanje prilagođenih unosa u dnevnik proširenja za zaključavanje povijesti

Što možete izgraditi​

Pravi skup značajki ovisi o tome gdje se povjerenje nalazi.

Proširenja iframea samo za frontend mogu izgraditi iskustva usmjerena na korisničko sučelje koja ne zahtijevaju mutaciju pouzdanog zaključavanja:

  • Stranice za postavljanje koje prikupljaju konfiguraciju proširenja
  • Nadzorne ploče koje čitaju kontekst sesije
  • Korisnička sučelja zagonetki, kontrolnih popisa ili igara koja čitaju stanje sesije i šalju provjereni napredak putem pozadinskog sustava
  • Tokovi temeljeni na medijima koji čitaju datoteke proširenja koje je već pohranio Chastify
  • Ulazne točke za početnu radnju koje otvaraju vaš iframe s namjerom

Proširenja podržana od strane poslužitelja mogu izgraditi značajke koje utječu na zaključavanje jer vaš backend provjerava ishode prije pozivanja privilegiranih API-ja:

  • Sustavi zadataka ili navika sa zahtjevima za otključavanje
  • Dnevni ili tjedni zahtjevi s planiranim kaznama za propuštene prozore
  • Igre koje nagrađuju uspjeh ili kažnjavaju neuspjeh promjenama vremena zaključavanja
  • Tokovi provjere koji uklanjaju blokatore otključavanja nakon validacije na strani poslužitelja
  • Popratni tokovi upravljanja uređajima pomoću podržanih naredbi uređaja
  • Tijekovi rada webhooka/baze podataka koji zadržavaju stanje ekstenzije izvan iframea

Vanjski programi su za privatnu automatizaciju vaše vlastite aktivne brave:

  • Lokalne skripte
  • Osobne nadzorne ploče
  • Alati za automatizaciju koji koriste korisnički ključ DEV

Odaberite svoj način rada​

Odaberite jedan od ovih načina rada:

  1. Hosted iframe extension: hostirajte statički iframe UI na Cloudflare Pages ili sličnoj usluzi. Koristite most za postavljanje, kontekst sesije i sigurna čitanja. Nemojte koristiti ovaj način rada samo za pisanje stanja, nagrade, kazne, otključavanje dovršetka ili napredak u pouzdanim zahtjevima.
  2. Server-backed extension: hostirajte iframe UI i pokrenite vlastiti backend. IFrame šalje svoj mainToken za pokretanje vašem backendu, a vaš backend poziva Chastify Extension API s ključem Developer API-ja s opsegom aplikacije i x-chastify-main-token. Koristite ovaj način rada za privilegirane radnje, otključavanje blokatora, pouzdani napredak, nagrade, kazne, webhookove i vanjske baze podataka.
  3. External API & Programs: koristite korisnički ključ DEV za skripte, lokalne programe ili automatizacije koje kontroliraju vašu aktivnu bravu. Ovo nije način rada za korisnike trećih strana koji instaliraju vaše proširenje.

Ako brzo testirate, počnite s iframe načinom rada za korisničko sučelje i sigurna čitanja. Dodajte pozadinski sustav prije implementacije pisanja stanja, pouzdanih nagrada, promjena vremena, planiranog napretka zahtjeva ili dovršetka blokade otključavanja.

caution

Iframe kod nije granica povjerenja. Sve što je vidljivo iframeu, uključujući hash payloads i tokene za lansiranje, korisnik može pregledati i ponovno reproducirati.

Prvih 10 minuta (iframe način rada)​

  1. Pročitajte location.hash korisni teret iz otvorenog Chastify iframea.
  2. Kreirajte zahtjev za premošćivanje za session.get.
  3. Potvrdite odgovor sa type: "chastify:ext:resp" i ok: true.
  4. Testno stanje se očitava sa state.get.
  5. Dodajte automatsku promjenu veličine + podršku za temu kako bi se iframe ispravno ponašao u korisničkom sučelju.

Podrška za teme dio je iframea spremnog za produkciju. Chastify prosljeđuje vrijednosti ui u hashu pokretanja i šalje ažuriranja teme uživo dok je iframe otvoren. Pogledajte Iframe Theming za primjere svijetlih/tamnih boja i kontrastno sigurne Tailwind uzorke.

Potrebne vrijednosti korisnog tereta:

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

Primjer zahtjeva za most:

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

Primjer odgovora mosta:

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

Ključne radnje koje prvo treba naučiti​

  • session.get
  • state.get
    Pročitajte JSON pohranu u vlasništvu proširenja za zaključanu sesiju. Zapišite stanje iz pozadine s vjerodajnicama Developer API-ja.
  • files.capabilities, files.list, files.get Koristite čitanje pohrane datoteka za binarne medije kao što su slike slagalica ili generirani pregledi. Pohranite ID-ove datoteka u stanju napisanom u pozadini, a zatim osvježite potpisane URL-ove s files.get.
  • metadata.get Čita blokatore otključavanja sesije zaključavanja i početne radnje/namjere proširenih kartica.
  • regularActions.get

Mutacije sesija kao što su pisanje stanja, slanje redovnih radnji, prijenos/brisanje datoteka tijekom izvođenja, promjene vremena, ažuriranja blokatora otključavanja, dovršetak zadatka, pokretanje higijene i naredbe uređaja moraju se pozvati s vašeg backenda s ključem API-ja razvojnog programera. Kod iframea preglednika nije pouzdan za ove radnje.

Potpuni API URL-ovi (podržani)​

Osnovna domena: https://chastify.net

API-ji sesije proširenja (/api/extensions/*)​

Ove rute imaju različite načine pristupa. Nemojte tretirati cijelu površinu /api/extensions/* kao sigurnu za iframe.

Sigurne rute iframe mosta usmjeravaju se kroz roditelja Chastify nakon zahtjeva za mostom postMessage:

  • 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

Rute instaliranih proširenja samo za pozadinsku komponentu zahtijevaju ključ API-ja razvojnih programera s opsegom aplikacije i token za pokretanje iframea:

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

Ovaj model s dva tokena veže backend zahtjev i za razvojnog programera proširenja (Authorization) i za trenutno otvorenu sesiju proširenja (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

API-ji pozadinskih tokena (/api/apps/v1/*)​

Koristite Authorization: Bearer <user-wide DEV token>. Ove krajnje točke upravljaju aktivnim sesijama zaključavanja vlasnika tokena i namijenjene su za vanjske API skripte/programe, a ne za instalirane sesije proširenja trećih strana.

  • 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

Naredbe mosta Iframe​

Korisni tereti naredbi mosta šalju se putem iframea (chastify:ext:req) i usmjeravaju se od strane roditelja Chastify. Most je namjerno ograničen na sigurne/sesijske UI operacije.

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

Krajnje točke mutacije sesije su izravni pozivi backend API-ja, a ne naredbe iframe mosta. To uključuje pisanje stanja, slanje redovnih radnji i prijenos/brisanje datoteka tijekom izvođenja, jer korisnik može kontrolirati iframe kod.

Primjeri API-ja za pozadinske sesije​

Vaš backend mora poslati oba zaglavlja za privilegirane pozive instaliranog proširenja:

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

Primjeri pozadinskih radnji:

  • 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 sa { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action sa { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action sa { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action sa { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action sa { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action sa { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action sa { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action sa { "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, opseg, opoziv i ponašanje revizije​

Koristite pravi token za pravu granicu povjerenja.

warning

Ključevi API-ja za razvojne programere su tajni. Ako je jedan od njih izložen kodu preglednika, odmah ga poništite i rotirajte varijablu okruženja pozadine.

Token za pokretanje iframea (mainToken)​

  • Isporučuje se u iframe hashu kada korisnik otvori instaliranu stranicu proširenja.
  • Vidljivo pregledniku po dizajnu. Identificira otvorenu sesiju proširenja, ali nije tajna pozadinskog sustava.
  • Kratkotrajno. Trenutni tokeni za lansiranje istječu nakon 10 sati; osvježite ponovnim otvaranjem stranice proširenja.
  • Obavezno kao x-chastify-main-token kada vaš backend poziva rute sesije instaliranog proširenja, tako da Chastify može povezati backend zahtjev s korisnikom/sesijom koja je otvorila proširenje.
  • Ne smije se koristiti samostalno za autorizaciju promjena vremena, otključavanje dovršetka blokatora, dovršetak zadataka, naredbe uređaja, prijenos/brisanje tijekom izvođenja, prilagođene zapisnike ili prilagođene obavijesti.

Ključ API-ja za razvojne programere na razini aplikacije​

  • Izrađeno iz korisničkog sučelja za razvojne programere za jednu aplikaciju proširenja.
  • Tajna samo za pozadinsku uslugu. Nikada je ne stavljajte u iframe JavaScript, pakete mobilnih aplikacija, konfiguraciju statičkog hostinga ili zapisnike čitljive u pregledniku.
  • Koristi se sa Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY i x-chastify-main-token.
  • API-je sesija instaliranih proširenja moguće je pozvati samo za sesije koje odgovaraju aplikaciji proširenja i tokenu za pokretanje.
  • Ne istječe automatski. Odmah ga poništite ako je otkriven i rotirajte varijablu okruženja pozadinske komponente.

Ključ API-ja za razvojne programere za cijeli korisnik​

  • Izrađeno iz korisničkog sučelja za razvojne programere bez odabira aplikacije proširenja.
  • Tajna samo za pozadinsku konfiguraciju za /api/apps/v1/*.
  • Kontrolira trenutne/buduće aktivne sesije zaključavanja vlasnika ključa.
  • Ne može se koristiti kao instalirana pozadinska vjerodajnica za proširenje treće strane.

Opoziv​

  • Opozvani ključevi API-ja razvojnih programera zaustavljaju autorizaciju novih zahtjeva.
  • Opozvani ključevi mogu se trajno izbrisati iz korisničkog sučelja za razvojne programere.
  • Nova pokretanja iframea dobivaju nove tokene za lansiranje. Nemojte pohranjivati ​​mainToken kao dugoročne vjerodajnice.

Opsezi i uloge​

  • Opsezi aplikacije proširenja opisuju što aplikacija smije zahtijevati.
  • Sigurni pozivi iframe mosta ograničeni su na UI bootstrap, čitanje sesije, stanje u vlasništvu ekstenzije, čitanje metapodataka, čitanje regularnih radnji i čitanje datoteka.
  • Privilegirane mutacije instalirane sesije zahtijevaju pozadinske vjerodajnice čak i kada proširenje ima odgovarajući opseg.
  • Radnje osjetljive na uloge i dalje mogu biti odbijene na temelju toga pripada li lansiranje korisniku ili vlasniku ključa.

Revizija i ograničenja​

  • Metapodaci zadnje korištenog ključa API-ja razvojnog programera ažuriraju se kada se koriste ključevi.
  • Privilegirane rute akcija imaju ograničenu brzinu i vraćaju eksplicitne pogreške poput server_credentials_required ili user_wide_dev_key_required kada se koristi pogrešan tip vjerodajnice.
  • Prilagođeni zapisnici zapisuju vidljive unose povijesti zaključavanja.
  • Prilagođene obavijesti stvaraju Chastify obavijesti za traženi cilj.
  • Potpuna pokrivenost revizije za svaku mutaciju privilegiranog proširenja prati se kao stavka osiguranja produkcije.

Podržane vrijednosti naredbi​

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

name podržava:

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

Ograničenja djelovanja:

  • Radnje zadataka zahtijevaju omogućeno proširenje/modul Zadaci na bravi.
  • hygienic_unlock.start zahtijeva omogućeno higijensko otvaranje i bez aktivne higijenske sesije.

session.get pomoćnici za zaključavanje podataka​

session.get / GET /api/apps/v1/session također uključuje lockData s logičkim vrijednostima, brojevima i nizovima znakova prilagođenim za izvođenje za mehanizme pravila.

Primjeri:

  • logičke vrijednosti: frozen, unlockable, trusted, taskAssigned (true kada postoji otvoreni TaskRun)
  • brojevi: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • nizovi znakova: lockTitle, polja profila korisnika/vlasnika ključa

Privatnost:

  • wearerLastSeenTimestamp i keyholderLastSeenTimestamp su null kada je taj korisnik onemogućio online status (showOnlineStatus === false).

Naredbe uređaja​

Sesije proširenja mogu koristiti krajnju točku temeljenu na sesiji:

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

Vanjski programi s tokenom DEV mogu koristiti jednostavniju v1 krajnju točku (nije potreban ID sesije):

POST /api/apps/v1/device-command

Oba prihvaćaju isto tijelo zahtjeva i vraćaju isti odgovor. Za više detalja pogledajte Vanjski API i programi.

Stranica za postavljanje (neobavezno, preporučeno)​

Ako vaše proširenje ima korisničko sučelje za postavljanje/konfiguraciju:

  1. Roditelj šalje chastify:ext:setup:init (spremljena konfiguracija + kontekst).
  2. Vaš iframe postavki vraća ažuriranja sa chastify:ext:setup:config.
  3. Roditelj može zatražiti trenutnu konfiguraciju pomoću chastify:ext:setup:get_config.

Tok pozadinskih tokena (kada su vam potrebni pozivi na strani poslužitelja)​

Za jednostavne skripte i vanjske programe koristite korisnički token DEV sa stranice Developer API. Pogledajte Vanjski API i programi.

Zadani tok u načinu rada iframe proširenja:

  1. Chastify izdaje kratkotrajni token za pokretanje vidljiv pregledniku za aktivnu sesiju proširenja.
  2. Token za lansiranje ugrađen je u iframe hash payload kao mainToken.
  3. Vaš iframe prosljeđuje mainToken vašem backendu.
  4. Vaš backend poziva https://chastify.net/api/extensions/sessions/:sessionId/* sa Authorization: Bearer <app-scoped Developer API key> i x-chastify-main-token: <mainToken>.

Ne šaljite ključeve API-ja razvojnih programera u iframe/kod preglednika. mainToken identificira otvorenu sesiju proširenja; nije tajna pozadinske mreže i ne može se samostalno koristiti za privilegirane radnje.

Ručni povrat:

  • Ako trebate eksplicitno dohvatiti/rotirati token za lansiranje iframea iz korisničkog sučelja prve strane, pozovite GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Koristite backend način rada ako su vam potrebni zakazani zadaci, webhookovi ili automatizacija dok stranica Chastify nije otvorena. Trenutne mutacije sesije instaliranog proširenja i dalje zahtijevaju valjani 10-satni token za pokretanje iframea, pa bi nenadzirani zadaci trebali pohraniti dokaz na čekanju i poslati ga pri sljedećem valjanom pokretanju, osim ako ne koristite tok poslužitelja prve strane/ugrađenog poslužitelja dizajniran za pozadinsko izvršavanje.

info

Za potpuno nenadzirano produkcijsko ponašanje, preferirajte ugrađeni/first-party server tok ili pričekajte eksplicitna odobrenja za pozadinska proširenja. API-ji sesija ograničeni na aplikaciju trenutno su vezani za token za pokretanje.

Backend u odnosu na Cloudflare stranice (bez servera)​

Koristite Cloudflare Pages (bez backend servera) kada:​

  • Želite najjednostavniju i najjeftiniju instalaciju (može se hostirati besplatno).
  • Potrebne su vam samo akcije vođene korisničkim sučeljem dok je korisnik aktivno na vašoj stranici proširenja.
  • Ne trebate zapisivanje stanja ekstenzije koje se čuva na poslužitelju.
  • Brzo izrađujete prototipove ili lagana proširenja.

Primjer lokalnog testiranja (PowerShell):

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

Koristite generirani javni URL kao URL iframea tijekom testiranja.

Koristite backend poslužitelj kada:​

  • Trebaju vam zakazani poslovi (ponašanje slično cronu).
  • Trebaju vam webhookovi ili vanjske integracije.
  • Potrebna vam je automatizacija/obrada u pozadini kada nitko nije na stranici proširenja.
  • Potrebni su vam tijekovi rada kontrolirani od strane poslužitelja koji se moraju izvoditi kontinuirano.

Važno ograničenje bez pozadinskog sustava:

  • Nema izvršavanja u pozadini. Vaše proširenje može poduzimati radnje samo dok korisnik trenutno ima otvoren iframe proširenja i komunicira s njim.

Uobičajeni problemi​

  • 403 extension_not_enabled: proširenje nije omogućeno za ovu bravu.
  • 409 lock_ended: brava više nije aktivna.
  • 429: dosegnuto je ograničenje brzine.
  • Nema odgovora u iframeu: provjerite nonce, targetOrigin (parentOrigin) i dopuštena porijekla.

Sljedeći vodiči​