Funktioner i Extension API

Använd den här sidan när du redan förstår den grundläggande tilläggsmodellen och vill bygga upp faktiskt låsbeteende: obligatoriska åtgärder, upplåsningsblockerare, regelbundenhet, belöningar och straff.

varning

Webbläsarens iframe-kod är inte betrodd.

Din iframe kan rendera användargränssnittet och läsa säker sessionskontext. Allt som skriver sessionsstatus, belönar bäraren, tar bort tid, rensar en upplåsningsblockerare, registrerar framsteg för betrodda krav, startar eller misslyckas med en försökstimer eller tillämpar straff måste verifieras av din backend.

Funktionskarta

Funktion	Vad den gör	Var den körs
Lås upp blockerare	Förhindra upplåsning tills din anknytning tar bort en blockerare eller registrerar tillräckligt med betrodda framsteg	Låsstartkonfiguration eller backend-metadata/framstegsanrop
Startsida åtgärder	Lägger till en synlig åtgärd på låssidan, till exempel "Spela utmaning"	Låsstartkonfiguration eller metadatapatchar för backend
Regelbundna åtgärder	Tillåter ett begränsat antal bäraråtgärder per intervall	Chastify spårar räknare; din backend skickar betrodda åtgärder
Nödvändiga framsteg	Spårar dagliga eller veckovisa slutförandekrav	Din backend registrerar framsteg; Chastify-schemaläggaren kontrollerar missade fönster
Belöningar	Tar bort tid, startar hygienöppning eller skickar meddelande efter verifierad framgång	Din backend anropar privilegierade slutpunkter
Straff	Lägger till tid, fryser, tilldelar en uppgift, startar skampåle eller skickar meddelande efter verifierat fel	Din backend anropar privilegierade slutpunkter

Obligatoriska backend-rubriker

Privilegierade tilläggsslutpunkter kräver båda rubrikerna:

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

mainToken identifierar den öppnade tilläggssessionen. Developer API-nyckeln bevisar att begäran kom från din backend.

Lås upp blockerare

Använd upplåsningsblockerare när bäraren måste avsluta något innan upplåsningen kan ske. Exempel:

Vinn 3 matcher.
Komplettera dagens träningsbevis.
Slutför ett verifieringspussel.
Slutför alla obligatoriska tilläggsåtgärder för det aktuella fönstret.

Det finns två mönster som stöds.

Framstegsbaserade blockerare

Använd initialMetadata.unlockRequirements när låset ska blockeras så snart låsningen startar eller en delad mall accepteras. Chastify initierar anknytningens sessionstillstånd från denna generiska konfiguration, så att blockeraren finns redan innan bäraren öppnar din anknytning för första gången.

{
  "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 verifierar en betrodd slutförande, registrera förloppet för samma mätvärde:

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 lagrar detta som upplåsningsförlopp och behandlar automatiskt kravet som uppfyllt när förloppet når requiredCount. Låskort kan visa förlopp som 1 of 3 complete.

Använd stabila mätvärdesnamn. Ett mätvärde representerar ett aktivt upplåsningskrav för den tilläggssessionen.

Tidsgränser för försök

Använd attemptLimit när ett betrott försök måste löpa ut om det inte slutförs i tid. Chastify lagrar det aktiva försöket under data.attemptLimits.<metric> och kan markera det som misslyckat efter deadline. Detta tillstånd hanteras av Chastify; starta och misslycka försök via försökets slutpunkter istället för att skriva data.attemptLimits själv.

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

startPolicy kan vara activity när nedräkningen startar när bäraren börjar spela, eller availability när nedräkningen startar så snart åtgärden är tillgänglig för låset.

Starta ett försök från 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 kontrollerar försöket, be Chastify att misslyckas om deadline har passerat:

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

Om misslyckade försök skulle förbruka en nedkylningsplats, skicka även in en vanlig åtgärd för det misslyckade försöket.

Manuella blockerare

Använd unlockBlockers när din backend behöver avgöra manuellt om upplåsning är blockerad. Uppdatera metadata från 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."
        }
      }
    ]
  }'

Rensa blockeraren efter att din backend verifierat att den är klar:

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

anteckning

unlockBlockers är manuella metadata. Den talar om för Chastify att upplåsning är blockerad tills din backend tar bort blockeraren. initialMetadata.unlockRequirements är förloppsbaserade metadata. Chastify kan utvärdera den automatiskt från betrodda förlopp som registrerats för matchande mätvärden.

Regelbundenhetsfunktion

Regelbundna handlingar är användbara när bäraren tillåts göra något i en fast kadens: en gång i timmen, fyra gånger per dag, en inlämning per vecka och så vidare.

Du kan konfigurera regelbundna åtgärder när låstillägget skapas, eller uppdatera den pågående sessionen från 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
  }'

Lägen:

unlimited: åtgärder är alltid tillgängliga.
non_cumulative: ett fönster blir tillgängligt åt gången; oanvända åtgärder staplas inte.
cumulative: åtgärder ackumuleras upp till maxActions.

Läs aktuell tillgänglighet:

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

Skicka in en betrodd regelbunden åtgärd:

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

Använd regelbundna handlingar när huvudregeln är "hur ofta kan denna handling ske?".

Anpassade obligatoriska åtgärder

Använd obligatoriska framsteg när huvudregeln är "hur många slutföranden krävs per dag eller vecka?".

Kravkonfigurationen finns i den installerade tilläggssessionskonfigurationen 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ödda kadensenheter:

day
week

Stödda typer av straff för missade fönster:

none
add_time
freeze
pillory

Registrera endast betrodda framsteg efter att din backend verifierat åtgärden:

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 schemaläggare utvärderar slutförda fönster och tillämpar den konfigurerade straffen för missade fönster om antalet slutförda är under requiredCount.

tips

Använd båda funktionerna tillsammans vid behov:

regular-actions begränsar hur ofta en bärare kan skicka in.
requirements/progress registrerar om tillräckligt många verifierade slutföranden inträffade under dagen eller veckan.
metadata.unlockBlockers blockerar upplåsning tills det aktuella kravet är uppfyllt.

Belöningar

Belöningar är privilegierade låsåtgärder. Anropa dem från din backend efter en verifierad framgång.

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

Starta en hygienisk öppning:

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

Skicka en anpassad avisering:

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

Straff

Straff är också privilegierade låsåtgärder. Tillämpa dem endast efter att din backend verifierar ett fel eller missat krav.

Lägg till 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
  }'

Frysa:

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

Tilldela en uppgift:

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

Starta skampålen:

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

Rekommenderat mönster

För spel, rutiner och verifieringsutmaningar:

Iframe öppnas och läser start-hashen.
Iframe ber din backend att skapa en utmaning med mainToken.
Backend utbyter/använder mainToken med sin app-scope-baserade Developer API-nyckel.
Iframe skickar svar till din backend.
Backend verifierar resultatet.
Backend registrerar betrodda framsteg med requirements/progress.
Backend tillämpar belöning eller straff med /action.
Backend-patcharna metadata.unlockBlockers och metadata.homeActions.
Iframe läser säkert tillstånd/metadata och visar resultatet.

Detta gör att tilläggets användargränssnitt responsivt samtidigt som det betrodda låsläget på servern bibehålls.

Funktionskarta​

Obligatoriska backend-rubriker​

Lås upp blockerare​

Framstegsbaserade blockerare​

Tidsgränser för försök​

Manuella blockerare​

Regelbundenhetsfunktion​

Anpassade obligatoriska åtgärder​

Belöningar​

Straff​

Rekommenderat mönster​