Funktionen der Erweiterungs-API

Nutzen Sie diese Seite, wenn Sie das grundlegende Erweiterungsmodell bereits verstehen und ein tatsächliches Sperrverhalten erstellen möchten: erforderliche Aktionen, Entsperrungsblocker, Regelmäßigkeit, Belohnungen und Bestrafungen.

vorsicht

Der Browser-iFrame-Code ist nicht vertrauenswürdig.

Ihr iFrame kann die Benutzeroberfläche darstellen und den sicheren Sitzungskontext lesen. Alles, was den Sitzungsstatus ändert, den Nutzer belohnt, Zeit entfernt, eine Entsperrsperre aufhebt, den Fortschritt vertrauenswürdiger Anforderungen speichert, einen Versuchstimer startet oder fehlschlagen lässt oder eine Strafe verhängt, muss von Ihrem Backend verifiziert werden.

Feature-Karte

Funktion	Was es kann	Wo es eingesetzt wird
Blockierungen aufheben	Entsperren verhindern, bis Ihre Nebenstelle eine Blockierung aufhebt oder genügend vertrauenswürdigen Fortschritt aufgezeichnet hat	Konfiguration oder Backend-Metadaten-/Fortschrittsaufrufe sperren
Aktionen auf der Startseite	Fügt eine sichtbare Aktion auf der Sperrseite hinzu, z. B. „Herausforderung spielen“	Konfigurations- oder Backend-Metadaten-Patches für den Sperrstart
Regelmäßige Aktionen	Ermöglicht eine begrenzte Anzahl von Aktionen des Trägers pro Intervall	Chastify verfolgt Zähler; Ihr Backend übermittelt vertrauenswürdige Aktionen
Erforderlicher Fortschritt	Verfolgt tägliche oder wöchentliche Fertigstellungsanforderungen	Ihr Backend protokolliert den Fortschritt; der Chastify-Scheduler prüft verpasste Zeitfenster
Belohnungen	Entfernt Wartezeiten, startet eine Hygieneöffnung oder sendet eine Benachrichtigung nach erfolgreicher Bestätigung	Ihr Backend ruft privilegierte Endpunkte auf
Strafen	Fügt Zeit hinzu, friert ein, weist eine Aufgabe zu, startet den Pranger oder sendet eine Benachrichtigung nach bestätigtem Fehler	Ihr Backend ruft privilegierte Endpunkte auf

Erforderliche Backend-Header

Privilegierte Erweiterungsendpunkte benötigen beide Header:

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

Der Code mainToken identifiziert die geöffnete Erweiterungssitzung. Der Entwickler-API-Schlüssel beweist, dass die Anfrage von Ihrem Backend stammt.

Entsperrungsblocker

Verwenden Sie Entsperrsperren, wenn der Träger eine Aufgabe abschließen muss, bevor er die Sperre aufheben kann. Beispiele:

Gewinne 3 Spiele.
Schließe den heutigen Trainingsnachweis ab.
Lösen Sie ein Überprüfungsrätsel.
Führen Sie alle erforderlichen Erweiterungsaktionen für das aktuelle Fenster durch.

Es gibt zwei unterstützte Muster.

Fortschrittsbasierte Blocker

Verwenden Sie initialMetadata.unlockRequirements, wenn die Sperre sofort nach dem Start oder der Annahme einer gemeinsamen Vorlage blockiert werden soll. Chastify initialisiert den Sitzungsstatus der Erweiterung anhand dieser generischen Konfiguration, sodass die Blockierung bereits vor dem ersten Öffnen Ihrer Erweiterung durch den Nutzer erfolgt.

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

Nachdem Ihr Backend eine vertrauenswürdige Fertigstellung bestätigt hat, erfassen Sie den Fortschritt für dieselbe 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 speichert dies als Freischaltfortschritt und behandelt die Anforderung automatisch als erfüllt, sobald der Fortschritt requiredCount erreicht. Sperrkarten können einen Fortschritt wie z. B. 1 of 3 complete anzeigen.

Verwenden Sie stabile Metriknamen. Eine Metrik repräsentiert eine aktive Entsperrungsanforderung für diese Erweiterungssitzung.

Zeitlimits für Versuche

Verwenden Sie attemptLimit, wenn ein vertrauenswürdiger Versuch ablaufen muss, falls er nicht rechtzeitig abgeschlossen wird. Chastify speichert den aktiven Versuch unter data.attemptLimits.<metric> und kann ihn nach Ablauf der Frist als fehlgeschlagen markieren. Dieser Status wird von Chastify verwaltet; starten und beenden Sie Versuche über die Versuchsendpunkte, anstatt data.attemptLimits selbst zu implementieren.

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

startPolicy kann zu activity werden, wenn der Countdown beginnt, sobald der Träger mit dem Spielen beginnt, oder zu availability, wenn der Countdown beginnt, sobald die Aktion für das Schloss verfügbar ist.

Starten Sie einen Versuch von Ihrem Backend aus:

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

Wenn Ihr Backend den Versuch prüft, weisen Sie Chastify an, den Versuch fehlschlagen zu lassen, falls die Frist abgelaufen ist:

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

