Fonctionnalités de l'API d'extension

Utilisez cette page lorsque vous comprenez déjà le modèle d'extension de base et que vous souhaitez créer un comportement de verrouillage réel : actions requises, bloqueurs de déverrouillage, régularité, récompenses et sanctions.

attention

Le code iframe du navigateur n'est pas fiable.

Votre iframe peut afficher l'interface utilisateur et lire le contexte de session sécurisé. Toute action modifiant l'état de la session, récompensant l'utilisateur, supprimant du temps, levant un blocage de déverrouillage, enregistrant la progression des exigences de confiance, démarrant ou annulant un compte à rebours, ou appliquant une sanction doit être vérifiée par votre serveur.

Carte des fonctionnalités

Fonctionnalité	Description	Plateforme d'exécution
Déverrouiller les éléments bloquants	Empêcher le déverrouillage tant que votre extension n'a pas levé un obstacle ou enregistré une progression fiable suffisante	Verrouiller la configuration de démarrage ou les appels de métadonnées/progression du backend
Actions sur la page d'accueil	Ajoute une action visible sur la page de verrouillage, telle que « Relever le défi »	Configuration de démarrage du verrouillage ou correctifs de métadonnées du backend
Actions régulières	Autorise un nombre limité d'actions par intervalle	Chastify effectue un suivi des compteurs ; votre serveur soumet des actions de confiance
Progression requise	Suivi des exigences de réalisation quotidiennes ou hebdomadaires	Votre système enregistre la progression ; le planificateur Chastify vérifie les fenêtres manquées
Récompenses	Supprime le temps, lance l'ouverture hygiénique ou envoie une notification après vérification du succès	Votre backend appelle des points de terminaison privilégiés
Sanctions	Ajoute du temps, bloque, assigne une tâche, met au pilori ou envoie une notification après un échec vérifié	Votre backend appelle des points de terminaison privilégiés

En-têtes backend requis

Les points de terminaison d'extension privilégiés nécessitent les deux en-têtes :

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

Le code mainToken identifie la session d'extension ouverte. La clé API développeur prouve que la requête provient de votre serveur.

Débloquer les bloqueurs

Utilisez des dispositifs de déverrouillage lorsque la personne qui les porte doit terminer une action avant de pouvoir les déverrouiller. Exemples :

• Gagner 3 matchs.
• Preuve de l'entraînement d'aujourd'hui complétée.
• Terminez un puzzle de vérification.
• Effectuez toutes les actions d'extension requises pour la fenêtre actuelle.

Deux modèles sont pris en charge.

Bloqueurs basés sur le progrès

Utilisez initialMetadata.unlockRequirements lorsque le verrouillage doit être bloqué dès son démarrage ou dès qu'un modèle partagé est accepté. Chastify initialise l'état de la session de l'extension à partir de cette configuration générique ; le blocage est donc actif avant même que l'utilisateur n'ouvre votre extension pour la première fois.

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

Une fois que votre système dorsal a vérifié la bonne exécution de la tâche, enregistrez la progression pour la même métrique :

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 enregistre cette progression de déverrouillage et considère automatiquement la condition comme remplie lorsque la progression atteint requiredCount. Les cartes de verrouillage peuvent afficher une progression telle que 1 of 3 complete.

Utilisez des noms de métriques stables. Une métrique représente une exigence de déverrouillage active pour cette session d'extension.

Limites de temps de tentative

Utilisez attemptLimit lorsqu'une tentative de confiance doit expirer si elle n'est pas terminée à temps. Chastify stocke la tentative active sous data.attemptLimits.<metric> et peut la marquer comme ayant échoué après l'échéance. Cet état est géré par Chastify ; lancez et faites échouer les tentatives via les points de terminaison de tentative au lieu d'écrire vous-même data.attemptLimits.

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

startPolicy peut être activity lorsque le compte à rebours commence au moment où le porteur commence à jouer, ou availability lorsque le compte à rebours commence dès que l'action est disponible pour le verrou.

Lancez une tentative depuis votre serveur :

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

