Funkce rozšíření API

Tuto stránku použijte, pokud již rozumíte základnímu modelu rozšíření a chcete vytvořit skutečné chování při uzamčení: požadované akce, blokování odemčení, pravidelnost, odměny a tresty.

caution

Kód iframe prohlížeče není důvěryhodný.

Váš iframe dokáže vykreslit uživatelské rozhraní a číst kontext bezpečné relace. Cokoli, co zapisuje stav relace, odměňuje uživatele, odebírá čas, maže blokování odemčení, zaznamenává postup důvěryhodných požadavků, spouští nebo selhává časovač pokusů nebo aplikuje trest, musí být ověřeno vaším backendem.

Mapa prvků

Funkce	Co dělá	Kde běží
Odemknout blokátory	Zabránit odemknutí, dokud vaše rozšíření neodstraní blokátor nebo nezaznamená dostatek důvěryhodného průběhu	Konfigurace uzamčení spuštění nebo volání metadat/průběhu backendu
Akce na domovské stránce	Přidá na stránku uzamčení viditelnou akci, například „Hrát výzvu“	Konfigurace pro spuštění uzamčení nebo záplaty metadat backendu
Běžné akce	Umožňuje omezený počet akcí uživatele za interval	Chastify sleduje čítače; váš backend odesílá důvěryhodné akce
Požadovaný postup	Sleduje denní nebo týdenní požadavky na dokončení	Váš backend zaznamenává postup; plánovač Chastify kontroluje zmeškaná okna
Odměny	Odebere čas, spustí hygienické otevírání nebo odešle oznámení po ověřeném úspěchu	Váš backend volá privilegované koncové body
Tresty	Přidává čas, zamrzá, přiřazuje úkol, spouští pranýř nebo odesílá oznámení po ověřeném selhání	Váš backend volá privilegované koncové body

Požadované záhlaví backendu

Privilegované koncové body rozšíření vyžadují obě hlavičky:

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

Kód mainToken identifikuje otevřenou relaci rozšíření. Klíč vývojářského API dokazuje, že požadavek přišel z vašeho backendu.

Odemknout blokátory

Blokátory odemčení použijte, když musí nositel před odemčením něco dokončit. Příklady:

Vyhrajte 3 zápasy.
Dokončete dnešní důkaz cvičení.
Dokončete jednu ověřovací hádanku.
Dokončete všechny požadované akce rozšíření pro aktuální okno.

Existují dva podporované vzory.

Blokátory založené na postupu

initialMetadata.unlockRequirements použijte, pokud má být zámek blokován ihned po spuštění zámku nebo přijetí sdílené šablony. Chastify inicializuje stav relace linky z této generické konfigurace, takže blokování existuje ještě předtím, než uživatel poprvé otevře vaši linku.

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

Poté, co váš backend ověří důvěryhodné dokončení, zaznamenejte průběh pro stejnou metriku:

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 ukládá toto jako postup odemčení a automaticky považuje požadavek za splněný, jakmile postup dosáhne requiredCount. Karty zámků mohou zobrazovat postup, například 1 of 3 complete.

Používejte stabilní názvy metrik. Jedna metrika představuje jeden aktivní požadavek na odemčení pro danou rozšiřující relaci.

Časové limity pokusů

Použijte attemptLimit, pokud důvěryhodný pokus musí vypršet, pokud není dokončen včas. Chastify ukládá aktivní pokus pod data.attemptLimits.<metric> a může jej po uplynutí lhůty označit jako neúspěšný. Tento stav je spravován Chastify; pokusy se spouštějí a neúspěšně selhávají prostřednictvím koncových bodů pokusů, místo abyste sami psali data.attemptLimits.

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

startPolicy může být activity, když odpočítávání začíná v okamžiku, kdy nositel začne hrát, nebo availability, když odpočítávání začíná, jakmile je akce pro zámek k dispozici.

Spusťte pokus z backendu:

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

Když váš backend zkontroluje pokus, požádejte Chastify, aby jej selhal, pokud uplynula lhůta:

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

