Přeskočit na hlavní obsah

Vyzkoušejte API pro vývojáře rozšíření

Tuto příručku použijte, pokud chcete vytvořit rozšíření Chastify, hostovat stránku s rozšířením iframe nebo volat vývojářské API z vlastního backendu.

Tato stránka je výchozím bodem: jaký režim zvolit, kam zavolat jako první a kam jít dál.

Konkrétní chování rozšíření, jako jsou blokátory odemykání, pravidelné požadované akce, odměny a tresty, naleznete v článku Funkce API rozšíření.

tip

Chcete si jen ovládat vlastní zámek?

Pokud nepotřebujete vytvářet veřejné rozšíření, stránka Externí API a programy je nejjednodušší způsob, jak začít. Stačí vytvořit token DEV a zavolat jednoduché REST koncové body – není nutné nastavovat rozšíření, používat iframe ani spravovat relace. Podporuje přidání/odebrání času, zmrazení, úlohy, příkazy zařízení a další.

K čemu je toto API​

Rozhraní API pro vývojáře rozšíření umožňuje vytvářet rozšíření třetích stran, která běží v rámci relací zámků Chastify.

S ním můžete:

  • Čtení kontextu relace a zámku (session.get pro rozšíření, /api/apps/v1/session pro vaši vlastní automatizaci zámků)
  • Čtení dat vlastněných rozšířením pro každou relaci zámku (state.get) a jejich zápis z backendu (PUT/PATCH /state)
  • Ukládání obrazových souborů vlastněných rozšířeními do úložiště R2 spravovaného Chastify (files.*)
  • Přidání akcí uživatelského rozhraní rozšíření na karty zámku (metadata.homeActions)
  • Proces odemykání brány s blokátory odemykání vlastněnými rozšířením (metadata.unlockBlockers)
  • Spouštění akcí zámku z důvěryhodného backendu (přidání/odebrání času, zmrazení/rozmrazení, oprava nastavení)
  • Spouštění úloh a hygienických akcí (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Odesílejte pravidelné akce s podporou čítačů/kadence
  • Odesílat podporované příkazy zařízení, pokud jsou k dispozici
  • Zapisovat vlastní položky protokolu rozšíření pro uzamčení historie

Co si můžete postavit​

Správná sada funkcí závisí na tom, kde důvěra sídlí.

Rozšíření iframe pouze pro frontend mohou vytvářet prostředí zaměřená na uživatelské rozhraní, která nevyžadují mutaci důvěryhodných zámků:

  • Stránky nastavení, které shromažďují konfiguraci rozšíření
  • Dashboardy, které čtou kontext relace
  • Uživatelská rozhraní hádanek, kontrolních seznamů nebo her, která čtou stav relace a odesílají ověřený postup přes backend
  • Toky založené na médiích, které čtou rozšiřující soubory, které jsou již uložené uživatelem Chastify
  • Vstupní body pro akce na domovské stránce, které otevírají váš iframe s intentem

Serverová rozšíření mohou vytvářet funkce ovlivňující uzamčení, protože váš backend ověřuje výsledky před voláním privilegovaných API:

  • Systémy úkolů nebo návyků s požadavky na odemčení
  • Denní nebo týdenní požadavky s naplánovanými tresty za zmeškané období
  • Hry, které odměňují úspěch nebo trestají neúspěch změnami času uzamčení
  • Ověřovací procesy, které po ověření na straně serveru odstraní blokátory odemknutí.
  • Doprovodné toky pro ovládání zařízení pomocí podporovaných příkazů zařízení
  • Pracovní postupy webhooků/databází, které uchovávají stav rozšíření mimo iframe

Externí programy slouží k soukromé automatizaci vašeho vlastního aktivního zámku:

  • Místní skripty
  • Osobní dashboardy
  • Automatizační nástroje, které používají klíč DEV pro celého uživatele

Vyberte si svůj režim​

Vyberte si jeden z těchto režimů:

  1. Hosted iframe extension: hostujte statické uživatelské rozhraní iframe na Cloudflare Pages nebo podobné službě. Použijte most pro nastavení, kontext relace a bezpečné čtení. Nepoužívejte tento režim samostatně pro zápisy stavu, odměny, tresty, dokončení odemknutí nebo postup důvěryhodných požadavků.
  2. Server-backed extension: hostujte uživatelské rozhraní iframe a spusťte si vlastní backend. IFrame odešle svůj spouštěcí kód mainToken do vašeho backendu a váš backend zavolá rozhraní Chastify Extension API s klíčem vývojářského API s rozsahem aplikace a kódem x-chastify-main-token. Tento režim použijte pro privilegované akce, odemykání blokátorů, důvěryhodný postup, odměny, tresty, webhooky a externí databáze.
  3. External API & Programs: pro skripty, lokální programy nebo automatizace, které ovládají váš vlastní aktivní zámek, použijte klíč DEV pro celého uživatele. Toto není režim pro uživatele třetích stran, kteří instalují vaše rozšíření.

Pokud testujete rychle, začněte s režimem iframe pro uživatelské rozhraní a bezpečné čtení. Před implementací zápisů stavu, důvěryhodných odměn, změn času, plánovaného průběhu požadavků nebo dokončení blokování odemknutí přidejte backend.

caution

Kód iframe nepředstavuje hranici důvěryhodnosti. Cokoli, co je viditelné pro iframe, včetně datových částí hash a spouštěcích tokenů, může uživatel zkontrolovat a přehrát.

Prvních 10 minut (režim iframe)​

  1. Načíst datovou část location.hash z otevřeného iframe Chastify.
  2. Vytvořte požadavek na přemostění pro session.get.
  3. Potvrďte odpověď pomocí type: "chastify:ext:resp" a ok: true.
  4. Testovací stav se čte s kódem state.get.
  5. Přidejte automatickou změnu velikosti a podporu motivů, aby se iframe v uživatelském rozhraní choval správně.

Podpora motivů je součástí produkčního iframe. Chastify předává hodnoty ui v hashovací hodnotě spouštění a odesílá aktualizace motivů v reálném čase, dokud je iframe otevřený. Příklady světlých/tmavých vzorů a kontrastně bezpečných vzorů Tailwind naleznete v článku Iframe Theming.

Požadované hodnoty užitečného zatížení:

  • bridge.nonce
  • bridge.parentOrigin
  • sessionId
  • lockId

Příklad požadavku na přemostění:

{
  "type": "chastify:ext:req",
  "v": 1,
  "id": "request-id", // unique id per request
  "nonce": "nonce-from-hash",
  "action": "session.get",
  "payload": {}
}

Příklad odpovědi mostu:

{
  "type": "chastify:ext:resp",
  "v": 1,
  "id": "request-id",
  "ok": true,
  "data": {}
}

Základní akce, které je třeba se naučit jako první​

  • session.get
  • state.get
    Čtení úložiště JSON vlastněného rozšířením pro relaci uzamčení. Zapisování stavu z backendu s použitím přihlašovacích údajů vývojářského API.
  • files.capabilities, files.list, files.get Pro binární média, jako jsou obrázky puzzle nebo generované náhledy, použijte čtení z úložiště souborů. Uložte ID souborů ve stavu zapsaném v backendu a poté obnovte podepsané URL adresy pomocí files.get.
  • metadata.get Přečíst blokátory odemknutí uzamčení relace a akce/záměry domovské stránky rozšiřující karty.
  • regularActions.get

Mutace relací, jako jsou zápisy stavu, odesílání běžných akcí, nahrávání/mazání souborů za běhu, změny času, aktualizace blokování odemčení, dokončení úloh, spuštění hygieny a příkazy zařízení, musí být volány z backendu s klíčem vývojářského API. Kód iframe prohlížeče není pro tyto akce důvěryhodný.

Úplné adresy URL API (podporováno)​

Základní doména: https://chastify.net

Rozhraní API pro rozšíření relací (/api/extensions/*)​

Tyto trasy mají různé režimy přístupu. Nepovažujte celou plochu /api/extensions/* za bezpečnou pro iframe.

Bezpečné trasy mostu iframe jsou směrovány přes nadřazený objekt Chastify po požadavcích na most postMessage:

  • GET https://chastify.net/api/extensions/sessions/:sessionId
  • GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId

Trasy nainstalovaných rozšíření pouze pro backend vyžadují klíč vývojářského API s rozsahem aplikace a spouštěcí token iframe:

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

Tento model se dvěma tokeny váže požadavek backendu jak k vývojáři rozšíření (Authorization), tak k aktuálně otevřené relaci rozšíření (x-chastify-main-token).

  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • PUT https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/regular-actions/config
  • POST https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • POST https://chastify.net/api/extensions/sessions/:sessionId/files
  • DELETE https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId
  • POST https://chastify.net/api/extensions/sessions/:sessionId/logs/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/notifications/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/device-command
  • POST https://chastify.net/api/extensions/sessions/:sessionId/action
  • POST https://chastify.net/api/extensions/sessions/:sessionId/requirements/progress

API pro backendové tokeny (/api/apps/v1/*)​

Použijte Authorization: Bearer <user-wide DEV token>. Tyto koncové body spravují aktivní relace zámku vlastníka tokenu a jsou určeny pro skripty/programy externího API, nikoli pro relace nainstalovaných rozšíření třetích stran.

  • GET https://chastify.net/api/apps/v1/session
  • GET https://chastify.net/api/apps/v1/state
  • PUT https://chastify.net/api/apps/v1/state
  • PATCH https://chastify.net/api/apps/v1/state
  • GET https://chastify.net/api/apps/v1/metadata
  • PATCH https://chastify.net/api/apps/v1/metadata
  • POST https://chastify.net/api/apps/v1/action
  • POST https://chastify.net/api/apps/v1/lock/apply-time
  • POST https://chastify.net/api/apps/v1/lock/freeze
  • POST https://chastify.net/api/apps/v1/lock/unfreeze
  • POST https://chastify.net/api/apps/v1/logs/custom

Příkazy mostu iframe​

Datové části příkazů mostu jsou odesílány pomocí iframe (chastify:ext:req) a směrovány rodičovským prvkem Chastify. Most je záměrně omezen na bezpečné/sessionové operace uživatelského rozhraní.

  • session.get -> GET https://chastify.net/api/extensions/sessions/:sessionId
  • state.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • files.capabilities -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • files.list -> GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • files.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId se { "fileId": "file_record_id" }
  • metadata.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • regularActions.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions

Koncové body mutace relace jsou přímá volání backendového API, nikoli příkazy iframe bridge. To zahrnuje zápisy stavu, odesílání běžných akcí a nahrávání/mazání souborů za běhu, protože kód iframe může ovládat uživatel.

Příklady API backendových relací​

Váš backend musí odeslat obě hlavičky pro privilegovaná volání nainstalovaného rozšíření:

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

Příklady akcí na backendu:

  • metadata.patch -> PATCH /api/extensions/sessions/:sessionId/metadata
  • regularActions.submit -> POST /api/extensions/sessions/:sessionId/regular-actions
  • files.upload -> POST /api/extensions/sessions/:sessionId/files
  • files.delete -> DELETE /api/extensions/sessions/:sessionId/files/:fileId
  • lock.applyTime -> POST /api/extensions/sessions/:sessionId/action se { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action se { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action se { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action se { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action se { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action se { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action se { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action se { "name": "pillory.end", "params": {} }
  • device.command -> POST /api/extensions/sessions/:sessionId/device-command
  • logs.custom -> POST /api/extensions/sessions/:sessionId/logs/custom
  • notifications.custom -> POST /api/extensions/sessions/:sessionId/notifications/custom
  • requirements.progress -> POST /api/extensions/sessions/:sessionId/requirements/progress

Token, rozsah, zrušení a chování auditu​

Použijte správný token pro správnou hranici důvěryhodnosti.

warning

Klíče vývojářského API jsou tajné. Pokud se nějaký dostane do kódu prohlížeče, okamžitě jej zrušte a otočte proměnnou prostředí backendu.

Token spuštění iframe (mainToken)​

  • Zobrazí se v hash iframe, když uživatel otevře stránku s nainstalovaným rozšířením.
  • Záměrně viditelné v prohlížeči. Identifikuje otevřenou relaci rozšíření, ale nejedná se o tajný klíč backendu.
  • Krátkodobé. Aktuální spouštěcí tokeny vyprší po 10 hodinách; obnovte je opětovným otevřením stránky rozšíření.
  • Vyžadováno jako x-chastify-main-token, když váš backend volá trasy relace nainstalovaného rozšíření, aby Chastify mohl navázat požadavek backendu na uživatele/relaci, který otevřel rozšíření.
  • Nesmí se používat samostatně k autorizaci změn času, odemčení dokončení blokování, dokončení úloh, příkazů zařízení, nahrávání/mazání za běhu, vlastních protokolů nebo vlastních oznámení.

Klíč vývojářského API s rozsahem aplikace​

  • Vytvořeno z vývojářského uživatelského rozhraní pro jednu rozšiřující aplikaci.
  • Tajný kód pouze pro backend. Nikdy jej nevkládejte do JavaScriptu iframe, balíčků mobilních aplikací, konfigurace statického hostingu ani do protokolů čitelných v prohlížeči.
  • Používá se se Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY a x-chastify-main-token.
  • Lze volat API relací nainstalovaného rozšíření pouze pro relace, které odpovídají rozšiřující aplikaci a spouštěcímu tokenu.
  • Nevyprší automaticky. Pokud je odhalen, okamžitě jej zrušte a otočte proměnnou prostředí backendu.

Klíč vývojářského API pro celý uživatel​

  • Vytvořeno z uživatelského rozhraní pro vývojáře bez výběru rozšiřující aplikace.
  • Tajný kód pouze pro backend pro /api/apps/v1/*.
  • Řídí aktuální/budoucí aktivní relace zámku vlastníka klíče.
  • Nelze použít jako přihlašovací údaje pro nainstalované rozšíření třetí strany.

Odvolání​

  • Zrušené klíče vývojářského API zastavují autorizaci nových požadavků.
  • Zrušené klíče lze trvale smazat z uživatelského rozhraní pro vývojáře.
  • Nově spuštěné prvky iframe obdrží nové spouštěcí tokeny. Neukládejte mainToken jako dlouhodobé přihlašovací údaje.

Rozsahy a role​

  • Rozsahy rozšiřujících aplikací popisují, co aplikace smí požadovat.
  • Bezpečná volání mostu iframe jsou omezena na bootstrap UI, čtení relací, stav vlastněný rozšířením, čtení metadat, čtení běžných akcí a čtení souborů.
  • Privilegované mutace nainstalované relace vyžadují přihlašovací údaje backendu, i když má rozšíření odpovídající rozsah.
  • Akce závislé na roli mohou být stále odmítnuty na základě toho, zda spuštění patří uživateli nebo držiteli klíče.

Audit a limity​

  • Metadata naposledy použitého klíče vývojářského API se aktualizují při použití klíčů.
  • Privilegované trasy akcí mají omezenou rychlost a při použití nesprávného typu přihlašovacích údajů vracejí explicitní chyby, jako například server_credentials_required nebo user_wide_dev_key_required.
  • Vlastní protokoly zapisují viditelné záznamy historie zámků.
  • Vlastní oznámení vytvářejí oznámení Chastify pro požadovaný cíl.
  • Úplné auditní pokrytí pro každou mutaci privilegovaného rozšíření je sledováno jako položka pro posílení produkčního prostředí.

Podporované hodnoty příkazů​

/api/extensions/sessions/:sessionId/action a /api/apps/v1/action​

name podporuje:

  • add_time
  • remove_time
  • freeze
  • pillory
  • unfreeze
  • toggle_freeze
  • settings.patch
  • task.assign
  • task.start_timer
  • task.complete
  • hygienic_unlock.start
  • pillory.end

Omezení akcí:

  • Akce úkolů vyžadují povolení rozšíření/modulu Úlohy na zámku.
  • hygienic_unlock.start vyžaduje povolené hygienické otevírání a žádnou aktivní hygienickou relaci.

Pomocníci pro uzamčení dat session.get​

session.get / GET /api/apps/v1/session také zahrnuje lockData s booleovskými hodnotami, čísly a řetězci, které jsou přátelské k běhu programu a slouží jako nástroje pro pravidla.

Příklady:

  • booleovské hodnoty: frozen, unlockable, trusted, taskAssigned (true, pokud existuje otevřený TaskRun)
  • čísla: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • řetězce: lockTitle, pole profilu nositele/držitele klíče

Soukromí:

  • wearerLastSeenTimestamp a keyholderLastSeenTimestamp jsou null, když daný uživatel deaktivoval online stav (showOnlineStatus === false).

Příkazy zařízení​

Rozšiřující relace mohou používat koncový bod založený na relaci:

POST /api/extensions/sessions/:sessionId/device-command

Externí programy s tokenem DEV mohou používat jednodušší koncový bod v1 (není potřeba ID relace):

POST /api/apps/v1/device-command

Oba přijímají stejné tělo požadavku a vracejí stejnou odpověď. Úplné podrobnosti naleznete v části Externí API a programy.

Stránka nastavení (volitelné, doporučené)​

Pokud má vaše rozšíření uživatelské rozhraní pro nastavení/konfiguraci:

  1. Nadřazený objekt odesílá chastify:ext:setup:init (uložená konfigurace + kontext).
  2. Váš instalační prvek iframe vrací aktualizace s kódem chastify:ext:setup:config.
  3. Nadřazený program si může vyžádat aktuální konfiguraci pomocí chastify:ext:setup:get_config.

Tok tokenů backendu (když potřebujete volání na straně serveru)​

Pro jednoduché skripty a externí programy použijte uživatelský token DEV ze stránky API pro vývojáře. Viz Externí API a programy.

Výchozí tok v režimu rozšíření iframe:

  1. Chastify vydá pro aktivní relaci rozšíření krátkodobý spouštěcí token viditelný v prohlížeči.
  2. Spouštěcí token je vložen do datové části hash iframe jako mainToken.
  3. Váš iframe přeposílá mainToken do vašeho backendu.
  4. Váš backend volá https://chastify.net/api/extensions/sessions/:sessionId/* s funkcemi Authorization: Bearer <app-scoped Developer API key> a x-chastify-main-token: <mainToken>.

Neodesílejte klíče vývojářského API do kódu iframe/prohlížeče. mainToken identifikuje otevřenou relaci rozšíření; nejedná se o tajný kód backendu a nelze jej samostatně použít pro privilegované akce.

Manuální záložní nastavení:

  • Pokud potřebujete explicitně načíst/otočit spouštěcí token iframe z uživatelského rozhraní první strany, zavolejte GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Pokud potřebujete plánované úlohy, webhooky nebo automatizaci, když stránka Chastify není otevřená, použijte režim backendu. Aktuální mutace relace nainstalovaného rozšíření stále vyžadují platný 10hodinový spouštěcí token iframe, takže bezobslužné úlohy by měly ukládat čekající důkaz a odesílat ho při dalším platném spuštění, pokud nepoužíváte tok serveru první strany/vestavěného serveru určený pro spuštění na pozadí.

info

Pro plně bezobslužné produkční chování upřednostňujte vestavěný/serverový tok první strany nebo počkejte na explicitní udělení rozšíření na pozadí. Rozhraní API relací s rozsahem aplikace jsou aktuálně vázána na spouštěcí token.

Backend vs. Cloudflare Pages (bez serveru)​

Použijte Cloudflare Pages (bez backendového serveru), když:​

  • Chcete nejjednodušší a nejlevnější nastavení (hosting lze provést zdarma).
  • Akce řízené uživatelským rozhraním potřebujete pouze tehdy, když je uživatel aktivně na stránce vašeho rozšíření.
  • Zápisy stavu rozšíření uchovávané na serveru nepotřebujete.
  • Rychle vytváříte prototypy nebo lehká rozšíření.

Příklad lokálního testování (PowerShell):

cloudflared tunnel --url http://localhost:5174

Při testování použijte vygenerovanou veřejnou URL adresu jako URL adresu iframe.

Backendový server použijte, když:​

  • Potřebujete naplánované úlohy (chování podobné cronu).
  • Potřebujete webhooky nebo externí integrace.
  • Potřebujete automatizaci/zpracování na pozadí, když na stránce rozšíření nikdo není.
  • Potřebujete serverem řízené pracovní postupy, které musí běžet nepřetržitě.

Důležité omezení bez backendu:

  • Žádné spuštění na pozadí. Vaše rozšíření může provádět akce pouze tehdy, když má uživatel otevřený prvek iframe rozšíření a interaguje s ním.

Běžné problémy​

  • 403 extension_not_enabled: rozšíření není pro tento zámek povoleno.
  • 409 lock_ended: zámek již není aktivní.
  • 429: dosaženo limitu rychlosti.
  • Žádné odpovědi v iframe: zkontrolujte nonce, targetOrigin (parentOrigin) a povolené původy.

Další průvodci​