Funcionalidades da API de extensão

Use esta página quando você já entender o modelo básico de extensão e quiser construir o comportamento real do bloqueio: ações necessárias, bloqueadores de desbloqueio, regularidade, recompensas e punições.

cuidado

O código iframe do navegador não é confiável.

Seu iframe pode renderizar a interface do usuário e ler o contexto seguro da sessão. Qualquer ação que grave o estado da sessão, recompense o usuário, remova tempo, remova um bloqueador de desbloqueio, registre o progresso de requisitos confiáveis, inicie ou interrompa um cronômetro de tentativas ou aplique uma punição deve ser verificada pelo seu servidor.

Mapa de recursos

Funcionalidade	O que faz	Onde funciona
Desbloquear bloqueadores	Impedir o desbloqueio até que sua extensão remova um bloqueador ou registre progresso suficiente e confiável	Chamadas de configuração de bloqueio de inicialização ou metadados/progresso do backend
Ações da página inicial	Adiciona uma ação visível na página de bloqueio, como "Jogar desafio"	Correções de configuração de inicialização do bloqueio ou metadados de backend
Ações regulares	Permite um número limitado de ações do usuário por intervalo	Chastify monitora contadores; seu backend envia ações confiáveis
Progresso necessário	Monitora os requisitos de conclusão diários ou semanais	Seu sistema registra o progresso; o agendador Chastify verifica as janelas perdidas
Recompensas	Remove tempo, inicia a abertura de higienização ou envia notificação após sucesso verificado	Seu backend chama endpoints privilegiados
Punições	Adiciona tempo, congela, atribui uma tarefa, inicia o pelourinho ou envia notificação após falha verificada	Seu backend chama endpoints privilegiados

Cabeçalhos de backend obrigatórios

Os endpoints de extensão privilegiados exigem ambos os cabeçalhos:

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

O código mainToken identifica a sessão de extensão aberta. A chave da API do desenvolvedor comprova que a solicitação veio do seu backend.

Desbloquear bloqueadores

Use bloqueadores de desbloqueio quando o usuário precisar concluir alguma ação antes de desbloquear. Exemplos:

Ganhe 3 jogos.
Comprove o treino de hoje.
Conclua um quebra-cabeça de verificação.
Conclua todas as ações de extensão necessárias para a janela atual.

Existem dois padrões suportados.

Bloqueadores baseados em progresso

Use initialMetadata.unlockRequirements quando a fechadura precisar ser bloqueada assim que for iniciada ou quando um modelo compartilhado for aceito. Chastify inicializa o estado da sessão da extensão a partir dessa configuração genérica, portanto o bloqueador já existe mesmo antes de o usuário abrir a extensão pela primeira 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"
      }
    ]
  }
}

Após o seu sistema verificar a conclusão confiável, registre o progresso para a mesma 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 armazena isso como progresso de desbloqueio e considera automaticamente o requisito como satisfeito quando o progresso atinge requiredCount. Os cartões de bloqueio podem mostrar o progresso, como 1 of 3 complete.

Use nomes de métricas estáveis. Uma métrica representa um requisito de desbloqueio ativo para essa sessão de extensão.

Limites de tempo de tentativa

Use attemptLimit quando uma tentativa confiável precisar expirar caso não seja concluída a tempo. Chastify armazena a tentativa ativa em data.attemptLimits.<metric> e pode marcá-la como falha após o prazo. Esse estado é gerenciado por Chastify; inicie e interrompa tentativas por meio dos endpoints de tentativa, em vez de escrever data.attemptLimits manualmente.

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

startPolicy pode se tornar activity quando a contagem regressiva começa assim que o usuário inicia a reprodução, ou availability quando a contagem regressiva começa assim que a ação estiver disponível para a fechadura.

Inicie uma tentativa a partir do seu 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"
  }'

Quando o seu servidor verificar a tentativa, peça ao Chastify para rejeitá-la caso o prazo tenha expirado:

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

