Značajke API-ja proširenja

Koristite ovu stranicu kada već razumijete osnovni model proširenja i želite izgraditi stvarno ponašanje zaključavanja: potrebne radnje, blokade otključavanja, redovitost, nagrade i kazne.

caution

iframe kod preglednika nije pouzdan.

Vaš iframe može prikazati korisničko sučelje i čitati kontekst sigurne sesije. Sve što zapisuje stanje sesije, nagrađuje korisnika, uklanja vrijeme, briše blokator otključavanja, bilježi napredak pouzdanog zahtjeva, pokreće ili ne uspijeva mjerač vremena pokušaja ili primjenjuje kaznu mora provjeriti vaš backend.

Karta značajki

Značajka	Što radi	Gdje se izvodi
Otključaj blokatore	Spriječi otključavanje dok tvoja ekstenzija ne ukloni blokator ili ne zabilježi dovoljno pouzdanog napretka	Zaključaj konfiguraciju pokretanja ili pozadinske metapodatke/pozive napretka
Početna radnje	Dodaje vidljivu radnju na zaključanu stranicu, kao što je "Igraj izazov"	Konfiguracija zaključavanja pri pokretanju ili zakrpe metapodataka pozadine
Redovite radnje	Omogućuje ograničen broj radnji korisnika po intervalu	Chastify prati brojače; vaš backend šalje pouzdane radnje
Potreban napredak	Prati dnevne ili tjedne zahtjeve za dovršetak	Vaš backend bilježi napredak; Chastify planer provjerava propuštene prozore
Nagrade	Uklanja vrijeme, pokreće higijensko otvaranje ili šalje obavijest nakon potvrđenog uspjeha	Vaš backend poziva privilegirane krajnje točke
Kazne	Dodaje vrijeme, zamrzava, dodjeljuje zadatak, pokreće sramotu ili šalje obavijest nakon potvrđenog neuspjeha	Vaš backend poziva privilegirane krajnje točke

Obavezni zaglavlja pozadinske komponente

Privilegirane krajnje točke proširenja zahtijevaju oba zaglavlja:

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

mainToken identificira otvorenu sesiju proširenja. Ključ API-ja za razvojne programere dokazuje da je zahtjev došao s vašeg pozadinskog sustava.

Otključaj blokatore

Koristite blokatore otključavanja kada korisnik mora nešto završiti prije otključavanja. Primjeri:

Pobijedite u 3 utakmice.
Ispunite dokaz za današnji trening.
Završite jednu zagonetku za provjeru.
Dovršite sve potrebne radnje proširenja za trenutni prozor.

Postoje dva podržana obrasca.

Blokatori temeljeni na napretku

Koristite initialMetadata.unlockRequirements kada zaključavanje treba biti blokirano čim se zaključavanje pokrene ili se prihvati dijeljeni predložak. Chastify inicijalizira stanje sesije proširenja iz ove generičke konfiguracije, tako da blokator postoji čak i prije nego što korisnik prvi put otvori vaše proširenje.

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

Nakon što vaš backend potvrdi pouzdano dovršetak, zabilježite napredak za istu 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 pohranjuje ovo kao napredak otključavanja i automatski tretira zahtjev kao ispunjen kada napredak dosegne requiredCount. Kartice zaključavanja mogu prikazivati napredak kao što je 1 of 3 complete.

Koristite stabilne nazive metrika. Jedna metrika predstavlja jedan aktivni zahtjev za otključavanje za tu sesiju proširenja.

Vremenska ograničenja pokušaja

Koristite attemptLimit kada pouzdani pokušaj mora isteći ako nije dovršen na vrijeme. Chastify pohranjuje aktivni pokušaj pod data.attemptLimits.<metric> i može ga označiti kao neuspjelog nakon isteka roka. Ovim stanjem upravlja Chastify; pokušaji se pokreću i ne uspijevaju putem krajnjih točaka pokušaja umjesto da sami pišete data.attemptLimits.

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

startPolicy može biti activity kada odbrojavanje počinje čim korisnik počne igrati ili availability kada odbrojavanje počinje čim je akcija dostupna za bravu.

Započnite pokušaj iz svog backenda:

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

Kada vaš backend provjeri pokušaj, zatražite od Chastify da ga ne uspije ako je rok prošao:

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