Pokud neúspěšné pokusy spotřebují čas na zchlazení, proveďte pro neúspěšný pokus také běžnou akci.

Manuální blokátory

Pokud váš backend potřebuje ručně rozhodnout, zda je odemykání blokováno, použijte unlockBlockers. Oprava metadat z vašeho backendu:

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

Po ověření dokončení vaším backendem vymažte blokování:

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 jsou manuální metadata. Říkají uživateli Chastify, že odemykání je blokováno, dokud váš backend blokování neodstraní. initialMetadata.unlockRequirements jsou metadata založená na průběhu. Chastify je dokáže automaticky vyhodnotit z důvěryhodného průběhu zaznamenaného pro odpovídající metriku.

Funkce pravidelnosti

Pravidelné akce jsou užitečné, když je nositeli dovoleno dělat něco v pevné kadenci: jednou za hodinu, čtyřikrát denně, jedno podání týdně atd.

Můžete nakonfigurovat běžné akce při vytvoření rozšíření zámku nebo aktualizovat spuštěnou relaci z backendu:

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

Režimy:

unlimited: akce jsou vždy dostupné.
non_cumulative: zpřístupňuje se vždy jen jedno okno; nepoužité akce se nesčítají.
cumulative: akce se hromadí až do maxActions.

Přečtěte si aktuální dostupnost:

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

Odešlete důvěryhodnou pravidelnou akci:

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

Používejte pravidelné akce, když hlavním pravidlem je „jak často se tato akce může opakovat?“.

Vlastní požadované akce

Použijte pravidlo požadovaného postupu, když hlavním pravidlem je „kolik dokončení je požadováno za den nebo týden?“.

Konfigurace požadavků se nachází v konfiguraci nainstalované rozšiřující relace pod 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"
    }
  }
}

Podporované jednotky kadence:

day
week

Podporované typy trestů za zmeškané okno:

none
add_time
freeze
pillory

Zaznamenávejte důvěryhodný postup až poté, co váš backend ověří akci:

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

Plánovač Chastify vyhodnocuje dokončená okna a aplikuje nakonfigurovaný trest za zmeškané okno, pokud je počet dokončených oken nižší než requiredCount.

tip

V případě potřeby použijte obě funkce společně:

regular-actions omezuje, jak často může uživatel odesílat.
requirements/progress zaznamenává, zda proběhl dostatek ověřených dokončení za daný den nebo týden.
metadata.unlockBlockers blokuje odemknutí, dokud není splněn aktuální požadavek.

Odměny

Odměny jsou privilegované akce uzamčení. Volejte je ze svého backendu po ověřeném úspěchu.

Čas odstranění:

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

Začněte hygienické otevírání:

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

Odeslat vlastní oznámení:

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

Tresty

Tresty jsou také privilegované akce zámku. Použijte je až poté, co váš backend ověří selhání nebo nesplnění požadavku.

Přidat čas:

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

Zmrazit:

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

Zadat úkol:

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

Začátek pranýře:

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

Doporučený vzor

Pro hry, rutiny a ověřovací výzvy:

Iframe se otevře a přečte spouštěcí hash.
Iframe požádá váš backend o vytvoření výzvy pomocí mainToken.
Backend si vyměňuje/používá mainToken s klíčem vývojářského API v rozsahu aplikace.
Iframe odesílá odpovědi do vašeho backendu.
Backend ověřuje výsledek.
Backend zaznamenává důvěryhodný pokrok pomocí requirements/progress.
Backend aplikuje odměnu nebo trest pomocí /action.
Backendové záplaty metadata.unlockBlockers a metadata.homeActions.
Iframe čte bezpečný stav/metadata a zobrazuje výsledek.

Díky tomu je uživatelské rozhraní rozšíření responzivní a zároveň se na serveru zachovává stav důvěryhodného zámku.

Mapa prvků​

Požadované záhlaví backendu​

Odemknout blokátory​

Blokátory založené na postupu​

Časové limity pokusů​

Manuální blokátory​

Funkce pravidelnosti​

Vlastní požadované akce​

Odměny​

Tresty​

Doporučený vzor​