Se tentativas falhas consumirem um espaço de recarga, submeta também uma ação normal para a tentativa falha.

Bloqueadores manuais

Use unlockBlockers quando seu backend precisar decidir manualmente se o desbloqueio está bloqueado. Aplique o patch nos metadados do seu 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."
        }
      }
    ]
  }'

Remova o bloqueador após o seu servidor verificar a conclusão:

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

observação

unlockBlockers são metadados manuais. Eles informam a Chastify que o desbloqueio está bloqueado até que seu backend remova o bloqueador. initialMetadata.unlockRequirements são metadados baseados em progresso. Chastify pode avaliá-los automaticamente a partir do progresso confiável registrado para a métrica correspondente.

Recurso de regularidade

Ações regulares são úteis quando o usuário pode realizar algo em uma frequência fixa: uma vez por hora, quatro vezes por dia, uma vez por semana, e assim por diante.

Você pode configurar ações regulares quando a extensão de bloqueio for criada ou atualizar a sessão em execução a partir do seu painel administrativo:

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: as ações estão sempre disponíveis.
non_cumulative: apenas uma janela fica disponível por vez; ações não utilizadas não se acumulam.
cumulative: as ações acumulam até maxActions.

Verifique a disponibilidade atual:

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

Enviar uma ação regular confiável:

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

Utilize ações regulares quando a regra principal for "com que frequência essa ação pode ocorrer?".

Ações personalizadas obrigatórias

Use o progresso necessário quando a regra principal for "quantas conclusões são necessárias por dia ou por semana?".

A configuração de requisitos reside no arquivo de configuração da sessão da extensão instalada, em 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 cadência suportadas:

day
week

Tipos de punição suportados para janelas de tempo perdidas:

none
add_time
freeze
pillory

Registre o progresso de forma confiável somente após o seu servidor verificar a ação:

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

O agendador de Chastify avalia as janelas concluídas e aplica a penalidade configurada para janelas perdidas se a contagem de janelas concluídas for inferior a requiredCount.

dica

Utilize ambas as funcionalidades em conjunto quando necessário:

regular-actions limita a frequência com que um usuário pode enviar mensagens.
O código requirements/progress registra se houve conclusões verificadas suficientes no dia ou na semana.
O código metadata.unlockBlockers bloqueia o desbloqueio até que o requisito atual seja atendido.

Recompensas

As recompensas são ações de bloqueio privilegiadas. Chame-as do seu painel administrativo após uma verificação bem-sucedida.

Remover tempo:

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

Comece com uma abertura 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 uma notificação 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"
  }'

Punições

As punições também são ações de bloqueio privilegiadas. Aplique-as somente depois que seu backend verificar uma falha ou um requisito não atendido.

Adicionar tempo:

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

Atribua uma tarefa:

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

Iniciar o pelourinho:

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

Padrão recomendado

Para jogos, rotinas e desafios de verificação:

O iframe é aberto e lê o hash de inicialização.
O iframe solicita ao seu backend que crie um desafio usando o código mainToken.
O backend troca/usa mainToken com sua chave de API de desenvolvedor com escopo de aplicativo.
O iframe envia as respostas para o seu servidor.
O sistema verifica o resultado.
O sistema de backend registra o progresso de forma confiável com requirements/progress.
O sistema aplica recompensas ou punições com o código /action.
Correções de backend metadata.unlockBlockers e metadata.homeActions.
O iframe lê o estado/metadados seguros e exibe o resultado.

Isso mantém a interface do usuário da extensão responsiva, ao mesmo tempo que preserva o estado de bloqueio confiável no servidor.

Mapa de recursos​

Cabeçalhos de backend obrigatórios​

Desbloquear bloqueadores​

Bloqueadores baseados em progresso​

Limites de tempo de tentativa​

Bloqueadores manuais​

Recurso de regularidade​

Ações personalizadas obrigatórias​

Recompensas​

Punições​

Padrão recomendado​