Características de la API de extensión

Utilice esta página cuando ya comprenda el modelo básico de extensión y desee crear un comportamiento de bloqueo real: acciones requeridas, bloqueadores de desbloqueo, regularidad, recompensas y castigos.

precaución

El código iframe del navegador no es de confianza.

Tu iframe puede renderizar la interfaz de usuario y leer el contexto de sesión seguro. Todo aquello que escriba el estado de la sesión, recompense al usuario, reste tiempo, elimine un bloqueador de desbloqueo, registre el progreso de los requisitos de confianza, inicie o falle un temporizador de intento o aplique un castigo debe ser verificado por tu backend.

Mapa de características

Característica	Qué hace	Dónde se ejecuta
Desbloquear bloqueadores	Impedir el desbloqueo hasta que su extensión elimine un bloqueador o registre suficiente progreso confiable	Configuración de inicio de bloqueo o llamadas de metadatos/progreso del backend
Acciones de inicio	Agrega una acción visible en la página de bloqueo, como "Jugar desafío"	Configuración de inicio de bloqueo o parches de metadatos de backend
Acciones regulares	Permite un número limitado de acciones del usuario por intervalo	Chastify realiza un seguimiento de los contadores; su backend envía acciones de confianza
Progreso requerido	Realiza un seguimiento de los requisitos de finalización diarios o semanales	Su sistema backend registra el progreso; el programador Chastify comprueba las ventanas perdidas
Recompensas	Elimina el tiempo, inicia la apertura de higiene o envía una notificación después de un éxito verificado	Su backend llama a puntos finales privilegiados
Castigos	Añade tiempo, congela, asigna una tarea, inicia la picota o envía una notificación después de un fallo verificado	Su backend llama a puntos finales privilegiados

Encabezados de backend requeridos

Los puntos finales de extensión privilegiados requieren ambos encabezados:

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

El código mainToken identifica la sesión de extensión abierta. La clave de API para desarrolladores demuestra que la solicitud proviene de su servidor.

Desbloquear bloqueadores

Utilice bloqueadores de desbloqueo cuando el usuario deba terminar algo antes de desbloquear. Ejemplos:

Gana 3 partidos.
Completa la prueba del entrenamiento de hoy.
Completa un rompecabezas de verificación.
Complete todas las acciones de extensión necesarias para la ventana actual.

Existen dos patrones compatibles.

Bloqueadores basados en el progreso

Utilice initialMetadata.unlockRequirements cuando el bloqueo deba bloquearse tan pronto como se inicie o se acepte una plantilla compartida. Chastify inicializa el estado de la sesión de la extensión a partir de esta configuración genérica, de modo que el bloqueador exista incluso antes de que el usuario abra la extensión por primera vez.

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

Una vez que su sistema backend verifique una finalización confiable, registre el progreso para la misma métrica:

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 almacena esto como progreso de desbloqueo y automáticamente considera que el requisito se cumple cuando el progreso alcanza requiredCount. Las tarjetas de bloqueo pueden mostrar un progreso como 1 of 3 complete.

Utilice nombres de métricas estables. Cada métrica representa un requisito de desbloqueo activo para esa sesión de extensión.

Límites de tiempo para los intentos

Utilice attemptLimit cuando un intento de confianza deba caducar si no se completa a tiempo. Chastify almacena el intento activo bajo data.attemptLimits.<metric> y puede marcarlo como fallido después de la fecha límite. Este estado es administrado por Chastify; inicie y falle los intentos a través de los puntos finales de intento en lugar de escribir data.attemptLimits usted mismo.

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

startPolicy puede ser activity cuando la cuenta regresiva comienza cuando el portador comienza a jugar, o availability cuando la cuenta regresiva comienza tan pronto como la acción está disponible para el bloqueo.

Inicie un intento desde su backend:

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

Cuando tu sistema backend compruebe el intento, pídele a Chastify que lo haga fallar si ha pasado el plazo:

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

Si los intentos fallidos deben consumir un espacio de tiempo de reutilización, también se debe enviar una acción regular para el intento fallido.

