확장 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승을 거두세요.
• 오늘 운동 완료 증명을 완료하세요.
• 인증 퍼즐 하나를 완료하세요.
• 현재 창에 필요한 모든 확장 작업을 완료하십시오.

지원되는 패턴은 두 가지입니다.

진행 상황 기반 차단 요소

잠금이 시작되거나 공유 템플릿이 수락되는 즉시 잠금을 차단해야 하는 경우 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. 백엔드는 앱 범위의 개발자 API 키와 함께 mainToken를 교환/사용합니다.
4. iframe은 백엔드로 응답을 전송합니다.
5. 백엔드에서 결과를 검증합니다.
6. 백엔드는 requirements/progress를 사용하여 신뢰할 수 있는 진행 상황을 기록합니다.
7. 백엔드는 /action를 사용하여 보상 또는 처벌을 적용합니다.
8. 백엔드 패치 metadata.unlockBlockers 및 metadata.homeActions.
9. iframe은 안전한 상태/메타데이터를 읽고 결과를 표시합니다.

이렇게 하면 확장 프로그램 UI가 반응성을 유지하면서 서버에 신뢰할 수 있는 잠금 상태가 유지됩니다.