Functies van de extensie-API

Gebruik deze pagina wanneer u het basismodel van de extensie al begrijpt en het daadwerkelijke vergrendelingsgedrag wilt bouwen: vereiste acties, ontgrendelingsblokkeringen, regelmaat, beloningen en straffen.

pas op

De code van de browser-iframe wordt niet vertrouwd.

Je iframe kan gebruikersinterfaces weergeven en veilige sessiecontext lezen. Alles wat de sessiestatus schrijft, de drager beloont, tijd verwijdert, een ontgrendelingsblokkering opheft, de voortgang van vertrouwde vereisten registreert, een pogingstimer start of laat mislukken, of een straf toepast, moet door je backend worden geverifieerd.

Functiekaart

Functie	Wat het doet	Waar het draait
Blokkeringen opheffen	Voorkom ontgrendeling totdat uw extensie een blokkering heeft opgeheven of voldoende betrouwbare voortgang heeft geregistreerd	Vergrendel de startconfiguratie of backend-metadata-/voortgangsoproepen
Startpagina-acties	Voegt een zichtbare actie toe aan de vergrendelingspagina, zoals 'Uitdaging spelen'	Patches voor vergrendelingsstartconfiguratie of backend-metadata
Regelmatige acties	Staat een beperkt aantal acties per interval toe	Chastify houdt tellers bij; uw backend verzendt vertrouwde acties
Vereiste voortgang	Houdt dagelijkse of wekelijkse voltooiingsvereisten bij	Uw backend registreert de voortgang; de Chastify-planner controleert gemiste vensters
Beloningen	Verwijdert tijd, start hygiëne-opening of verzendt een melding na succesvolle verificatie	Uw backend roept beveiligde eindpunten aan
Straffen	Voegt tijd toe, bevriest, wijst een taak toe, start de schandpaal of stuurt een melding na geverifieerde mislukking	Uw backend roept geprivilegieerde eindpunten aan

Vereiste backend-headers

Voor geprivilegieerde extensie-eindpunten zijn beide headers vereist:

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

De mainToken identificeert de geopende extensiesessie. De API-sleutel voor ontwikkelaars bewijst dat het verzoek afkomstig is van uw backend.

Blokkeerders ontgrendelen

Gebruik ontgrendelingsblokkeringen wanneer de drager iets moet voltooien voordat hij/zij kan ontgrendelen. Voorbeelden:

• Win 3 wedstrijden.
• Voltooi vandaag nog je trainingsbewijs.
• Voltooi één verificatiepuzzel.
• Voltooi alle vereiste uitbreidingsacties voor het huidige venster.

Er zijn twee ondersteunde patronen.

Op voortgang gebaseerde blokkeringen

Gebruik initialMetadata.unlockRequirements wanneer het slot moet worden geblokkeerd zodra het slot wordt geopend of een gedeelde sjabloon wordt geaccepteerd. Chastify initialiseert de extensiesessiestatus vanuit deze generieke configuratie, zodat de blokkering al bestaat voordat de gebruiker uw extensie voor de eerste keer opent.

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

Nadat uw backend een betrouwbare voltooiing heeft geverifieerd, registreert u de voortgang voor dezelfde metriek:

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 slaat dit op als ontgrendelingsvoortgang en beschouwt de vereiste automatisch als voldaan wanneer de voortgang requiredCount bereikt. Vergrendelingskaarten kunnen voortgang weergeven zoals 1 of 3 complete.

Gebruik stabiele metrische namen. Eén metriek vertegenwoordigt één actieve ontgrendelingsvereiste voor die extensiesessie.

Tijdslimieten voor pogingen

Gebruik attemptLimit wanneer een vertrouwde poging moet verlopen als deze niet op tijd is voltooid. Chastify slaat de actieve poging op onder data.attemptLimits.<metric> en kan deze na de deadline als mislukt markeren. Deze status wordt beheerd door Chastify; start en beëindig pogingen via de pogings-eindpunten in plaats van zelf data.attemptLimits te schrijven.

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

startPolicy kan activity worden als het aftellen begint wanneer de drager begint te spelen, of availability als het aftellen begint zodra de actie beschikbaar is voor het slot.

Start een poging vanuit je 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"
  }'

Wanneer uw backend de poging controleert, vraag dan Chastify om deze te laten mislukken als de deadline is verstreken:

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

