Funzionalità API di estensione

Utilizza questa pagina quando hai già compreso il modello di estensione di base e desideri implementare il comportamento effettivo di un lucchetto: azioni richieste, blocchi di sblocco, regolarità, premi e punizioni.

attenzione

Il codice iframe del browser non è considerato attendibile.

Il tuo iframe può visualizzare l'interfaccia utente e leggere il contesto di sessione sicuro. Qualsiasi operazione che scriva lo stato della sessione, premi chi lo indossa, rimuova del tempo, rimuova un blocco di sblocco, registri i progressi dei requisiti affidabili, avvii o interrompa un timer di tentativi o applichi una punizione deve essere verificata dal tuo backend.

Mappa delle caratteristiche

Funzionalità	Cosa fa	Dove funziona
Sblocca i blocchi	Impedisci lo sblocco finché l'estensione non rimuove un blocco o non registra progressi sufficientemente affidabili	Blocca la configurazione di avvio o le chiamate ai metadati/progressi del backend
Azioni Home	Aggiunge un'azione visibile sulla pagina di blocco, ad esempio "Gioca alla sfida"	Patch di configurazione di avvio del blocco o metadati del backend
Azioni regolari	Consente un numero limitato di azioni dell'utilizzatore per intervallo	Chastify tiene traccia dei contatori; il tuo backend invia azioni attendibili
Avanzamento richiesto	Traccia i requisiti di completamento giornalieri o settimanali	Il tuo backend registra l'avanzamento; lo scheduler Chastify controlla le finestre mancate
Premi	Rimuove il tempo, avvia l'apertura igienica o invia una notifica dopo il successo verificato	Il tuo backend chiama endpoint privilegiati
Punizioni	Aggiunge tempo, blocca, assegna un compito, avvia la gogna o invia una notifica dopo un errore verificato	Il tuo backend chiama endpoint privilegiati

Intestazioni di backend richieste

Gli endpoint di estensione privilegiati richiedono entrambe le intestazioni:

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

Il codice mainToken identifica la sessione di estensione aperta. La chiave API per sviluppatori dimostra che la richiesta proviene dal tuo backend.

Sblocca i bloccanti

Utilizzare i blocchi di sblocco quando chi li indossa deve completare un'operazione prima di sbloccare il dispositivo. Esempi:

• Vinci 3 partite.
• Prova completa dell'allenamento di oggi.
• Completa un puzzle di verifica.
• Completare tutte le azioni di estensione richieste per la finestra corrente.

Sono supportati due modelli.

Blocchi basati sui progressi

Utilizzare initialMetadata.unlockRequirements quando il lucchetto deve essere bloccato non appena viene avviato o viene accettato un modello condiviso. Chastify inizializza lo stato della sessione dell'estensione da questa configurazione generica, in modo che il blocco sia attivo anche prima che l'utente apra l'estensione per la prima volta.

{
  "initialMetadata": {
    "unlockRequirements": [
      {
        "metric": "memory_win",
        "requiredCount": 3,
        "blocker": "Complete 3 memory challenge wins to unlock"
      }
    ],
    "homeActions": [
      {
        "slug": "play-memory-challenge",
        "title": "Play memory challenge",
        "description": "Complete the extension challenge to satisfy the unlock requirement.",
        "icon": "gamepad-2",
        "badge": "Required"
      }
    ]
  }
}

Dopo che il tuo backend ha verificato il completamento in modo affidabile, registra i progressi per la stessa metrica:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/requirements/progress" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "memory_win",
    "amount": 1
  }'

Chastify memorizza questo come progresso di sblocco e considera automaticamente il requisito soddisfatto quando il progresso raggiunge requiredCount. Le schede di sblocco possono mostrare il progresso come 1 of 3 complete.

Utilizzare nomi di metriche stabili. Una metrica rappresenta un requisito di sblocco attivo per quella sessione di estensione.

limiti di tempo per i tentativi

Utilizzare attemptLimit quando un tentativo affidabile deve scadere se non viene completato in tempo. Chastify memorizza il tentativo attivo sotto data.attemptLimits.<metric> e può contrassegnarlo come fallito dopo la scadenza. Questo stato è gestito da Chastify; avviare e far fallire i tentativi tramite gli endpoint di tentativo anziché scrivere data.attemptLimits manualmente.

{
  "attemptLimit": {
    "enabled": true,
    "metric": "memory_win",
    "durationSeconds": 300,
    "startPolicy": "activity"
  }
}

startPolicy può essere activity quando il conto alla rovescia inizia nel momento in cui chi lo indossa inizia a giocare, oppure availability quando il conto alla rovescia inizia non appena l'azione è disponibile per il lucchetto.

Avvia un tentativo dal tuo backend:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/attempts/start" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "memory_win",
    "attemptId": "memory-run-123"
  }'

Quando il tuo backend controlla il tentativo, chiedi a Chastify di farlo fallire se la scadenza è passata:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/attempts/fail-expired" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "memory_win",
    "attemptId": "memory-run-123"
  }'

Se i tentativi falliti devono consumare uno slot di cooldown, invia anche un'azione regolare per il tentativo fallito.

Bloccanti manuali

Utilizza unlockBlockers quando il tuo backend deve decidere manualmente se lo sblocco è bloccato. Modifica i metadati dal tuo backend:

curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/metadata" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "unlockBlockers": [
      "Complete 3 memory challenge wins to unlock"
    ],
    "homeActions": [
      {
        "slug": "play-memory-challenge",
        "title": "Play memory challenge",
        "description": "Complete the extension challenge to satisfy the unlock requirement.",
        "icon": "gamepad-2",
        "badge": "Required",
        "intent": {
          "type": "play",
          "title": "Memory challenge",
          "message": "Complete the required challenge."
        }
      }
    ]
  }'

