Passa al contenuto principale

Prova l'API per sviluppatori di estensioni

Utilizza questa guida se desideri creare un'estensione Chastify, ospitare una pagina di estensione iframe o chiamare l'API per sviluppatori dal tuo backend.

Questa pagina è il punto di partenza: quale modalità scegliere, cosa chiamare per primo e dove andare dopo.

Per informazioni concrete sul comportamento delle estensioni, come lo sblocco dei blocchi, le azioni richieste regolarmente, i premi e le punizioni, consultare Funzionalità dell'API delle estensioni.

suggerimento

Vuoi semplicemente controllare la tua serratura?

Se non hai bisogno di creare un'estensione pubblica, la pagina API e programmi esterni è il modo più semplice per iniziare. Ti basta creare un token DEV e chiamare semplici endpoint REST: non è richiesta alcuna configurazione di estensioni, iframe o gestione delle sessioni. Supporta l'aggiunta/rimozione di tempo, il blocco, le attività, i comandi del dispositivo e altro ancora.

A cosa serve questa API​

L'API per sviluppatori di estensioni consente di creare esperienze di estensione di terze parti che vengono eseguite all'interno di sessioni di blocco Chastify.

Con esso puoi:

  • Leggere il contesto della sessione e del blocco (session.get per le estensioni, /api/apps/v1/session per la propria automazione del blocco)
  • Leggi i dati di proprietà dell'estensione per ogni sessione di blocco (state.get) e scrivili dal tuo backend (PUT/PATCH /state)
  • Archivia i file immagine di proprietà dell'estensione con l'archiviazione R2 gestita da Chastify (files.*)
  • Aggiungi azioni UI di estensione sulle schede di blocco (metadata.homeActions)
  • Flusso di sblocco del cancello con blocchi di sblocco di proprietà dell'estensione (metadata.unlockBlockers)
  • Attiva le azioni di blocco da un backend affidabile (aggiungi/rimuovi tempo, blocca/sblocca, modifica impostazioni)
  • Attivazione dell'attività e delle azioni igieniche (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Invia azioni regolari con supporto contatori/cadenza
  • Invia i comandi del dispositivo supportato quando disponibili
  • Scrivi voci di registro di estensione personalizzate per bloccare la cronologia

Cosa puoi costruire​

La giusta combinazione di funzionalità dipende da dove risiede la fiducia.

Le estensioni iframe solo per il frontend possono creare esperienze incentrate sull'interfaccia utente che non necessitano di mutazioni di blocco affidabili:

  • Pagine di configurazione che raccolgono la configurazione dell'estensione
  • Dashboard che leggono il contesto della sessione
  • Interfacce utente di puzzle, checklist o giochi che leggono lo stato della sessione e inviano i progressi verificati tramite un backend
  • Flussi basati su supporti che leggono i file di estensione già memorizzati da Chastify
  • Punti di ingresso azione home che aprono il tuo iframe con un intento

Le estensioni basate su server possono creare funzionalità che influiscono sui blocchi perché il backend verifica i risultati prima di chiamare le API privilegiate:

  • Sistemi di attività o abitudini con requisiti di sblocco
  • Requisiti giornalieri o settimanali con sanzioni programmate per il mancato rispetto delle finestre temporali.
  • Giochi che premiano il successo o penalizzano il fallimento con modifiche al tempo di blocco
  • Flussi di verifica che rimuovono i blocchi di sblocco dopo la convalida lato server
  • Flussi complementari di controllo del dispositivo che utilizzano comandi del dispositivo supportati
  • Flussi di lavoro Webhook/database che mantengono lo stato dell'estensione al di fuori dell'iframe

I programmi esterni servono per l'automazione privata della propria serratura attiva:

  • Script locali
  • dashboard personali
  • Strumenti di automazione che utilizzano una chiave DEV a livello di utente

Scegli la tua modalità​

Scegli una di queste modalità:

  1. Hosted iframe extension: ospita un'interfaccia utente iframe statica su Cloudflare Pages o un servizio simile. Utilizza il bridge per la configurazione, il contesto di sessione e le letture sicure. Non utilizzare questa modalità da sola per la scrittura dello stato, i premi, le punizioni, il completamento dello sblocco o l'avanzamento dei requisiti di affidabilità.
  2. Server-backed extension: ospita l'interfaccia utente dell'iframe ed esegui il tuo backend. L'iframe invia il suo codice di avvio mainToken al tuo backend, e il tuo backend chiama l'API di estensione Chastify con una chiave API per sviluppatori con ambito app più x-chastify-main-token. Utilizza questa modalità per azioni privilegiate, sblocco di blocchi, progressi affidabili, premi, punizioni, webhook e database esterni.
  3. External API & Programs: utilizzare un tasto DEV valido per tutti gli utenti per script, programmi locali o automazioni che controllano il proprio lucchetto attivo. Questa non è la modalità per gli utenti di terze parti che installano l'estensione.

