Funktioner i udvidelses-API'en

Brug denne side, når du allerede forstår den grundlæggende udvidelsesmodel og ønsker at opbygge faktisk låseadfærd: nødvendige handlinger, oplåsningsblokerere, regelmæssighed, belønninger og straffe.

caution

Browserens iframe-kode er ikke tillid.

Din iframe kan gengive brugergrænsefladen og læse sikker sessionskontekst. Alt, der skriver sessionsstatus, belønner brugeren, fjerner tid, rydder en oplåsningsblokering, registrerer fremskridt for betroede krav, starter eller fejler en forsøgstimer eller anvender straf, skal verificeres af din backend.

Funktionskort

Funktion	Hvad den gør	Hvor den kører
Lås op for blokeringer	Forhindr oplåsning, indtil din udvidelse fjerner en blokering eller registrerer tilstrækkelig pålidelig fremgang	Lås-start konfiguration eller backend-metadata/fremgangskald
Hjemmesidehandlinger	Tilføjer en synlig handling på låsesiden, f.eks. "Afspil udfordring"	Lås-start konfiguration eller backend metadata-rettelser
Regelmæssige handlinger	Tillader et begrænset antal brugerhandlinger pr. interval	Chastify sporer tællere; din backend sender betroede handlinger
Nødvendig status	Sporer daglige eller ugentlige færdiggørelseskrav	Din backend registrerer status; Chastify-planlæggeren kontrollerer mistede vinduer
Belønninger	Fjerner tid, starter hygiejneåbning eller sender besked efter bekræftet succes	Din backend kalder privilegerede slutpunkter
Straffe	Tilføjer tid, fryser, tildeler en opgave, starter gabestok eller sender besked efter verificeret fejl	Din backend kalder privilegerede slutpunkter

Påkrævede backend-headere

Privilegerede udvidelsesslutpunkter kræver begge headere:

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

mainToken identificerer den åbnede udvidelsessession. Developer API-nøglen beviser, at anmodningen kom fra din backend.

Lås op for blokkere

Brug oplåsningsblokkere, når brugeren skal afslutte noget, før den kan låses op. Eksempler:

Vind 3 kampe.
Færdiggør dagens træningsbevis.
Færdiggør én verifikationsgåde.
Udfør alle nødvendige udvidelseshandlinger for det aktuelle vindue.

Der er to understøttede mønstre.

Fremskridtsbaserede blokkere

Brug initialMetadata.unlockRequirements, når låsen skal blokeres, så snart låsen starter, eller en delt skabelon accepteres. Chastify initialiserer lokalnummerets sessionstilstand fra denne generiske konfiguration, så blokeringen findes, selv før brugeren åbner din lokalnummer for første gang.

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

Når din backend verificerer en betroet fuldførelse, skal du registrere status for den samme metrik:

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 gemmer dette som oplåsningsstatus og behandler automatisk kravet som opfyldt, når status når requiredCount. Låsekort kan vise status, f.eks. 1 of 3 complete.

Brug stabile metriknavne. Én metrik repræsenterer ét aktivt oplåsningskrav for den pågældende udvidelsessession.

Tidsgrænser for forsøg

Brug attemptLimit, når et betroet forsøg skal udløbe, hvis det ikke gennemføres i tide. Chastify gemmer det aktive forsøg under data.attemptLimits.<metric> og kan markere det som mislykket efter deadline. Denne tilstand administreres af Chastify; start og mislykke forsøg via forsøgets slutpunkter i stedet for selv at skrive data.attemptLimits.

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

startPolicy kan være activity, når nedtællingen starter, når bæreren begynder at spille, eller availability, når nedtællingen starter, så snart handlingen er tilgængelig for låsen.

Start et forsøg fra din 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"
  }'

Når din backend tjekker forsøget, skal du bede Chastify om at fejle, hvis deadline er overskredet:

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"
  }'

Hvis mislykkede forsøg skulle optage et nedkølingstidsrum, skal du også indsende en almindelig handling for det mislykkede forsøg.

