拡張機能APIの機能

基本的な拡張モデルを理解していて、必要なアクション、ロック解除のブロック、規則性、報酬、罰則など、実際のロック動作を構築したい場合は、このページを使用してください。

注意

ブラウザのiframeコードは信頼できません。

iframe は UI をレンダリングし、安全なセッションコンテキストを読み取ることができます。セッションステートの書き込み、着用者への報酬付与、時間の削除、ロック解除ブロッカーの解除、信頼済み要件の進捗状況の記録、試行タイマーの開始または失敗、あるいは罰則の適用を行うものはすべて、バックエンドで検証する必要があります。

フィーチャーマップ

特徴	機能	動作環境
ブロッカーを解除する	拡張機能がブロッカーをクリアするか、十分な信頼できる進行状況を記録するまで、ロックを解除しないようにする	ロック開始設定またはバックエンドのメタデータ/進行状況呼び出しをロックする
ホームアクション	ロックページに「チャレンジをプレイ」などの目に見えるアクションを追加します	ロック開始設定またはバックエンドメタデータのパッチ
通常のアクション	一定間隔でウェアラバーのアクションを制限された数だけ許可します	Chastify はカウンターを追跡します。バックエンドは信頼できるアクションを送信します
必要な進捗状況	日次または週次の完了要件を追跡します	バックエンドが進捗状況を記録し、Chastify スケジューラが見逃されたウィンドウを確認します
報酬	時間の削除、衛生的な開封の開始、または検証成功後の通知の送信	バックエンドは特権エンドポイントを呼び出します
罰則	検証済みの失敗後に、時間を追加、凍結、タスクの割り当て、さらし台の開始、または通知の送信を行います	バックエンドは特権エンドポイントを呼び出します

必須のバックエンドヘッダー

特権拡張エンドポイントには、以下の両方のヘッダーが必要です。

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

mainTokenは、開いている拡張セッションを識別します。開発者APIキーは、リクエストがバックエンドから送信されたことを証明します。

ブロッカーを解除

装着者がロックを解除する前に何かを完了する必要がある場合は、ロック解除ブロッカーを使用してください。例：

3試合に勝つ。
今日のワークアウトの証明を完了してください。
検証パズルを1つ解いてください。
現在のウィンドウに必要なすべての拡張機能操作を完了してください。

サポートされているパターンは2つあります。

進行度に基づくブロッカー

ロックが開始された直後、または共有テンプレートが受け入れられた直後にロックをブロックする必要がある場合は、initialMetadata.unlockRequirementsを使用してください。Chastifyは、この汎用設定から拡張機能のセッション状態を初期化するため、ユーザーが初めて拡張機能を開く前からブロッカーが存在します。

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

バックエンドが信頼できる完了を確認したら、同じ指標の進捗状況を記録します。

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はこれをロック解除の進行状況として保存し、進行状況がrequiredCountに達すると自動的に要件が満たされたとみなします。ロックカードには、1 of 3 completeなどの進行状況を表示できます。

安定したメトリック名を使用してください。1つのメトリックは、その拡張機能セッションにおける1つの有効なロック解除要件を表します。

試行時間制限

信頼できる試行が時間内に完了しない場合に期限切れとなる必要がある場合は、attemptLimit を使用してください。Chastify はアクティブな試行を data.attemptLimits.<metric> の下に保存し、期限後に失敗としてマークすることができます。この状態は Chastify によって管理されます。試行の開始と失敗は、data.attemptLimits を自分で記述するのではなく、試行エンドポイントを介して行ってください。

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

startPolicyは、装着者がゲームを開始した時点でカウントダウンが開始される場合はactivityとなり、ロックのアクションが利用可能になった時点でカウントダウンが開始される場合はavailabilityとなる。

バックエンドから試行を開始してください。

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

バックエンドが試行をチェックする際に、期限が過ぎている場合はChastifyに試行を失敗させるように要求してください。

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

失敗した試行がクールダウンスロットを消費する場合、失敗した試行に対しても通常のアクションを送信してください。

手動ブロッカー

バックエンドでロック解除がブロックされているかどうかを手動で判断する必要がある場合は、unlockBlockers を使用してください。バックエンドからのメタデータをパッチします。

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

バックエンドが完了を確認したら、ブロッカーをクリアしてください。

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

注記

unlockBlockersは手動メタデータです。これは、バックエンドがブロッカーを解除するまでロック解除がブロックされていることをChastifyに伝えます。initialMetadata.unlockRequirementsは進捗状況に基づくメタデータです。Chastifyは、一致するメトリックに対して記録された信頼できる進捗状況からこれを自動的に評価できます。

規則性機能

定期的な動作は、装着者が一定のペースで何かを行うことが許可されている場合に役立ちます。例えば、1時間に1回、1日に4回、1週間に1回などです。

ロック拡張機能が作成されたとき、またはバックエンドから実行中のセッションを更新したときに、定期的なアクションを設定できます。

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

モード:

unlimited: アクションは常に利用可能です。
non_cumulative: 一度に使用可能になるウィンドウは1つだけです。未使用のアクションは積み重ねられません。
cumulative: アクションはmaxActionsまで累積されます。

現在の在庫状況を確認する：

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

信頼できる定期的なアクションを送信します。

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

主なルールが「このアクションはどのくらいの頻度で発生できるか？」である場合は、定期的なアクションを使用してください。

カスタム必須アクション

主なルールが「1日または1週間あたりに何件の完了が必要か？」である場合は、必要進捗状況を使用してください。

要件設定は、インストール済みの拡張機能セッション設定の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"
    }
  }
}

サポートされているケイデンス単位:

day
week

対応している不履行期間ペナルティの種類：

none
add_time
freeze
pillory

バックエンドがアクションを検証した後でのみ、信頼できる進捗状況を記録する。

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のスケジューラは完了したウィンドウを評価し、完了したウィンドウ数がrequiredCountを下回る場合は、設定されたウィンドウ欠落ペナルティを適用します。

ヒント

必要に応じて両方の機能を組み合わせて使用してください。

regular-actionsは、着用者が送信できる頻度を制限します。
requirements/progressは、その日またはその週に十分な数の検証済み完了が発生したかどうかを記録します。
metadata.unlockBlockersブロックは、現在の要件が満たされるまでロック解除されます。

報酬

報酬は特権的なロック操作です。成功が確認された後、バックエンドから呼び出してください。

時間を削除する:

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

衛生的な営業開始を始めましょう：

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

カスタム通知を送信する：

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

罰

ペナルティも特権ロック操作です。バックエンドが失敗または要件の未達成を確認した後にのみ適用してください。

時間を追加する:

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

フリーズ：

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

タスクを割り当てる：

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

さらし台開始：

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

フィーチャーマップ​

必須のバックエンドヘッダー​

ブロッカーを解除​

進行度に基づくブロッカー​

試行時間制限​

手動ブロッカー​

規則性機能​

カスタム必須アクション​

報酬​

罰​

おすすめのパターン​