Bloqueadores manuales

Utilice unlockBlockers cuando su sistema backend necesite decidir manualmente si el desbloqueo está bloqueado. Parchee los metadatos de su sistema backend:

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

Elimine el bloqueador una vez que su sistema backend verifique la finalización:

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

nota

unlockBlockers son metadatos manuales. Indican a Chastify que el desbloqueo está bloqueado hasta que el sistema de backend elimine el bloqueador. initialMetadata.unlockRequirements son metadatos basados en el progreso. Chastify puede evaluarlos automáticamente a partir del progreso registrado para la métrica correspondiente.

Característica de regularidad

Las acciones regulares son útiles cuando se permite al usuario realizar alguna actividad con una frecuencia fija: una vez por hora, cuatro veces al día, una vez por semana, etc.

Puedes configurar acciones regulares cuando se crea la extensión de bloqueo, o actualizar la sesión en ejecución desde tu backend:

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

Modos:

unlimited: las acciones siempre están disponibles.
non_cumulative: una ventana estará disponible a la vez; las acciones no utilizadas no se acumulan.
cumulative: las acciones se acumulan hasta maxActions.

Consulte la disponibilidad actual:

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

Enviar una acción periódica de confianza:

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

Utilice acciones regulares cuando la regla principal sea "¿con qué frecuencia puede ocurrir esta acción?".

Acciones personalizadas requeridas

Utilice el progreso requerido cuando la regla principal sea "¿cuántas finalizaciones se requieren por día o semana?".

La configuración de requisitos reside en la configuración de sesión de la extensión instalada bajo 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"
    }
  }
}

Unidades de cadencia compatibles:

day
week

Tipos de penalización por ventana perdida admitidos:

none
add_time
freeze
pillory

Registra el progreso de forma fiable solo después de que tu sistema backend verifique la acción:

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

El planificador de Chastify evalúa las ventanas completadas y aplica la penalización por ventana perdida configurada si el recuento de ventanas completadas es inferior a requiredCount.

tip

Utilice ambas funciones conjuntamente cuando sea necesario:

regular-actions limita la frecuencia con la que un usuario puede enviar mensajes.
El código requirements/progress registra si se produjeron suficientes finalizaciones verificadas durante el día o la semana.
Los bloques metadata.unlockBlockers se desbloquean hasta que se cumpla el requisito actual.

Recompensas

Las recompensas son acciones de bloqueo privilegiadas. Llámalas desde tu sistema backend después de que se haya verificado el éxito.

Eliminar tiempo:

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

Inicie una apertura higiénica:

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

Enviar una notificación personalizada:

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

castigos

Las sanciones también son acciones de bloqueo privilegiadas. Aplícalas solo después de que tu sistema backend verifique un fallo o un requisito incumplido.

Agregar tiempo:

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

Congelar:

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

Asignar una tarea:

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

Comienza la picota:

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

Patrón recomendado

Para juegos, rutinas y desafíos de verificación:

El iframe se abre y lee el hash de lanzamiento.
El iframe le pide a su backend que cree un desafío usando mainToken.
El backend intercambia/utiliza mainToken con su clave API de desarrollador con ámbito de aplicación.
El iframe envía las respuestas a tu servidor.
El sistema backend verifica el resultado.
El sistema backend registra el progreso de forma fiable con requirements/progress.
El sistema backend aplica la recompensa o el castigo con /action.
Parches de backend metadata.unlockBlockers y metadata.homeActions.
El iframe lee el estado/metadatos seguros y muestra el resultado.

Esto mantiene la interfaz de usuario de la extensión receptiva al tiempo que conserva el estado de bloqueo de confianza en el servidor.

Mapa de características​

Encabezados de backend requeridos​

Desbloquear bloqueadores​

Bloqueadores basados ​​en el progreso​

Límites de tiempo para los intentos​

Bloqueadores manuales​

Característica de regularidad​

Acciones personalizadas requeridas​

Recompensas​

castigos​

Patrón recomendado​