Manuelle blokkere

Brug unlockBlockers, når din backend skal afgøre manuelt, om oplåsning er blokeret. Opdater metadata fra din 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."
        }
      }
    ]
  }'

Ryd blokeringen, når din backend bekræfter færdiggørelsen:

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 er manuelle metadata. Den fortæller Chastify, at oplåsning er blokeret, indtil din backend fjerner blokeringen. initialMetadata.unlockRequirements er statusbaserede metadata. Chastify kan evaluere den automatisk ud fra betroede statusregistreringer for den matchende metrik.

Regelmæssighedsfunktion

Regelmæssige handlinger er nyttige, når bæreren får lov til at gøre noget med en fast kadence: én gang i timen, fire gange om dagen, én indsendelse om ugen og så videre.

Du kan konfigurere regelmæssige handlinger, når låseudvidelsen oprettes, eller opdatere den kørende session fra din 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
  }'

Tilstande:

unlimited: handlinger er altid tilgængelige.
non_cumulative: ét vindue bliver tilgængeligt ad gangen; ubrugte handlinger stables ikke.
cumulative: Handlinger akkumuleres op til maxActions.

Læs aktuel tilgængelighed:

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

Indsend en betroet regelmæssig handling:

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
    }
  }'

Brug regelmæssige handlinger, når hovedreglen er "hvor ofte kan denne handling ske?".

Brugerdefinerede obligatoriske handlinger

Brug krævet fremskridt, når hovedreglen er "hvor mange fuldførelser kræves pr. dag eller uge?".

Kravkonfigurationen findes i den installerede udvidelsessessionskonfiguration under 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"
    }
  }
}

Understøttede kadensenheder:

day
week

Understøttede typer af straf for mistede vinduer:

none
add_time
freeze
pillory

Registrer kun betroede fremskridt, når din backend har verificeret handlingen:

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"
  }'

Chastifys planlægger evaluerer fuldførte vinduer og anvender den konfigurerede straf for mistede vinduer, hvis antallet af fuldførte vinduer er under requiredCount.

tip

Brug begge funktioner sammen, når det er nødvendigt:

regular-actions begrænser, hvor ofte en bruger kan indsende.
requirements/progress registrerer, om der er sket nok verificerede fuldførelser for dagen eller ugen.
metadata.unlockBlockers blokerer oplåsning, indtil det aktuelle krav er opfyldt.

Belønninger

Belønninger er privilegerede låsehandlinger. Kald dem fra din backend efter en bekræftet succes.

Fjern tid:

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
  }'

Start en hygiejnisk åbning:

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
    }
  }'

Send en brugerdefineret notifikation:

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"
  }'

Straffe

Straffe er også privilegerede låsehandlinger. Anvend dem kun, når din backend verificerer en fejl eller et manglende krav.

Tilføj tid:

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
  }'

Fryse:

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
    }
  }'

Tildel en opgave:

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
    }
  }'

Start gabestok:

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"
    }
  }'

Anbefalet mønster

Til spil, rutiner og verifikationsudfordringer:

Iframe åbner og læser launch-hashen.
Iframe beder din backend om at oprette en udfordring ved hjælp af mainToken.
Backend udveksler/bruger mainToken med sin app-scopede Developer API-nøgle.
Iframe sender svar til din backend.
Backend verificerer resultatet.
Backend registrerer pålidelig fremgang med requirements/progress.
Backend anvender belønning eller straf med /action.
Backend-patches metadata.unlockBlockers og metadata.homeActions.
Iframe læser sikker tilstand/metadata og viser resultatet.

Dette holder udvidelsens brugergrænseflade responsiv, samtidig med at den betroede låsetilstand på serveren bevares.

Funktionskort​

Påkrævede backend-headere​

Lås op for blokkere​

Fremskridtsbaserede blokkere​

Tidsgrænser for forsøg​

Manuelle blokkere​

Regelmæssighedsfunktion​

Brugerdefinerede obligatoriske handlinger​

Belønninger​

Straffe​

Anbefalet mønster​