Funkcje interfejsu API rozszerzeń

Użyj tej strony, jeśli znasz już podstawowy model rozszerzenia i chcesz zbudować faktyczne zachowanie blokady: wymagane działania, odblokowanie blokad, regularność, nagrody i kary.

uwaga

Kod iframe przeglądarki nie jest zaufany.

Twój element iframe może renderować interfejs użytkownika i odczytywać bezpieczny kontekst sesji. Wszystko, co zapisuje stan sesji, nagradza użytkownika, usuwa czas, usuwa blokadę odblokowania, rejestruje postęp w spełnianiu zaufanych wymagań, uruchamia lub nie odlicza próby lub nakłada karę, musi zostać zweryfikowane przez Twój system.

Mapa funkcji

Funkcja	Co robi	Gdzie działa
Odblokuj blokady	Uniemożliw odblokowanie, dopóki rozszerzenie nie usunie blokady lub nie zarejestruje wystarczającej ilości zaufanych postępów	Konfiguracja blokady startowej lub wywołania metadanych zaplecza/postępu
Akcje główne	Dodaje widoczną akcję na stronie blokady, np. „Zagraj w wyzwanie”	Konfiguracja blokady początkowej lub poprawki metadanych zaplecza
Akcje regularne	Pozwala użytkownikowi na ograniczoną liczbę akcji w danym interwale	Chastify śledzi liczniki; twoje zaplecze przesyła zaufane akcje
Wymagany postęp	Śledzi codzienne lub cotygodniowe wymagania dotyczące ukończenia	Twoje zaplecze rejestruje postęp; harmonogram Chastify sprawdza pominięte okna
Nagrody	Usuwa czas, rozpoczyna otwieranie higieniczne lub wysyła powiadomienie po zweryfikowanym powodzeniu	Twój zaplecze wywołuje uprzywilejowane punkty końcowe
Kary	Dodaje czas, zamraża, przypisuje zadanie, uruchamia pręgierz lub wysyła powiadomienie po zweryfikowanym niepowodzeniu	Twój system zaplecza wywołuje uprzywilejowane punkty końcowe

Wymagane nagłówki zaplecza

Punkty końcowe rozszerzeń uprzywilejowanych wymagają obu nagłówków:

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

Kod mainToken identyfikuje otwartą sesję rozszerzenia. Klucz API dla programisty potwierdza, że żądanie pochodzi z Twojego zaplecza.

Odblokuj blokery

Używaj blokad odblokowania, gdy użytkownik musi coś dokończyć przed odblokowaniem. Przykłady:

Wygraj 3 gry.
Uzupełnij dzisiejszy dowód treningu.
Rozwiąż jedną zagadkę weryfikacyjną.
Wykonaj wszystkie wymagane czynności rozszerzeń dla bieżącego okna.

Obsługiwane są dwa wzorce.

Blokady oparte na postępie

Użyj initialMetadata.unlockRequirements, gdy blokada powinna zostać zablokowana natychmiast po jej uruchomieniu lub zaakceptowaniu współdzielonego szablonu. Chastify inicjuje stan sesji rozszerzenia z tej ogólnej konfiguracji, dzięki czemu blokada istnieje jeszcze przed pierwszym otwarciem rozszerzenia przez użytkownika.

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

Po zweryfikowaniu przez zaplecze zaufanego ukończenia, zapisz postęp dla tej samej metryki:

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 zapisuje to jako postęp odblokowania i automatycznie uznaje wymaganie za spełnione, gdy postęp osiągnie requiredCount. Karty blokady mogą wskazywać postęp, np. 1 of 3 complete.

Używaj stabilnych nazw metryk. Jedna metryka reprezentuje jedno aktywne wymaganie odblokowania dla danej sesji rozszerzenia.

Limity czasu prób

Użyj kodu attemptLimit, gdy zaufana próba musi wygasnąć, jeśli nie zostanie ukończona na czas. Kod Chastify przechowuje aktywną próbę pod kodem data.attemptLimits.<metric> i może oznaczyć ją jako nieudaną po upływie terminu. Ten stan jest zarządzany przez kod Chastify; uruchamiaj i przerywaj próby za pośrednictwem punktów końcowych zamiast samodzielnie wpisywać kod data.attemptLimits.

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

Kod startPolicy może być zmieniony na activity, gdy odliczanie rozpoczyna się, gdy użytkownik zaczyna grać, lub na availability, gdy odliczanie rozpoczyna się, gdy tylko akcja stanie się dostępna dla zamka.

Rozpocznij próbę z poziomu zaplecza:

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