Falls fehlgeschlagene Versuche einen Cooldown-Slot verbrauchen sollten, wird zusätzlich eine reguläre Aktion für den fehlgeschlagenen Versuch ausgelöst.

Manuelle Blocker

Verwenden Sie unlockBlockers, wenn Ihr Backend manuell entscheiden muss, ob die Entsperrung blockiert ist. Patchen Sie die Metadaten von Ihrem 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."
        }
      }
    ]
  }'

Beseitigen Sie die Blockierung, nachdem Ihr Backend die Fertigstellung bestätigt hat:

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

hinweis

unlockBlockers sind manuelle Metadaten. Sie teilen Chastify mit, dass die Entsperrung blockiert ist, bis Ihr Backend die Blockierung aufhebt. initialMetadata.unlockRequirements sind fortschrittsbasierte Metadaten. Chastify kann diese automatisch anhand des für die entsprechende Metrik aufgezeichneten, vertrauenswürdigen Fortschritts auswerten.

Regelmäßigkeitsmerkmal

Regelmäßige Aktionen sind dann sinnvoll, wenn dem Träger erlaubt ist, etwas in einem festgelegten Rhythmus zu tun: einmal pro Stunde, viermal pro Tag, eine Einreichung pro Woche usw.

Sie können regelmäßige Aktionen konfigurieren, die beim Erstellen der Sperrerweiterung ausgeführt werden, oder die laufende Sitzung von Ihrem Backend aus aktualisieren:

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: Aktionen sind immer verfügbar.
non_cumulative: Es steht jeweils nur ein Fenster zur Verfügung; ungenutzte Aktionen werden nicht gestapelt.
cumulative: Aktionen werden bis maxActions akkumuliert.

Aktuelle Verfügbarkeit prüfen:

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

Reichen Sie eine vertrauenswürdige regelmäßige Aktion ein:

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

Verwenden Sie reguläre Aktionen, wenn die Hauptregel lautet: „Wie oft kann diese Aktion ausgeführt werden?“.

Benutzerdefinierte erforderliche Aktionen

Verwenden Sie die erforderliche Fortschrittsvorgabe, wenn die Hauptregel lautet: „Wie viele Abschlüsse sind pro Tag oder Woche erforderlich?“.

Die Anforderungskonfiguration befindet sich in der installierten Erweiterungssitzungskonfiguration unter 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"
    }
  }
}

Unterstützte Kadenzeinheiten:

day
week

Unterstützte Strafarten bei versäumter Frist:

none
add_time
freeze
pillory

Vertrauliche Fortschritte werden erst dann protokolliert, nachdem das Backend die Aktion verifiziert hat:

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

Der Scheduler von Chastify wertet abgeschlossene Fenster aus und wendet die konfigurierte Strafe für verpasste Fenster an, wenn die Anzahl der abgeschlossenen Fenster unter requiredCount liegt.

tipp

Nutzen Sie beide Funktionen bei Bedarf gemeinsam:

regular-actions begrenzt die Häufigkeit, mit der ein Träger etwas einreichen kann.
requirements/progress protokolliert, ob für den Tag oder die Woche genügend bestätigte Abschlüsse stattgefunden haben.
metadata.unlockBlockers blockiert die Entsperrung, bis die aktuelle Anforderung erfüllt ist.

Prämien

Belohnungen sind privilegierte Sperraktionen. Rufen Sie sie nach erfolgreicher Bestätigung über Ihr Backend auf.

Zeit entfernen:

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

Beginnen Sie mit einer hygienischen Öffnung:

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

Sende eine benutzerdefinierte Benachrichtigung:

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

Strafen

Strafen sind ebenfalls privilegierte Sperraktionen. Wenden Sie sie erst an, nachdem Ihr Backend einen Fehler oder eine nicht erfüllte Anforderung bestätigt hat.

Zeit hinzufügen:

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

Einfrieren:

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

Eine Aufgabe zuweisen:

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

Pranger beginnen:

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

Empfohlenes Muster

Für Spiele, Routinen und Verifizierungsherausforderungen:

Ein Iframe öffnet sich und liest den Start-Hash.
Der Iframe fordert Ihr Backend auf, eine Challenge mit dem Code mainToken zu erstellen.
Das Backend tauscht/verwendet mainToken mit seinem anwendungsbezogenen Entwickler-API-Schlüssel.
Iframe übermittelt Antworten an Ihr Backend.
Das Backend überprüft das Ergebnis.
Im Backend werden vertrauenswürdige Fortschrittsmeldungen mit requirements/progress aufgezeichnet.
Im Backend wird eine Belohnung oder Bestrafung mit /action angewendet.
Backend-Patches metadata.unlockBlockers und metadata.homeActions.
Ein Iframe liest den sicheren Status/die Metadaten und zeigt das Ergebnis an.

Dadurch bleibt die Benutzeroberfläche der Erweiterung reaktionsfähig, während der vertrauenswürdige Sperrstatus auf dem Server erhalten bleibt.

Feature-Karte​

Erforderliche Backend-Header​

Entsperrungsblocker​

Fortschrittsbasierte Blocker​

Zeitlimits für Versuche​

Manuelle Blocker​

Regelmäßigkeitsmerkmal​

Benutzerdefinierte erforderliche Aktionen​

Prämien​

Strafen​

Empfohlenes Muster​