Als mislukte pogingen een afkoelingsslot in beslag nemen, dien dan ook een reguliere actie in voor de mislukte poging.

Handmatige blokkeringen

Gebruik unlockBlockers wanneer uw backend handmatig moet bepalen of ontgrendelen is geblokkeerd. Patch de metadata van uw 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."
        }
      }
    ]
  }'

Verwijder de blokkering nadat uw backend de voltooiing heeft geverifieerd:

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

notitie

unlockBlockers is handmatige metadata. Deze geeft aan Chastify aan dat het ontgrendelen is geblokkeerd totdat uw backend de blokkering opheft. initialMetadata.unlockRequirements is voortgangsgebaseerde metadata. Chastify kan deze automatisch evalueren op basis van de betrouwbare voortgang die is vastgelegd voor de betreffende metriek.

Regelmatigheidskenmerk

Regelmatige handelingen zijn nuttig wanneer de drager iets met een vaste frequentie mag doen: één keer per uur, vier keer per dag, één keer per week, enzovoort.

U kunt terugkerende acties configureren wanneer de vergrendelingsuitbreiding wordt aangemaakt, of de actieve sessie vanuit uw backend bijwerken:

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

Modi:

• unlimited: acties zijn altijd beschikbaar.
• non_cumulative: er komt telkens één venster beschikbaar; ongebruikte acties worden niet opgestapeld.
• cumulative: acties worden verzameld tot en met maxActions.

Bekijk de actuele beschikbaarheid:

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

Dien een betrouwbare, regelmatig terugkerende actie in:

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

Gebruik regelmatige acties wanneer de hoofdregel is: "Hoe vaak kan deze actie plaatsvinden?".

Aangepaste vereiste acties

Gebruik 'vereiste voortgang' wanneer de hoofdregel is: "hoeveel taken moeten er per dag of per week worden voltooid?".

De vereistenconfiguratie bevindt zich in de geïnstalleerde extensiesessieconfiguratie onder 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"
    }
  }
}

Ondersteunde cadanseenheden:

• day
• week

Ondersteunde soorten straffen voor gemiste tijdsvensters:

• none
• add_time
• freeze
• pillory

Registreer de voortgang pas nadat uw backend de actie heeft geverifieerd:

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

De scheduler van Chastify evalueert voltooide vensters en past de geconfigureerde straf voor gemiste vensters toe als het aantal voltooide vensters lager is dan requiredCount.

tip

Gebruik beide functies samen wanneer nodig:

• regular-actions beperkt hoe vaak een drager kan inzenden.
• requirements/progress registreert of er voldoende geverifieerde transacties hebben plaatsgevonden op de betreffende dag of week.
• metadata.unlockBlockers-blokken worden ontgrendeld totdat aan de huidige vereiste is voldaan.

Beloningen

Beloningen zijn acties met een bevoorrechte vergrendeling. Roep ze aan vanuit je backend na een geverifieerd succes.

Verwijder tijd:

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

Begin met een hygiënische opening:

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

Een aangepaste melding verzenden:

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

Straffen

Straffen zijn ook acties met een bevoorrechte vergrendeling. Pas ze alleen toe nadat uw backend een fout of een gemiste vereiste heeft geverifieerd.

Voeg tijd toe:

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

Bevriezen:

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

Een taak toewijzen:

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

Begin schandpaal:

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

Aanbevolen patroon

Voor spellen, routines en verificatie-uitdagingen:

1. De iframe wordt geopend en leest de opstarthash.
2. Iframe vraagt ​​je backend om een ​​challenge te creëren met behulp van mainToken.
3. De backend wisselt mainToken uit met de bijbehorende, voor de applicatie geldende, ontwikkelaars-API-sleutel.
4. Iframe verzendt antwoorden naar uw backend.
5. De backend verifieert het resultaat.
6. De backend registreert de voortgang op betrouwbare wijze met requirements/progress.
7. De backend past beloning of straf toe met /action.
8. Backend-patches metadata.unlockBlockers en metadata.homeActions.
9. De iframe leest de veilige status/metadata en toont het resultaat.

Hierdoor blijft de gebruikersinterface van de extensie responsief, terwijl de vertrouwde vergrendelingsstatus op de server behouden blijft.