API for utfordringsresultater

Whitelabel-portaler og andre støttede integrasjoner kan bygge en resultatopplevelse for utfordringer med endepunktene nedenfor. Alle bruker utfordringskoden og krever en autentisert API-forespørsel.

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

Endepunktrekkefølge #

Begynn med result-settings/. Bruk flaggene og kolonnebeskrivelsene derfra til å avgjøre hvilke kontroller og visninger som skal gjengis, i stedet for å anta at alle utfordringer har samme resultatform.

Hent challenger_id-verdier fra den sideinndelte results/-resultatlisten for utfordringen. Aktivitets-ID-er finnes i den nestede listen activities.results i det detaljerte svaret.

Resultatinnstillinger #

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

Svaret beskriver den gjeldende resultatvisningen for utfordringen:

• primary_column og ordered_by angir rangeringsmålet og standardrekkefølgen.
• columns og team_columns er ordnede visningsbeskrivelser. Nøklene deres tilsvarer feltene i resultatlisteradene for deltakere og lag.
• totals, progress, sections, distances og participant_data gir valgfri kontekst for hele utfordringen.
• show_map og show_heatmap forteller klienten hvilke kartvisninger som kan tilbys. show_analytics angir om den som sender forespørselen, kan se fysiologiske aktivitetsdata for en annen deltaker. Det begrenser ikke tilgjengelig analyse av forespørselsavsenderens eget resultat.
• results_limited er null for ubegrensede resultater. Et tall betyr at forespørselsavsenderen bare kan se så mange topprader, og at kontroller for filtrering, sortering og sideinndeling av resultater skal skjules.

Disse verdiene er tilpasset den som sender forespørselen. Den samme utfordringen kan for eksempel returnere ubegrensede innstillinger til en deltaker og begrensede innstillinger til en innlogget bruker som ikke deltar.

Varmekart for treningsøkter #

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

Varmekartet samler godkjente GPS-aktiviteter i rutenettceller på omtrent 150 meter. Hver celle er [longitude, latitude, weight], der vekten er antallet unike aktiviteter som har passert gjennom den. En aktivitet bidrar høyst én gang i hver celle, og treningsøkter som er merket som private i kildeappen, utelates.

Varmekart genereres ved behov. Når det ikke finnes et lagret varmekart, starter den første forespørselen generering i bakgrunnen og returnerer:

{"status": "pending"}

Spør etter dataene på nytt etter noen sekunder. Et ferdig svar inneholder generated_at, cell_size, activity_count, max_weight, truncated og cells. Lagrede data kan vises mens et utdatert varmekart oppdateres i bakgrunnen.

Bruk max_weight til å normalisere et vektet tetthetslag. Hvis truncated er true, inneholder svaret de tetteste cellene i stedet for alle genererte celler.

Endepunktet returnerer 404 når arrangøren ikke har aktivert show_heatmap, i et tidsrom med skjulte resultater eller når offentlige resultater er begrenset og forespørselsavsenderen ikke er deltaker.

Detaljert deltakerresultat #

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

Svaret kombinerer:

• Deltakerens resultatlisterad, valgte distanse, plassering og result_rank_total.
• statistics, for eksempel distanse, varighet, tempo eller hastighet, energi, skritt, antall aktiviteter, aktive dager, lengste sammenhengende rekke og gjennomsnittspuls når det er tilgjengelig.
• is_own_result, som angir om raden tilhører den autentiserte deltakeren.
• head_to_head, som bare er tilgjengelig når en deltaker ser sitt eget resultat. Det omfatter plassering og persentil, rangeringsmålet, avstanden til nærmeste konkurrenter og lederen, gjennomsnittet for alle deltakere og pallplasseringene.
• activities, en nestet sideinndelt liste over godkjente og synlige aktiviteter som er godskrevet resultatet. Hver rad inneholder grunnleggende metadata for treningsøkten, gjennomsnittstempo, en ruteform når den er tilgjengelig, og has_analytics.

For et resultat med fast distanse stopper aktivitetslisten ved aktiviteten som fullførte den valgte distansen. Senere aktiviteter vises ikke fordi de ikke bidro til resultatet.

Sideinndeling av nestede aktiviteter #

Aktivitetslisten har de vanlige feltene count, next, previous og results, men bruker egne spørringsparametere for å unngå konflikt med sideinndelingen på øverste nivå:

Stedsuavhengige ruteformer #

Rutene i aktivitetstidslinjen er ikke geografiske koordinater. Serveren forskyver og skalerer hvert GPS-spor til et fast SVG-koordinatrom på 158 × 108 og returnerer bare:

• path — SVG-banedata
• start og end — punkter i det normaliserte koordinatrommet
• point_count — antall punkter i den returnerte formen

Absolutt breddegrad, lengdegrad, avgrensning og sentrum er ikke inkludert. Den samme ruten flyttet til et annet sted gir samme form. Den egner seg derfor som miniatyrbilde, men kan ikke tegnes på et geografisk kart.

Analyse per aktivitet #

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

Aktiviteten må være godkjent, synlig og knyttet til akkurat dette deltakerresultatet. Svaret inneholder grunnleggende distanse, varighet, tempo og hastighet, i tillegg til analyse som kan utledes fra lagrede datastrømmer:

Hver blokk kan være null uavhengig av de andre, fordi leverandører og enheter sender ulike datastrømmer. has_streams angir om brukbar strømanalyse finnes. x_kind angir om x-verdiene i diagrammer representerer akkumulert distanse eller medgått tid.

Blokker med lav sensitivitet — ruteform, mellomtider, tempo og høyde — er tilgjengelige for alle som har tilgang til resultatet. Fysiologiske blokker — puls, pulssoner, kadens og anstrengelse — er alltid tilgjengelige for forespørselsavsenderens eget tilgjengelige resultat. For en annen deltakers aktivitet returneres de bare når arrangøren har aktivert show_analytics og forespørselsavsenderen oppfyller reglene for resultatsynlighet. Ellers er disse blokkene null, og physio_restricted er true.

Regler for synlighet og personvern #

Deltakere i utfordringen beholder tilgang til fullstendige resultater utenfor et tidsrom med skjulte resultater. Tilgangen for ansatte i organisasjonen kan avvike fra deltakertilgangen, men klienter skal likevel følge verdiene som er tilpasset forespørselsavsenderen og returneres av result-settings/.

Relatert #

• Offentlig API-oversikt
• Whitelabel og bedriftsoppsett