Возможности 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"
    }
  }'

Карта объектов​

Обязательные заголовки бэкэнда​

Разблокировать блокировщики​

Блокировщики, основанные на прогрессе​

Ограничения по времени выполнения попыток​

Ручные блокировщики​

Функция регулярности​

Настраиваемые обязательные действия​

Награды​

Наказания​

Рекомендуемый шаблон​