Funksjoner i utvidelses-API-et

Bruk denne siden når du allerede forstår den grunnleggende utvidelsesmodellen og ønsker å bygge faktisk låseatferd: nødvendige handlinger, opplåsingsblokkeringer, regelmessighet, belønninger og straffer.

caution

Nettleserens iframe-kode er ikke klarert.

Iframe-en din kan gjengi brukergrensesnitt og lese kontekst for sikker økt. Alt som skriver øktstatus, belønner brukeren, fjerner tid, fjerner en opplåsingsblokkering, registrerer fremdrift for klarerte krav, starter eller mislykkes med en forsøkstimer, eller bruker straff, må verifiseres av backend-en din.

Funksjonskart

Funksjon	Hva den gjør	Hvor den kjører
Lås opp blokkeringer	Forhindre opplåsing inntil utvidelsen din fjerner en blokkering eller registrerer nok pålitelig fremdrift	Lås-start-konfigurasjon eller backend-metadata/fremdriftskall
Hjemmesidehandlinger	Legger til en synlig handling på låsesiden, for eksempel «Spill av utfordring»	Lås-start-konfigurasjon eller metadataoppdateringer for backend
Regelmessige handlinger	Tillater et begrenset antall brukerhandlinger per intervall	Chastify sporer tellere; backend-enheten din sender inn pålitelige handlinger
Nødvendig fremdrift	Sporer daglige eller ukentlige fullføringskrav	Backend-en din registrerer fremdrift; Chastify-planleggeren sjekker tapte vinduer
Belønninger	Fjerner tid, starter hygieneåpning eller sender varsel etter bekreftet suksess	Backend-en din kaller privilegerte endepunkter
Straffer	Legger til tid, fryser, tildeler en oppgave, starter gapestokk eller sender varsel etter bekreftet feil	Backend-en din kaller privilegerte endepunkter

Nødvendige backend-overskrifter

Privilegerte utvidelsesendepunkter krever begge overskriftene:

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

mainToken identifiserer den åpnede utvidelsesøkten. Developer API-nøkkelen beviser at forespørselen kom fra backend-en din.

Lås opp blokkeringer

Bruk opplåsingsblokkeringer når brukeren må fullføre noe før opplåsing. Eksempler:

Vinn 3 kamper.
Fullfør dagens treningsbevis.
Fullfør én verifiseringsoppgave.
Fullfør alle nødvendige utvidelseshandlinger for det gjeldende vinduet.

Det er to støttede mønstre.

Fremdriftsbaserte blokkere

Bruk initialMetadata.unlockRequirements når låsen skal blokkeres så snart låsingen starter eller en delt mal aksepteres. Chastify initialiserer øktstatusen til utvidelsen fra denne generiske konfigurasjonen, slik at blokkeringen eksisterer selv før brukeren åpner utvidelsen din 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"
      }
    ]
  }
}

Etter at backend-en din bekrefter en pålitelig fullføring, registrer fremdriften for samme måleenhet:

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 lagrer dette som opplåsingsfremdrift og behandler automatisk kravet som oppfylt når fremdriften når requiredCount. Låsekort kan vise fremdrift, for eksempel 1 of 3 complete.

Bruk stabile målenavn. Én måleenhet representerer ett aktivt opplåsingskrav for den utvidelsesøkten.

Tidsgrenser for forsøk

Bruk attemptLimit når et klarert forsøk må utløpe hvis det ikke fullføres i tide. Chastify lagrer det aktive forsøket under data.attemptLimits.<metric> og kan markere det som mislykket etter fristen. Denne tilstanden er Chastify-administrert; start og mislykkede forsøk gjennom forsøkets endepunkter i stedet for å skrive data.attemptLimits selv.

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

startPolicy kan være activity når nedtellingen starter idet brukeren begynner å spille, eller availability når nedtellingen starter så snart handlingen er tilgjengelig for låsen.

