跳到主要内容

扩展 API 功能

如果您已经了解基本扩展模型并想要构建实际的锁定行为，请使用此页面：必需的操作、解锁阻止程序、规律性、奖励和惩罚。

警告

浏览器 iframe 代码不受信任。

您的 iframe 可以渲染用户界面并读取安全的会话上下文。任何写入会话状态、奖励佩戴者、移除时间、清除解锁障碍、记录可信要求进度、启动或失败尝试计时器或施加惩罚的操作，都必须由您的后端进行验证。

特征图​

功能作用适用平台
解锁障碍物在您的扩展程序清除障碍物或记录足够的可靠进度之前，阻止解锁锁定启动配置或后端元数据/进度调用
首页操作在锁定页面添加可见操作，例如“参与挑战”锁定启动配置或后端元数据补丁
常规操作每个时间间隔内允许佩戴者执行有限次数的操作Chastify 跟踪计数器；您的后端提交可信操作
所需进度跟踪每日或每周完成要求您的后端记录进度；Chastify 调度程序检查错过的窗口
奖励验证成功后，移除时间、启动卫生开启或发送通知您的后端调用特权端点
惩罚确认失败后，增加时间、冻结、分配任务、开始示众或发送通知您的后端调用特权端点

必需的后端标头​

特权扩展端点需要这两个标头：

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

mainToken 用于标识已打开的扩展会话。开发者 API 密钥用于证明请求来自您的后端。

解锁障碍物​

当佩戴者必须完成某件事才能解锁时，请使用解锁阻止器。例如：

  • 赢3场比赛。
  • 完成今天的锻炼证明。
  • 完成一个验证谜题。
  • 完成当前窗口所需的所有扩展操作。

有两种支持的模式。

基于进度的障碍​

当锁在启动或接受共享模板后立即被阻止时，请使用 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。

使用稳定的指标名称。一个指标代表该扩展会话中的一个有效解锁需求。

尝试时间限制​

当可信尝试因未及时完成而必须过期时，请使用 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 可以根据匹配指标记录的可信进度自动评估它。

规律性特征​

当佩戴者被允许以固定的节奏执行某项操作时，规律性操作就很有用：例如每小时一次、每天四次、每周一次等等。

您可以配置在创建锁定扩展时执行的常规操作，或者从后端更新正在运行的会话：

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：一次只能有一个窗口可用；未使用的操作不会堆叠。
  • 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
    }
  }'

当主要规则是“此操作可以多久发生一次？”时，使用常规操作。

自定义必填操作​

当主要规则是“每天或每周需要完成多少项任务？”时，使用所需进度。

需求配置位于已安装扩展会话配置中的 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"
    }
  }'

适用于游戏、例程和验证挑战：

  1. Iframe 打开并读取启动哈希值。
  2. Iframe 请求您的后端使用 mainToken 创建一个挑战。
  3. 后端使用 mainToken 与其应用程序范围的开发者 API 密钥进行交换/使用。
  4. Iframe会将答案提交到您的后端。
  5. 后端验证结果。
  6. 后端记录可信进度，使用 requirements/progress。
  7. 后端使用 /action 进行奖励或惩罚。
  8. 后端补丁 metadata.unlockBlockers 和 metadata.homeActions。
  9. Iframe 读取安全状态/元数据并显示结果。

这样既能保持扩展程序用户界面的响应速度，又能保持服务器上的可信锁定状态。