Se stai eseguendo dei test rapidi, inizia con la modalità iframe per l'interfaccia utente e le letture sicure. Aggiungi un backend prima di implementare la scrittura dello stato, le ricompense affidabili, le modifiche temporali, l'avanzamento dei requisiti programmati o il completamento dei blocchi di sblocco.

attenzione

Il codice dell'iframe non costituisce un confine di fiducia. Tutto ciò che è visibile all'iframe, inclusi i payload degli hash e i token di avvio, può essere ispezionato e riprodotto dall'utente.

Primi 10 minuti (modalità iframe)​

  1. Legge il payload location.hash dall'iframe Chastify aperto.
  2. Crea una richiesta di bridge per session.get.
  3. Conferma la risposta con type: "chastify:ext:resp" e ok: true.
  4. Test dello stato di lettura con state.get.
  5. Aggiungi il ridimensionamento automatico e il supporto per i temi in modo che l'iframe si comporti correttamente nell'interfaccia utente.

Il supporto per i temi è parte integrante di un iframe pronto per la produzione. Chastify trasmette i valori ui nell'hash di avvio e invia aggiornamenti del tema in tempo reale mentre l'iframe è aperto. Vedi Temi per iframe per esempi di temi chiari/scuri e pattern Tailwind compatibili con il contrasto.

Valori di carico utile richiesti:

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

Esempio di richiesta di bridge:

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

Esempio di risposta del ponte:

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

Azioni fondamentali da imparare per prime​

  • session.get
  • state.get
    Leggi lo storage JSON di proprietà dell'estensione per la sessione di blocco. Scrivi lo stato dal tuo backend con le credenziali dell'API per sviluppatori.
  • files.capabilities, files.list, files.get Utilizza la lettura della memoria di file per i file multimediali binari, come le immagini dei puzzle o le anteprime generate. Memorizza gli ID dei file nello stato scritto dal backend, quindi aggiorna gli URL firmati con files.get.
  • metadata.get Leggere i blocchi di sblocco della sessione di blocco e le azioni/intenzioni relative alla schermata iniziale della scheda di estensione.
  • regularActions.get

Le modifiche di sessione, come la scrittura dello stato, l'invio di azioni regolari, il caricamento/eliminazione di file in fase di esecuzione, le modifiche dell'ora, gli aggiornamenti del blocco di sblocco, il completamento delle attività, gli avvii di pulizia e i comandi del dispositivo, devono essere richiamate dal backend con una chiave API per sviluppatori. Il codice iframe del browser non è considerato affidabile per queste azioni.

URL API completi (supportati)​

Dominio base: https://chastify.net