Rimuovi il blocco dopo che il tuo backend ha verificato il completamento:

curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/metadata" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "unlockBlockers": [],
    "homeActions": [
      {
        "slug": "play-memory-challenge",
        "title": "Memory challenge complete",
        "description": "The extension unlock requirement has been completed.",
        "icon": "check-circle",
        "badge": "Complete"
      }
    ]
  }'

note

unlockBlockers è un metadato manuale. Indica a Chastify che lo sblocco è bloccato finché il backend non rimuove il blocco. initialMetadata.unlockRequirements è un metadato basato sull'avanzamento. Chastify può valutarlo automaticamente in base all'avanzamento affidabile registrato per la metrica corrispondente.

Caratteristica di regolarità

Le azioni regolari sono utili quando a chi le indossa è consentito di fare qualcosa con una cadenza fissa: una volta all'ora, quattro volte al giorno, una volta alla settimana e così via.

È possibile configurare azioni regolari alla creazione dell'estensione di blocco oppure aggiornare la sessione in corso dal backend:

curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/regular-actions/config" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "cumulative",
    "regularitySeconds": 86400,
    "maxActions": 4
  }'

Modalità:

• unlimited: le azioni sono sempre disponibili.
• non_cumulative: una finestra diventa disponibile alla volta; le azioni non utilizzate non si accumulano.
• cumulative: le azioni si accumulano fino a maxActions.

Consulta la disponibilità attuale:

curl "https://chastify.net/api/extensions/sessions/$SESSION_ID/regular-actions" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN"

Invia un'azione regolare affidabile:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/regular-actions" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "kind": "checkin",
      "score": 92
    }
  }'

Utilizza azioni regolari quando la regola principale è "con quale frequenza può verificarsi questa azione?".

Azioni personalizzate richieste

Utilizzare i progressi richiesti quando la regola principale è "quanti completamenti sono richiesti al giorno o alla settimana?".

La configurazione dei requisiti si trova nella configurazione della sessione dell'estensione installata sotto extensionRequirements:

{
  "extensionRequirements": {
    "enabled": true,
    "metric": "completion",
    "requiredCount": 4,
    "cadence": {
      "every": 1,
      "unit": "day",
      "timezone": "UTC"
    },
    "punishment": {
      "type": "add_time",
      "seconds": 1800,
      "reason": "Daily extension requirement missed"
    }
  }
}

Unità di cadenza supportate:

• day
• week

Tipi di punizione per finestra temporale mancata supportati:

• none
• add_time
• freeze
• pillory

Registra i progressi attendibili solo dopo che il tuo backend ha verificato l'azione:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/requirements/progress" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "completion",
    "amount": 1,
    "occurredAt": "2026-05-31T18:42:41.715Z"
  }'

Lo scheduler di Chastify valuta le finestre completate e applica la penalità configurata per le finestre perse se il conteggio delle finestre completate è inferiore a requiredCount.

suggerimento

Utilizza entrambe le funzioni contemporaneamente quando necessario:

• regular-actions limita la frequenza con cui chi lo indossa può inviare un messaggio.
• Il codice requirements/progress indica se si è registrato un numero sufficiente di completamenti verificati nel corso della giornata o della settimana.
• Il codice metadata.unlockBlockers blocca lo sblocco fino al soddisfacimento del requisito corrente.

Premi

Le ricompense sono azioni di blocco privilegiate. Richiamale dal tuo backend dopo aver verificato il successo dell'operazione.

Tempo di rimozione:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "remove_time",
    "params": 600
  }'

Iniziate con un'apertura igienica:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hygienic_unlock.start",
    "params": {
      "durationSeconds": 900
    }
  }'

Invia una notifica personalizzata:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/notifications/custom" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Challenge complete",
    "message": "Your extension reward was applied.",
    "target": "wearer"
  }'

Punizioni

Anche le sanzioni sono azioni di blocco privilegiate. Applicale solo dopo che il tuo backend ha verificato un errore o un requisito non soddisfatto.

Aggiungi il tempo:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "add_time",
    "params": 1800
  }'

Congelare:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "freeze",
    "params": {
      "durationSeconds": 3600
    }
  }'

Assegna un compito:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "task.assign",
    "params": {
      "actor": "extension",
      "taskText": "Write a short reflection about the missed requirement.",
      "points": 5,
      "durationMinutes": 30
    }
  }'

Inizia la gogna:

curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
  -H "Authorization: Bearer $DEVELOPER_KEY" \
  -H "x-chastify-main-token: $MAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pillory",
    "params": {
      "durationSeconds": 3600,
      "reason": "Extension requirement missed"
    }
  }'

Modello consigliato

Per giochi, routine e sfide di verifica:

1. L'iframe si apre e legge l'hash di avvio.
2. L'iframe chiede al tuo backend di creare una sfida utilizzando mainToken.
3. Il backend scambia/utilizza mainToken con la sua chiave API per sviluppatori con ambito app.
4. L'iframe invia le risposte al tuo backend.
5. Il backend verifica il risultato.
6. Il backend registra i progressi affidabili con requirements/progress.
7. Il backend applica premi o punizioni con /action.
8. Patch di backend metadata.unlockBlockers e metadata.homeActions.
9. L'iframe legge lo stato sicuro/i metadati e mostra il risultato.

In questo modo l'interfaccia utente dell'estensione rimane reattiva, mantenendo al contempo uno stato di blocco affidabile sul server.