API des résultats de challenge

Les portails en marque blanche et les autres intégrations prises en charge peuvent créer une expérience de résultats de challenge avec les points de terminaison ci-dessous. Ils utilisent tous le code du challenge et nécessitent une requête API authentifiée.

/api/v1/gamification/challenge/{code}/

Séquence des points de terminaison #

Commencez par result-settings/. Utilisez ses indicateurs et descripteurs de colonnes pour décider quels contrôles et écrans afficher, plutôt que de supposer que tous les challenges ont le même format de résultats.

Récupérez les valeurs challenger_id dans le classement paginé results/ du challenge. Les identifiants d'activité proviennent de la liste imbriquée activities.results de la réponse détaillée.

Paramètres des résultats #

GET /api/v1/gamification/challenge/{code}/result-settings/

La réponse décrit la présentation actuelle des résultats du challenge :

• primary_column et ordered_by indiquent la mesure du classement et l'ordre par défaut.
• columns et team_columns sont des descripteurs d'affichage ordonnés ; leurs clés correspondent aux champs des lignes des classements des participants et des équipes.
• totals, progress, sections, distances et participant_data fournissent un contexte facultatif à l'échelle du challenge.
• show_map et show_heatmap indiquent au client les vues cartographiques à proposer. show_analytics indique si cet appelant peut voir les données physiologiques des activités d'un autre participant ; il ne limite pas les analyses accessibles de l'appelant lui-même.
• results_limited vaut null lorsque les résultats ne sont pas limités. Un nombre signifie que l'appelant ne peut voir que ce nombre de premières lignes ; les commandes de filtrage, de tri et de pagination des résultats doivent alors être masquées.

Ces valeurs dépendent de l'appelant. Le même challenge peut, par exemple, renvoyer des paramètres sans restriction à un participant et des paramètres limités à une personne connectée qui ne participe pas.

Carte thermique des entraînements #

GET /api/v1/gamification/challenge/{code}/heatmap/

La carte thermique regroupe les activités GPS acceptées dans des cellules d'environ 150 mètres. Chaque cellule a la forme [longitude, latitude, weight], où weight est le nombre d'activités distinctes qui l'ont traversée. Une activité ne contribue qu'une seule fois à chaque cellule, et les entraînements marqués comme privés dans leur application source sont exclus.

Les cartes thermiques sont générées à la demande. Lorsqu'aucune carte n'est enregistrée, la première requête lance sa génération en arrière-plan et renvoie :

{"status": "pending"}

Interrogez de nouveau le point de terminaison après quelques secondes. Une réponse prête contient generated_at, cell_size, activity_count, max_weight, truncated et cells. Les données enregistrées peuvent être fournies pendant qu'une carte thermique obsolète est actualisée en arrière-plan.

Utilisez max_weight pour normaliser une couche de densité pondérée. Si truncated vaut true, la réponse contient les cellules de poids le plus élevé plutôt que toutes les cellules générées.

Le point de terminaison renvoie 404 lorsque l'organisateur n'a pas activé show_heatmap, pendant une période de masquage des résultats, ou lorsque les résultats publics sont restreints et que l'appelant ne participe pas.

Résultat détaillé d'un participant #

GET /api/v1/gamification/challenge/{code}/results/{challenger_id}/detailed/

La réponse réunit :

• La ligne de classement du participant, la distance choisie, le rang et result_rank_total.
• Des statistics telles que la distance, la durée, l'allure ou la vitesse, l'énergie, les pas, le nombre d'activités, les jours actifs, la plus longue série et la fréquence cardiaque moyenne lorsqu'elle est disponible.
• is_own_result, qui indique si la ligne appartient au participant authentifié.
• head_to_head, disponible uniquement lorsqu'un participant consulte son propre résultat. Il comprend son rang et son percentile, la mesure du classement, les écarts avec les concurrents proches et le leader, la moyenne des participants et les lignes du podium.
• activities, une liste imbriquée et paginée des activités acceptées et visibles créditées au résultat. Chaque ligne comprend les métadonnées principales de l'entraînement, l'allure moyenne, une forme de parcours lorsqu'elle est disponible et has_analytics.

Pour un résultat à distance fixe, la liste des activités s'arrête à l'activité qui a permis d'atteindre la distance choisie. Les activités ultérieures n'apparaissent pas, car elles n'ont pas contribué à ce résultat.

Pagination imbriquée des activités #

La liste des activités comporte les champs habituels count, next, previous et results, mais utilise des paramètres de requête dédiés pour ne pas entrer en conflit avec la pagination de premier niveau :

Formes de parcours sans localisation #

Les parcours de la chronologie des activités ne sont pas des coordonnées géographiques. Le serveur translate et met à l'échelle chaque trace GPS dans un espace de coordonnées SVG fixe de 158 × 108 et renvoie uniquement :

• path — données du tracé SVG
• start et end — points dans l'espace de coordonnées normalisé
• point_count — nombre de points dans la forme renvoyée

La latitude, la longitude, les limites et le centre absolus ne sont pas inclus. Un même parcours déplacé à un autre endroit produit la même forme : elle convient donc à une miniature, mais ne peut pas être placée sur une carte géographique.

Analyses par activité #

GET /api/v1/gamification/challenge/{code}/results/{challenger_id}/activities/{activity_id}/analytics/

L'activité doit être acceptée, visible et rattachée exactement au résultat de ce participant. La réponse contient la distance, la durée, l'allure et la vitesse principales, ainsi que les analyses pouvant être dérivées des flux enregistrés :

Chaque bloc peut indépendamment être nul, car les fournisseurs et les appareils transmettent des flux différents. has_streams indique si des analyses de flux exploitables sont disponibles. x_kind précise si les valeurs x des graphiques représentent la distance cumulée ou le temps écoulé.

Les blocs peu sensibles — forme du parcours, temps intermédiaires, allure et altitude — sont accessibles à tout appelant autorisé à consulter le résultat. Les blocs physiologiques — fréquence cardiaque, zones, cadence et effort — sont toujours disponibles pour le propre résultat accessible de l'appelant. Pour l'activité d'un autre participant, ils ne sont renvoyés que si l'organisateur a activé show_analytics et si l'appelant respecte les règles de visibilité des résultats. Dans le cas contraire, ces blocs valent null et physio_restricted vaut true.

Règles de visibilité et de confidentialité #

Les participants au challenge conservent l'accès à l'intégralité des résultats en dehors d'une période de masquage. L'accès du personnel de l'organisation peut différer de celui des participants, mais les clients doivent toujours suivre les valeurs propres à l'appelant renvoyées par result-settings/.

Articles connexes #

• Aperçu de l'API publique
• Configuration en marque blanche et pour les entreprises