API di estensione della sessione (/api/extensions/*)​

Questi percorsi hanno diverse modalità di accesso. Non considerare l'intera superficie /api/extensions/* come sicura per gli iframe.

I percorsi sicuri del bridge iframe vengono instradati attraverso il genitore Chastify dopo le richieste del bridge 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

Le route di estensione installate solo nel backend richiedono una chiave API per sviluppatori con ambito app e il token di avvio iframe:

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

Questo modello a due token associa una richiesta backend sia allo sviluppatore dell'estensione (Authorization) sia alla sessione dell'estensione attualmente aperta (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 del token di backend (/api/apps/v1/*)​

Utilizzare Authorization: Bearer <user-wide DEV token>. Questi endpoint gestiscono le sessioni di blocco attive del proprietario del token e sono destinati a script/programmi API esterni, non a sessioni di estensioni di terze parti installate.

  • 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

Comandi di Iframe Bridge​

I payload dei comandi del bridge vengono inviati tramite iframe (chastify:ext:req) e instradati dal nodo padre Chastify. Il bridge è intenzionalmente limitato alle operazioni sicure/dell'interfaccia utente di sessione.

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

Gli endpoint di mutazione della sessione sono chiamate API dirette al backend, non comandi del bridge iframe. Ciò include la scrittura dello stato, l'invio di azioni regolari e il caricamento/eliminazione di file in fase di esecuzione, poiché il codice iframe può essere controllato dall'utente.

Esempi di API di sessione backend​

Il tuo backend deve inviare entrambe le intestazioni per le chiamate privilegiate dell'estensione installata:

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

Esempi di azioni di backend:

  • 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 con { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action con { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action con { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action con { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action con { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action con { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action con { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action con { "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, ambito, revoca e comportamento di audit​

Utilizzare il token corretto per il confine di fiducia appropriato.

warning

Le chiavi API per sviluppatori sono segrete. Se una di esse viene esposta al codice del browser, revocatela immediatamente e modificate la variabile d'ambiente del backend.

Token di avvio dell'iframe (mainToken)​

  • Viene trasmesso nell'hash dell'iframe quando un utente apre la pagina di un'estensione installata.
  • Visibile nel browser per impostazione predefinita. Identifica la sessione dell'estensione aperta, ma non è un segreto di sistema.
  • Di breve durata. I token di lancio attuali scadono dopo 10 ore; per aggiornarli, riapri la pagina dell'estensione.
  • Richiesto come x-chastify-main-token quando il backend chiama le route di sessione dell'estensione installata, in modo che Chastify possa associare la richiesta del backend all'utente/sessione che ha aperto l'estensione.
  • Non deve essere utilizzato da solo per autorizzare modifiche dell'ora, sblocco del completamento del blocco, completamento delle attività, comandi del dispositivo, caricamenti/eliminazioni in fase di esecuzione, registri personalizzati o notifiche personalizzate.

Chiave API per sviluppatori con ambito applicativo​

  • Creato dall'interfaccia utente per sviluppatori per un'app di estensione.
  • Segreto accessibile solo dal backend. Non inserirlo mai in iframe JavaScript, bundle di app per dispositivi mobili, configurazioni di hosting statiche o log leggibili dal browser.
  • Utilizzato con Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY e x-chastify-main-token.
  • È possibile chiamare le API di sessione delle estensioni installate solo per le sessioni che corrispondono all'app dell'estensione e al token di avvio.
  • Non scade automaticamente. Revocalo immediatamente se esposto e ruota la variabile d'ambiente del backend.

Chiave API per sviluppatori a livello utente​

  • Creato dall'interfaccia utente per sviluppatori senza selezionare un'app di estensione.
  • Segreto accessibile solo dal backend per /api/apps/v1/*.
  • Controlla le sessioni di blocco attive attuali e future del proprietario della chiave.
  • Non può essere utilizzato come credenziale di backend per un'estensione di terze parti installata.

Revoca​

  • Le chiavi API per sviluppatori revocate non consentono più l'autorizzazione di nuove richieste.
  • Le chiavi revocate possono essere eliminate definitivamente dall'interfaccia utente per sviluppatori.
  • I nuovi lanci di iframe ricevono token di avvio aggiornati. Non memorizzare mainToken come credenziale a lungo termine.

Ambiti e ruoli​

  • Gli ambiti delle app di estensione descrivono quali richieste l'app è autorizzata a effettuare.
  • Le chiamate sicure ai bridge iframe sono limitate al bootstrap dell'interfaccia utente, alla lettura della sessione, allo stato di proprietà dell'estensione, alla lettura dei metadati, alla lettura delle azioni regolari e alla lettura dei file.
  • Le mutazioni privilegiate della sessione installata richiedono le credenziali di backend anche quando l'estensione ha un ambito corrispondente.
  • Le azioni sensibili al ruolo potrebbero comunque essere rifiutate a seconda che il dispositivo di avvio appartenga a chi lo indossa o a chi detiene la chiave.

Revisione contabile e limiti​

  • I metadati relativi all'ultimo utilizzo della chiave API dello sviluppatore vengono aggiornati quando le chiavi vengono utilizzate.
  • Le route di azioni privilegiate sono soggette a limitazioni di frequenza e restituiscono errori espliciti come server_credentials_required o user_wide_dev_key_required quando viene utilizzato un tipo di credenziale errato.
  • I log personalizzati scrivono voci visibili nella cronologia dei blocchi.
  • Le notifiche personalizzate creano notifiche Chastify per il target richiesto.
  • La copertura completa degli audit per ogni mutazione di estensione privilegiata viene tracciata come elemento di protezione della produzione.

Valori di comando supportati​

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

name supporta:

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

Vincoli di azione:

  • Le azioni relative alle attività richiedono che l'estensione/il modulo Attività sia abilitato sulla serratura.
  • hygienic_unlock.start richiede che l'apertura igienica sia abilitata e che non sia attiva alcuna sessione di igiene.

session.get helper dati di blocco​

session.get / GET /api/apps/v1/session include anche lockData con valori booleani, numerici e stringhe adatti all'esecuzione per i motori di regole.

Esempi:

  • valori booleani: frozen, unlockable, trusted, taskAssigned (true quando esiste un TaskRun aperto)
  • numeri: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • stringhe: lockTitle, campi del profilo del portatore/detentore della chiave

Privacy:

  • wearerLastSeenTimestamp e keyholderLastSeenTimestamp diventano null quando l'utente ha disabilitato lo stato online (showOnlineStatus === false).

Comandi del dispositivo​

Le sessioni di estensione possono utilizzare l'endpoint basato su sessione:

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

I programmi esterni con un token DEV possono utilizzare l'endpoint v1 più semplice (non è necessario un ID di sessione):

POST /api/apps/v1/device-command

Entrambe accettano lo stesso corpo della richiesta e restituiscono la stessa risposta. Per maggiori dettagli, consultare API e programmi esterni.

Pagina di configurazione (facoltativa, consigliata)​

Se la tua estensione dispone di un'interfaccia utente di configurazione:

  1. Il genitore invia chastify:ext:setup:init (configurazione salvata + contesto).
  2. Il tuo iframe di configurazione restituisce aggiornamenti con chastify:ext:setup:config.
  3. Il genitore può richiedere la configurazione corrente con chastify:ext:setup:get_config.

Flusso di token backend (quando sono necessarie chiamate lato server)​

Per script semplici e programmi esterni, utilizzare un token DEV valido per tutto l'utente, disponibile nella pagina delle API per sviluppatori. Vedere API e programmi esterni.

Flusso predefinito in modalità iframe di estensione:

  1. Chastify rilascia un token di avvio temporaneo, visibile nel browser, per la sessione attiva dell'estensione.
  2. Il token di lancio è incorporato nel payload dell'hash dell'iframe come mainToken.
  3. Il tuo iframe inoltra mainToken al tuo backend.
  4. Il tuo backend chiama https://chastify.net/api/extensions/sessions/:sessionId/* con Authorization: Bearer <app-scoped Developer API key> e x-chastify-main-token: <mainToken>.

Non inviare le chiavi API per sviluppatori al codice iframe/browser. mainToken identifica la sessione dell'estensione aperta; non è un segreto di backend e non può essere utilizzato da solo per azioni privilegiate.

Ripristino manuale:

  • Se è necessario recuperare/ruotare esplicitamente il token di avvio dell'iframe dall'interfaccia utente proprietaria, chiamare GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Utilizza la modalità backend se hai bisogno di attività pianificate, webhook o automazioni mentre la pagina Chastify non è aperta. Le attuali mutazioni di sessione dell'estensione installata richiedono ancora un token di avvio iframe valido di 10 ore, quindi le attività non presidiate dovrebbero memorizzare la prova in sospeso e inviarla al successivo avvio valido, a meno che tu non stia utilizzando un flusso server proprietario/integrato progettato per l'esecuzione in background.

informazioni

Per un comportamento di produzione completamente automatizzato, è preferibile utilizzare un flusso server integrato/di prima parte oppure attendere le autorizzazioni esplicite per le estensioni in background. Le API di sessione a livello di app sono attualmente vincolate al launch token.

Backend vs Cloudflare Pages (senza server)​

Utilizza Cloudflare Pages (senza server backend) quando:​

  • Desideri la configurazione più semplice ed economica (può essere ospitata gratuitamente).
  • Le azioni gestite dall'interfaccia utente sono necessarie solo quando l'utente si trova attivamente sulla pagina dell'estensione.
  • Non è necessario che lo stato dell'estensione venga salvato sul server.
  • Stai realizzando prototipi o creando estensioni leggere in modo rapido.

Esempio di test in locale (PowerShell):

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

Durante i test, utilizza l'URL pubblico generato come URL dell'iframe.

Utilizzare un server backend quando:​

  • È necessario pianificare delle attività (un comportamento simile a cron).
  • È necessario utilizzare webhook o integrazioni esterne.
  • È necessaria l'automazione/elaborazione in background quando nessuno sta visualizzando la pagina dell'estensione.
  • È necessario disporre di flussi di lavoro controllati da server che devono essere eseguiti in modo continuativo.

Limite importante in assenza di un backend:

  • Nessuna esecuzione in background. La tua estensione può eseguire azioni solo se l'utente ha l'iframe dell'estensione aperto e sta interagendo con esso.

Problemi comuni​

  • 403 extension_not_enabled: l'estensione non è abilitata per questa serratura.
  • 409 lock_ended: il blocco non è più attivo.
  • 429: limite di frequenza raggiunto.
  • Nessuna risposta nell'iframe: verificare nonce, targetOrigin (parentOrigin) e le origini consentite.

Guide successive​