Start et forsøk fra backend-en din:

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 backend-en din sjekker forsøket, ber du Chastify om å feile hvis fristen er utløpt:

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øk skulle forbruke et nedkjølingstidspunkt, må du også sende inn en vanlig handling for det mislykkede forsøket.

Manuelle blokkere

Bruk unlockBlockers når backend-systemet ditt må avgjøre manuelt om opplåsing er blokkert. Oppdater metadata fra backend-systemet ditt:

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

Fjern blokkeringen etter at backend-en din bekrefter fullføringen:

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 forteller Chastify at opplåsing er blokkert inntil backend-systemet ditt fjerner blokkeringen. initialMetadata.unlockRequirements er fremdriftsbaserte metadata. Chastify kan evaluere den automatisk fra pålitelig fremdrift registrert for den samsvarende metrikken.

Regelmessighetsfunksjon

Regelmessige handlinger er nyttige når brukeren får lov til å gjøre noe med en fast kadens: én gang i timen, fire ganger per dag, én innsending per uke og så videre.

Du kan konfigurere vanlige handlinger når låseutvidelsen opprettes, eller oppdatere den kjørende økten fra backend-systemet ditt:

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

Moduser:

unlimited: handlinger er alltid tilgjengelige.
non_cumulative: ett vindu blir tilgjengelig om gangen; ubrukte handlinger stables ikke.
cumulative: handlinger akkumuleres opptil maxActions.

Les gjeldende tilgjengelighet:

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

Send inn en klarert regelmessig 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
    }
  }'

Bruk regelmessige handlinger når hovedregelen er «hvor ofte kan denne handlingen skje?».

Tilpassede obligatoriske handlinger

Bruk obligatorisk fremgang når hovedregelen er «hvor mange fullføringer kreves per dag eller uke?».

Kravkonfigurasjonen ligger i den installerte utvidelsesøktskonfigurasjonen 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"
    }
  }
}

Støttede kadensenheter:

day
week

Støttede typer straff for tapte vinduer:

none
add_time
freeze
pillory

Registrer kun pålitelig fremdrift etter at backend-en din har bekreftet 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 planlegger evaluerer fullførte vinduer og bruker den konfigurerte straffen for tapte vinduer hvis antallet fullførte vinduer er under requiredCount.

tip

Bruk begge funksjonene sammen når det er nødvendig:

regular-actions begrenser hvor ofte en bruker kan sende inn.
requirements/progress registrerer om det har skjedd nok bekreftede fullføringer for dagen eller uken.
metadata.unlockBlockers blokkerer opplåsing inntil gjeldende krav er oppfylt.

Belønninger

Belønninger er privilegerte låsehandlinger. Kall dem fra backend-en din etter en bekreftet suksess.

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 hygienisk åpning:

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 et tilpasset varsel:

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

Straffer

Straffer er også privilegerte låsehandlinger. Bruk dem bare etter at backend-en din bekrefter en feil eller et manglende krav.

Legg til 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 oppgave:

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 gapestokken:

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

Anbefalt mønster

For spill, rutiner og verifiseringsutfordringer:

Iframe åpnes og leser oppstartshashen.
Iframe ber backend-en din om å opprette en utfordring ved hjelp av mainToken.
Backend utveksler/bruker mainToken med sin app-scoped Developer API-nøkkel.
Iframe sender svar til backend-en din.
Backend verifiserer resultatet.
Backend registrerer pålitelig fremdrift med requirements/progress.
Backend bruker belønning eller straff med /action.
Backend-oppdateringene metadata.unlockBlockers og metadata.homeActions.
Iframe leser sikker tilstand/metadata og viser resultatet.

Dette holder utvidelsens brukergrensesnitt responsivt samtidig som den klarerte låsetilstanden på serveren opprettholdes.

Funksjonskart​

Nødvendige backend-overskrifter​

Lås opp blokkeringer​

Fremdriftsbaserte blokkere​

Tidsgrenser for forsøk​

Manuelle blokkere​

Regelmessighetsfunksjon​

Tilpassede obligatoriske handlinger​

Belønninger​

Straffer​

Anbefalt mønster​