API til udfordringsresultater

Whitelabel-portaler og andre understøttede integrationer kan skabe en visning af udfordringsresultater med endepunkterne nedenfor. De bruger alle udfordringskoden og kræver en godkendt API-anmodning.

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

Rækkefølge af endepunkter #

Start med result-settings/. Brug dets flag og kolonnebeskrivelser til at afgøre, hvilke kontrolelementer og skærmbilleder der skal vises, i stedet for at antage, at alle udfordringer har samme resultatformat.

Hent værdierne for challenger_id fra udfordringens paginerede results/-rangliste. Aktivitets-id'er kommer fra den indlejrede liste activities.results i det detaljerede svar.

Resultatindstillinger #

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

Svaret beskriver den aktuelle præsentation af udfordringsresultaterne:

• primary_column og ordered_by identificerer ranglistemålingen og standardsorteringen.
• columns og team_columns er sorterede visningsbeskrivelser; deres nøgler svarer til felter i deltagernes og holdenes ranglisterækker.
• totals, progress, sections, distances og participant_data leverer valgfri kontekst for hele udfordringen.
• show_map og show_heatmap fortæller klienten, hvilke kortvisninger der skal tilbydes. show_analytics angiver, om denne anmoder må se en anden deltagers fysiologiske aktivitetsdata; det begrænser ikke den analyse, som anmoderen kan tilgå for sit eget resultat.
• results_limited er null, når resultaterne er ubegrænsede. Et tal betyder, at anmoderen kun kan se så mange af de øverste rækker, og at kontrolelementer til filtrering, sortering og paginering af resultater skal skjules.

Disse værdier afhænger af anmoderen. Den samme udfordring kan for eksempel returnere ubegrænsede indstillinger til en deltager og begrænsede indstillinger til en bruger, der er logget ind uden at deltage.

Varmekort over træningspas #

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

Varmekortet samler godkendte GPS-aktiviteter i gitterceller på cirka 150 meter. Hver celle er [longitude, latitude, weight], hvor vægten er antallet af forskellige aktiviteter, der har passeret gennem den. En aktivitet bidrager højst én gang til hver celle, og træningspas, der er markeret som private i kildeappen, udelukkes.

Varmekort genereres efter behov. Når der ikke findes et gemt varmekort, starter den første anmodning genereringen i baggrunden og returnerer:

{"status": "pending"}

Forespørg igen efter nogle få sekunder. Et færdigt svar indeholder generated_at, cell_size, activity_count, max_weight, truncated og cells. Gemte data kan vises, mens et forældet varmekort opdateres i baggrunden.

Brug max_weight til at normalisere et vægtet tæthedslag. Hvis truncated er true, indeholder svaret de tungeste celler i stedet for alle genererede celler.

Endepunktet returnerer 404, når arrangøren ikke har aktiveret show_heatmap, under en periode med skjulte resultater, eller når offentlige resultater er begrænsede, og anmoderen ikke er deltager.

Detaljeret deltagerresultat #

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

Svaret kombinerer:

• Deltagerens ranglisterække, valgte distance, placering og result_rank_total.
• statistics, f.eks. distance, varighed, tempo eller hastighed, energi, skridt, antal aktiviteter, aktive dage, længste serie og gennemsnitspuls, når den er tilgængelig.
• is_own_result, som angiver, om rækken tilhører den godkendte deltager.
• head_to_head, som kun er tilgængelig, når en deltager ser sit eget resultat. Den omfatter placering og percentil, ranglistemålingen, afstande til nærliggende konkurrenter og lederen, feltets gennemsnit samt rækkerne på podiet.
• activities, en indlejret pagineret liste over godkendte og synlige aktiviteter, der er medregnet i resultatet. Hver række indeholder grundlæggende træningsmetadata, gennemsnitstempo, en ruteform, når den er tilgængelig, og has_analytics.

For et resultat med fast distance stopper aktivitetslisten ved den aktivitet, der fuldførte den valgte distance. Senere aktiviteter vises ikke, fordi de ikke bidrog til resultatet.

Indlejret aktivitetspaginering #

Aktivitetslisten har de sædvanlige felter count, next, previous og results, men bruger særskilte forespørgselsparametre, så den ikke kolliderer med paginering på øverste niveau:

Placeringsuafhængige ruteformer #

Ruterne på aktivitetstidslinjen er ikke geografiske koordinater. Serveren flytter og skalerer hvert GPS-spor til et fast 158 × 108 SVG-koordinatsystem og returnerer kun:

• path — SVG-stidata
• start og end — punkter i det normaliserede koordinatsystem
• point_count — antal punkter i den returnerede form

Absolut breddegrad, længdegrad, grænser og centrum medtages ikke. Den samme rute flyttet til et andet sted giver samme form, så den er egnet som miniature, men kan ikke placeres på et geografisk kort.

Analyse pr. aktivitet #

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

Aktiviteten skal være godkendt, synlig og knyttet til netop dette deltagerresultat. Svaret indeholder grundlæggende distance, varighed, tempo og hastighed samt al analyse, der kan udledes af de gemte datastrømme:

Blokkene kan hver især være null, fordi udbydere og enheder leverer forskellige datastrømme. has_streams angiver, om der findes brugbar strømanalyse. x_kind angiver, om diagrammets x-værdier repræsenterer samlet distance eller forløbet tid.

Blokke med lav følsomhed — ruteform, intervaller, tempo og højde — er tilgængelige for alle anmodere, der kan tilgå resultatet. Fysiologiske blokke — puls, zoner, kadence og indsats — er altid tilgængelige for anmoderens eget tilgængelige resultat. For en anden deltagers aktivitet returneres de kun, når arrangøren har aktiveret show_analytics, og anmoderen opfylder reglerne for resultatsynlighed. Ellers er blokkene null, og physio_restricted er true.

Regler for synlighed og privatliv #

Uden for en periode med skjulte resultater bevarer udfordringsdeltagere adgang til alle resultater. Adgang for organisationens medarbejdere kan afvige fra deltagernes adgang, men klienter bør stadig følge de anmoderspecifikke værdier, som result-settings/ returnerer.

Relateret #

• Oversigt over det offentlige API
• Opsætning af whitelabel og virksomhedsløsninger