Ako neuspjeli pokušaji zauzmu vrijeme hlađenja, također pošaljite redovnu radnju za neuspjeli pokušaj.

Ručni blokatori

Koristite unlockBlockers kada vaš backend treba ručno odlučiti je li otključavanje blokirano. Zakrpa metapodataka iz vašeg backenda:

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

Uklonite blokator nakon što vaš backend potvrdi dovršetak:

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 su ručni metapodaci. Oni govore Chastify da je otključavanje blokirano dok vaš backend ne ukloni blokator. initialMetadata.unlockRequirements su metapodaci temeljeni na napretku. Chastify ih može automatski procijeniti na temelju pouzdanog napretka zabilježenog za odgovarajuću metriku.

Značajka regularnosti

Redovite radnje su korisne kada je korisniku dopušteno nešto raditi u fiksnom ritmu: jednom na sat, četiri puta dnevno, jedno podnošenje tjedno i tako dalje.

Možete konfigurirati redovne radnje kada se stvori proširenje za zaključavanje ili ažurirati pokrenutu sesiju iz vašeg backenda:

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

Načini rada:

unlimited: akcije su uvijek dostupne.
non_cumulative: jedan prozor postaje dostupan odjednom; neiskorištene radnje se ne slažu.
cumulative: radnje se akumuliraju do maxActions.

Pročitajte trenutnu dostupnost:

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

Pošaljite pouzdanu redovnu radnju:

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

Koristite redovne radnje kada je glavno pravilo "koliko često se ova radnja može dogoditi?".

Prilagođene obavezne radnje

Koristite potreban napredak kada je glavno pravilo "koliko je dovršenja potrebno dnevno ili tjedno?".

Konfiguracija zahtjeva nalazi se u konfiguraciji instalirane sesije proširenja 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"
    }
  }
}

Podržane jedinice za kadencu:

day
week

Podržane vrste kazni za propušteni prozor:

none
add_time
freeze
pillory

Zabilježite pouzdani napredak tek nakon što vaš backend potvrdi radnju:

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

Chastify-ov planer procjenjuje dovršene prozore i primjenjuje konfiguriranu kaznu za propuštene prozore ako je broj dovršenih prozora manji od requiredCount.

tip

Koristite obje značajke zajedno kada je potrebno:

regular-actions ograničava koliko često korisnik može poslati.
requirements/progress bilježi je li se dogodilo dovoljno provjerenih dovršetaka za taj dan ili tjedan.
metadata.unlockBlockers blokira otključavanje dok se ne zadovolji trenutni zahtjev.

Nagrade

Nagrade su privilegirane akcije zaključavanja. Pozovite ih iz svog backenda nakon potvrđenog uspjeha.

Ukloni vrijeme:

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

Započnite higijensko otvaranje:

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

Pošalji prilagođenu obavijest:

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

Kazne

Kazne su također privilegirane akcije zaključavanja. Primijenite ih tek nakon što vaš backend potvrdi neuspjeh ili propušteni zahtjev.

Dodaj vrijeme:

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

Zamrznuti:

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

Dodijelite zadatak:

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

Početak srama:

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

Preporučeni uzorak

Za igre, rutine i izazove provjere:

Iframe se otvara i čita hash za pokretanje.
Iframe traži od vašeg backenda da kreira izazov koristeći mainToken.
Backend razmjenjuje/koristi mainToken sa svojim ključem API-ja razvojnih programera koji je u opsegu aplikacije.
Iframe šalje odgovore vašem backendu.
Backend provjerava rezultat.
Backend bilježi pouzdani napredak pomoću requirements/progress.
Backend primjenjuje nagradu ili kaznu sa /action.
Backend zakrpe metadata.unlockBlockers i metadata.homeActions.
Iframe čita sigurno stanje/metapodatke i prikazuje rezultat.

To održava korisničko sučelje proširenja responzivnim, a istovremeno zadržava stanje pouzdanog zaključavanja na poslužitelju.

Karta značajki​

Obavezni zaglavlja pozadinske komponente​

Otključaj blokatore​

Blokatori temeljeni na napretku​

Vremenska ograničenja pokušaja​

Ručni blokatori​

Značajka regularnosti​

Prilagođene obavezne radnje​

Nagrade​

Kazne​

Preporučeni uzorak​