Trouver les niveaux où les joueurs restent bloqués

Le taux de réussite d'un niveau est la part des tentatives sur ce niveau que les joueurs terminent. Un niveau dont le taux de réussite est bien plus bas que celui des niveaux voisins est l'endroit où les joueurs restent bloqués, et souvent celui où ils arrêtent de jouer.

Pour montrer à quoi cela ressemble, nous avons créé un jeu de puzzle d'exemple avec huit niveaux et 120 joueurs répartis sur deux versions, 1.0.0 et 1.1.0. Dans la version 1.0.0, le Level 5 est bien plus difficile que les niveaux voisins. La version 1.1.0 le rend plus facile.

Étape 1 : choisir un token

Les événements de progression peuvent venir du client du jeu ou d'un serveur de jeu que vous gérez. Utilisez un token serveur si c'est un serveur qui les envoie, ou un token client si c'est le client du jeu. Créez le token dans Paramètres > Jetons API, où vous trouverez aussi l'identifiant de votre compte.

Les exemples ci-dessous utilisent curl avec ces deux valeurs dans des variables d'environnement :

export GAMESTATS_TOKEN=your_api_token
export ACCOUNT_ID=your_account_id

Étape 2 : envoyer un événement au début d'un niveau

Chaque fois qu'un joueur commence un niveau, envoyez un événement « started » à l'endpoint des événements de progression. Chaque début est une tentative : un joueur qui recommence un niveau envoie donc un autre événement « started » :

curl -i -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/progression_events" \
  -H "Authorization: Bearer $GAMESTATS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player_username": "player_3e8",
    "version_name": "1.0.0",
    "progression_type_name": "level",
    "progression_name": "Level 5",
    "progression_milestone_type_name": "started",
    "progression_milestone_name": "started",
    "started_at": "2026-10-02T14:03:10Z",
    "occurred_at": "2026-10-02T14:03:10Z",
    "time_elapsed": 0
  }'

progression_type_name regroupe les progressions à comparer, ici tous les level. progression_name est le niveau lui-même, et c'est le nom affiché dans le rapport. Le rapport compare des types de jalon : utilisez donc les deux mêmes, started et finished, pour chaque niveau ; progression_milestone_name peut reprendre le nom du type. started_at marque le début d'une nouvelle tentative.

Une réponse 201 signifie que l'événement a été accepté. Les joueurs, versions, niveaux et types de jalon sont créés à la première utilisation, il n'y a donc rien à déclarer à l'avance.

Étape 3 : envoyer un événement à la fin d'un niveau

Quand le joueur réussit le niveau, envoyez un événement « finished » pour le même joueur et le même niveau, sans started_at :

curl -i -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/progression_events" \
  -H "Authorization: Bearer $GAMESTATS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player_username": "player_3e8",
    "version_name": "1.0.0",
    "progression_type_name": "level",
    "progression_name": "Level 5",
    "progression_milestone_type_name": "finished",
    "progression_milestone_name": "finished",
    "occurred_at": "2026-10-02T14:05:31Z",
    "time_elapsed": 141
  }'

Game Stats AI rattache l'événement à la tentative la plus récente de ce joueur sur ce niveau. time_elapsed est le temps écoulé depuis le début de la tentative, ici 141 secondes. Utilisez l'unité de votre choix, tant que tous les événements utilisent la même.

N'envoyez rien quand un joueur échoue ou abandonne un niveau. Une tentative sans événement « finished » compte comme non terminée.

Étape 4 : créer un rapport de progression

Dans Rapports > Nouveau rapport, choisissez Rapport de progression, donnez-lui un libellé, puis choisissez level pour Type, started pour De et finished pour À :

Le rapport affiche une ligne par niveau, triée par nom pour que Level 2 vienne avant Level 10, avec trois valeurs :

Étape 5 : trouver le niveau où les joueurs restent bloqués

Choisissez la version 1.0.0 dans les filtres du rapport. Le graphique affiche le taux de réussite de chaque niveau :

Dans le jeu d'exemple, le Level 5 se distingue de trois façons :

• Son taux de réussite est de 17 %, alors que tous les autres niveaux sont entre 55 % et 94 %.
• Il compte 99 tentatives, plus que n'importe quel autre niveau, parce que les joueurs l'ont recommencé.
• Seulement 19 tentatives ont eu lieu sur le Level 6. La plupart des joueurs arrivés au Level 5 ne l'ont jamais dépassé.

Les tentatives terminées ont aussi duré 141 secondes en moyenne, le temps le plus long de tous les niveaux.

Étape 6 : vérifier la correction dans la version suivante

La version 1.1.0 a rendu le Level 5 plus facile. Choisissez 1.1.0 dans les filtres pour ne voir que les tentatives faites dans cette version :

Le taux de réussite du Level 5 est passé de 17 % à 54 %, et les tentatives sur le Level 6 sont passées de 19 à 44 : davantage de joueurs atteignent désormais la suite du jeu.

Chaque tentative appartient à la version de son événement « started ». Sélectionnez plusieurs versions dans les filtres pour les voir combinées.