Gdy Twój back-end sprawdzi próbę, poproś Chastify o jej odrzucenie, jeśli termin minął:

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

Jeśli nieudane próby powodują zużycie czasu odnowienia, należy także przesłać zwykłą akcję dla nieudanej próby.

Blokady ręczne

Użyj unlockBlockers, gdy Twój backend musi ręcznie zdecydować, czy odblokowanie jest zablokowane. Zaktualizuj metadane z 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."
        }
      }
    ]
  }'

Wyczyść blokadę po sprawdzeniu ukończenia przez zaplecze:

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

notatka

unlockBlockers to ręczne metadane. Informują one Chastify, że odblokowanie jest zablokowane do czasu usunięcia blokady przez system zaplecza. initialMetadata.unlockRequirements to metadane oparte na postępie. Chastify może je automatycznie ocenić na podstawie zaufanego postępu zarejestrowanego dla pasującej metryki.

Funkcja regularności

Regularne działania są przydatne, gdy użytkownikowi pozwala się na wykonywanie czynności w ustalonym rytmie: raz na godzinę, cztery razy dziennie, raz na tydzień itd.

Możesz skonfigurować standardowe akcje po utworzeniu rozszerzenia blokady lub zaktualizować sesję aktywną z poziomu zaplecza:

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

Tryby:

unlimited: akcje są zawsze dostępne.
non_cumulative: jedno okno staje się dostępne na raz; nieużywane akcje nie kumulują się.
cumulative: akcje naliczają się do maxActions.

Przeczytaj aktualną dostępność:

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

Prześlij zaufaną regularną akcję:

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

Stosuj zwykłe akcje, gdy główną zasadą jest „jak często ta akcja może się wydarzyć?”.

Niestandardowe wymagane działania

Użyj wymaganego postępu, gdy główną zasadą jest „ile ukończeń jest wymaganych na dzień lub tydzień?”.

Konfiguracja wymagań znajduje się w konfiguracji sesji zainstalowanego rozszerzenia 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"
    }
  }
}

Obsługiwane jednostki kadencji:

day
week

Obsługiwane typy kar za pominięte okno:

none
add_time
freeze
pillory

Rejestruj zaufany postęp dopiero po sprawdzeniu akcji przez zaplecze:

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

Harmonogram Chastify ocenia ukończone okna i stosuje skonfigurowaną karę za pominięte okno, jeśli liczba ukończonych okien jest mniejsza niż requiredCount.

wskazówka

W razie potrzeby używaj obu funkcji jednocześnie:

regular-actions ogranicza częstotliwość przesyłania danych przez użytkownika.
requirements/progress rejestruje, czy w danym dniu lub tygodniu wykonano wystarczającą liczbę zweryfikowanych operacji.
Bloki metadata.unlockBlockers są odblokowywane do momentu spełnienia bieżącego wymagania.

Nagrody

Nagrody to uprzywilejowane akcje blokady. Wywołaj je z zaplecza po potwierdzeniu sukcesu.

Usuń czas:

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

Rozpocznij higieniczne otwarcie:

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

Wyślij niestandardowe powiadomienie:

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

Kary

Kary to również uprzywilejowane akcje blokady. Stosuj je dopiero po tym, jak backend zweryfikuje błąd lub pominięte wymaganie.

Dodaj czas:

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

Zamrażać:

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

Przypisz zadanie:

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

Rozpocznij pręgierz:

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

Zalecany wzór

W przypadku gier, procedur i wyzwań weryfikacyjnych:

Iframe otwiera się i odczytuje hash uruchomienia.
Iframe prosi Twój back-end o utworzenie wyzwania przy użyciu mainToken.
Zaplecze wymienia/używa mainToken z kluczem API programisty obejmującym aplikację.
Iframe przesyła odpowiedzi do Twojego zaplecza.
Backend weryfikuje wynik.
Zaplecze rejestruje zaufany postęp za pomocą requirements/progress.
Zaplecze stosuje nagrodę lub karę za pomocą kodu /action.
Poprawki back-endowe metadata.unlockBlockers i metadata.homeActions.
Iframe odczytuje bezpieczny stan/metadane i wyświetla wynik.

Dzięki temu interfejs użytkownika rozszerzenia pozostaje responsywny, a na serwerze utrzymywany jest zaufany stan blokady.

Mapa funkcji​

Wymagane nagłówki zaplecza​

Odblokuj blokery​

Blokady oparte na postępie​

Limity czasu prób​

Blokady ręczne​

Funkcja regularności​

Niestandardowe wymagane działania​

Nagrody​

Kary​

Zalecany wzór​