API voor resultaten van uitdagingen

Whitelabelportalen en andere ondersteunde integraties kunnen met de onderstaande eindpunten een resultaatweergave voor uitdagingen bouwen. Ze gebruiken allemaal de code van de uitdaging en vereisen een geauthenticeerd API-verzoek.

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

Volgorde van eindpunten #

Begin met result-settings/. Gebruik de vlaggen en kolombeschrijvingen om te bepalen welke bedieningselementen en schermen moeten worden weergegeven, in plaats van ervan uit te gaan dat elke uitdaging dezelfde resultaatindeling heeft.

Haal challenger_id-waarden op uit de gepagineerde results/-ranglijst van de uitdaging. Activiteits-ID's staan in de geneste lijst activities.results van het gedetailleerde antwoord.

Resultaatinstellingen #

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

Het antwoord beschrijft de huidige resultaatweergave van de uitdaging:

• primary_column en ordered_by geven de rangschikkingsmaatstaf en standaardvolgorde aan.
• columns en team_columns zijn geordende weergavebeschrijvingen; hun sleutels komen overeen met velden in de ranglijstregels voor deelnemers en teams.
• totals, progress, sections, distances en participant_data bieden optionele context voor de hele uitdaging.
• show_map en show_heatmap vertellen de client welke kaartweergaven moeten worden aangeboden. show_analytics geeft aan of deze aanvrager de fysiologische activiteitsgegevens van een andere deelnemer mag zien; het beperkt niet de eigen bereikbare analyses van de aanvrager.
• results_limited is null voor onbeperkte resultaten. Een getal betekent dat de aanvrager alleen dat aantal bovenste regels kan zien en dat bedieningselementen voor filteren, sorteren en pagineren van resultaten moeten worden verborgen.

Deze waarden zijn afgestemd op de aanvrager. Dezelfde uitdaging kan bijvoorbeeld onbeperkte instellingen teruggeven aan een deelnemer en beperkte instellingen aan een ingelogde gebruiker die niet deelneemt.

Heatmap van trainingen #

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

De heatmap voegt geaccepteerde GPS-activiteiten samen in rastercellen van ongeveer 150 meter. Elke cel is [longitude, latitude, weight], waarbij het gewicht het aantal afzonderlijke activiteiten is dat door die cel liep. Een activiteit draagt maximaal één keer bij aan elke cel en trainingen die in de bronapp als privé zijn gemarkeerd, worden uitgesloten.

Heatmaps worden pas gegenereerd wanneer ze nodig zijn. Als er geen opgeslagen heatmap bestaat, start het eerste verzoek de generatie op de achtergrond en wordt het volgende teruggegeven:

{"status": "pending"}

Vraag de gegevens na enkele seconden opnieuw op. Een gereed antwoord bevat generated_at, cell_size, activity_count, max_weight, truncated en cells. Opgeslagen gegevens kunnen worden weergegeven terwijl een verouderde heatmap op de achtergrond wordt vernieuwd.

Gebruik max_weight om een gewogen dichtheidslaag te normaliseren. Als truncated true is, bevat het antwoord de zwaarst gewogen cellen in plaats van alle gegenereerde cellen.

Het eindpunt geeft 404 terug wanneer de organisator show_heatmap niet heeft ingeschakeld, tijdens een periode met verborgen resultaten of wanneer openbare resultaten beperkt zijn en de aanvrager geen deelnemer is.

Gedetailleerd deelnemersresultaat #

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

Het antwoord combineert:

• De ranglijstregel, gekozen afstand, rang en result_rank_total van de deelnemer.
• statistics zoals afstand, duur, tempo of snelheid, energie, stappen, aantal activiteiten, actieve dagen, langste reeks en gemiddelde hartslag indien beschikbaar.
• is_own_result, dat aangeeft of de regel bij de geauthenticeerde deelnemer hoort.
• head_to_head, dat alleen beschikbaar is wanneer een deelnemer het eigen resultaat bekijkt. Het bevat rang en percentiel, de rangschikkingsmaatstaf, verschillen met nabije concurrenten en de leider, het gemiddelde van alle deelnemers en de podiumregels.
• activities, een geneste gepagineerde lijst van geaccepteerde, zichtbare activiteiten die aan het resultaat zijn toegekend. Elke regel bevat basismetadata van de training, gemiddeld tempo, een routevorm indien beschikbaar en has_analytics.

Voor een resultaat met een vaste afstand stopt de activiteitenlijst bij de activiteit waarmee de gekozen afstand is voltooid. Latere activiteiten worden niet weergegeven omdat ze niet aan dat resultaat hebben bijgedragen.

Paginering van geneste activiteiten #

De activiteitenlijst heeft de gebruikelijke velden count, next, previous en results, maar gebruikt eigen queryparameters zodat deze niet conflicteren met paginering op het hoogste niveau:

Locatievrije routevormen #

Routes in de activiteitstijdlijn zijn geen geografische coördinaten. De server verschuift en schaalt elke GPS-route naar een vaste SVG-coördinatenruimte van 158 × 108 en geeft alleen het volgende terug:

• path — SVG-padgegevens
• start en end — punten in de genormaliseerde coördinatenruimte
• point_count — aantal punten in de teruggegeven vorm

Absolute breedtegraad, lengtegraad, begrenzingen en middelpunt zijn niet opgenomen. Dezelfde route die naar een andere locatie wordt verplaatst, levert dezelfde vorm op. De vorm is daarom geschikt als miniatuur, maar kan niet op een geografische kaart worden getekend.

Analyse per activiteit #

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

De activiteit moet geaccepteerd en zichtbaar zijn en aan precies dit deelnemersresultaat zijn gekoppeld. Het antwoord bevat basisgegevens over afstand, duur, tempo en snelheid, plus alle analyses die uit de opgeslagen gegevensstromen kunnen worden afgeleid:

Elk blok kan afzonderlijk null zijn omdat providers en apparaten verschillende gegevensstromen leveren. has_streams geeft aan of bruikbare stroomanalyses beschikbaar zijn. x_kind geeft aan of de x-waarden van grafieken de cumulatieve afstand of verstreken tijd vertegenwoordigen.

Blokken met een lage gevoeligheid — routevorm, tussentijden, tempo en hoogte — zijn beschikbaar voor elke aanvrager die toegang heeft tot het resultaat. Fysiologische blokken — hartslag, zones, cadans en inspanning — zijn altijd beschikbaar voor het eigen bereikbare resultaat van de aanvrager. Voor de activiteit van een andere deelnemer worden ze alleen teruggegeven als de organisator show_analytics heeft ingeschakeld en de aanvrager aan de zichtbaarheidsregels voor resultaten voldoet. Anders zijn die blokken null en is physio_restricted true.

Zichtbaarheids- en privacyregels #

Deelnemers aan de uitdaging behouden buiten een periode met verborgen resultaten toegang tot alle resultaten. De toegang van organisatiemedewerkers kan verschillen van die van deelnemers, maar clients moeten altijd de aanvragerspecifieke waarden volgen die door result-settings/ worden teruggegeven.

Gerelateerd #

• Overzicht van de openbare API
• Whitelabel en bedrijfsinstellingen