Lorsque votre serveur vérifie la tentative, demandez à Chastify de la faire échouer si le délai est dépassé :

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 les tentatives infructueuses doivent consommer un emplacement de temps de recharge, soumettez également une action normale pour la tentative infructueuse.

bloqueurs manuels

Utilisez unlockBlockers lorsque votre serveur doit décider manuellement si le déverrouillage est bloqué. Modifiez les métadonnées depuis votre serveur :

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

Levez le blocage une fois que votre serveur a vérifié la fin de l'opération :

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

remarque

unlockBlockers correspond à des métadonnées manuelles. Elles indiquent à Chastify que le déverrouillage est bloqué jusqu'à ce que votre système dorsal supprime le blocage. initialMetadata.unlockRequirements correspond à des métadonnées basées sur la progression. Chastify peut les évaluer automatiquement à partir de la progression fiable enregistrée pour la métrique correspondante.

Fonction de régularité

Les actions régulières sont utiles lorsque l'utilisateur est autorisé à faire quelque chose à une cadence fixe : une fois par heure, quatre fois par jour, une soumission par semaine, etc.

Vous pouvez configurer des actions régulières lors de la création de l'extension de verrouillage, ou mettre à jour la session en cours depuis votre 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
  }'

Modes :

• unlimited : des actions sont toujours disponibles.
• non_cumulative : une seule fenêtre devient disponible à la fois ; les actions non utilisées ne s’empilent pas.
• cumulative : les actions s’accumulent jusqu’à maxActions.

Consultez la disponibilité actuelle :

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

Soumettez une action régulière fiable :

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

Utilisez des actions régulières lorsque la règle principale est « à quelle fréquence cette action peut-elle se produire ? ».

Actions personnalisées requises

Utilisez la notion de progression requise lorsque la règle principale est « combien de tâches doivent être effectuées par jour ou par semaine ? ».

Le fichier de configuration requis se trouve dans la configuration de session de l'extension installée sous 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"
    }
  }
}

Unités de cadence prises en charge :

• day
• week

Types de sanctions prises en charge en cas de fenêtre manquée :

• none
• add_time
• freeze
• pillory

N’enregistrez les progrès fiables qu’après que votre système dorsal a vérifié l’action :

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

Le planificateur de Chastify évalue les fenêtres terminées et applique la punition de fenêtre manquée configurée si le nombre de fenêtres terminées est inférieur à requiredCount.

astuce

Utilisez les deux fonctionnalités ensemble lorsque cela est nécessaire :

• regular-actions limite la fréquence à laquelle un utilisateur peut soumettre des données.
• requirements/progress enregistre si suffisamment de complétions vérifiées ont eu lieu pour la journée ou la semaine.
• Le code metadata.unlockBlockers bloque le déverrouillage jusqu'à ce que la condition requise soit satisfaite.

Récompenses

Les récompenses sont des actions de verrouillage privilégiées. Appelez-les depuis votre backend après une réussite vérifiée.

Supprimer l'heure :

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

Commencez par une ouverture hygiénique :

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

Envoyer une notification personnalisée :

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

Les sanctions

Les sanctions sont également des actions de verrouillage privilégiées. Appliquez-les uniquement après que votre système dorsal a vérifié une défaillance ou un manquement à une exigence.

Ajouter du temps :

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

Geler:

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

Attribuer une tâche :

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

Début du pilori :

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

Modèle recommandé

Pour les jeux, les routines et les défis de vérification :

1. L'iframe s'ouvre et lit le hachage de lancement.
2. L'iframe demande à votre serveur de créer un défi utilisant mainToken.
3. Le backend échange/utilise mainToken avec sa clé API développeur à portée d'application.
4. L'iframe envoie les réponses à votre serveur.
5. Le système dorsal vérifie le résultat.
6. Le système dorsal enregistre les progrès de manière fiable avec requirements/progress.
7. Le backend applique la récompense ou la punition avec /action.
8. Correctifs du backend metadata.unlockBlockers et metadata.homeActions.
9. L'iframe lit l'état/les métadonnées sécurisés et affiche le résultat.

Cela permet de conserver une interface utilisateur réactive pour l'extension tout en maintenant un état de verrouillage fiable sur le serveur.