API för utmaningsresultat

Whitelabel-portaler och andra integrationer som stöds kan bygga en upplevelse för utmaningsresultat med slutpunkterna nedan. Alla använder utmaningskoden och kräver en autentiserad API-begäran.

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

Slutpunkternas ordning #

Börja med result-settings/. Använd dess flaggor och kolumnbeskrivningar för att avgöra vilka kontroller och skärmar som ska visas, i stället för att anta att alla utmaningar har samma resultatformat.

Hämta värden för challenger_id från utmaningens paginerade topplista results/. Aktivitets-ID:n kommer från den nästlade listan activities.results i det detaljerade svaret.

Resultatinställningar #

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

Svaret beskriver den aktuella presentationen av utmaningsresultaten:

• primary_column och ordered_by identifierar rankningsmåttet och standardsorteringen.
• columns och team_columns är ordnade visningsbeskrivningar; deras nycklar motsvarar fält i deltagarnas och lagens topplisterader.
• totals, progress, sections, distances och participant_data ger valfritt sammanhang för hela utmaningen.
• show_map och show_heatmap talar om för klienten vilka kartvyer som ska erbjudas. show_analytics anger om anroparen får se fysiologiska aktivitetsdata för en annan deltagare; det begränsar inte anroparens egen åtkomliga analys.
• results_limited är null när resultaten är obegränsade. Ett tal innebär att anroparen bara kan se så många topprader och att kontroller för filtrering, sortering och paginering av resultat ska döljas.

Värdena är anpassade till anroparen. Samma utmaning kan till exempel ge obegränsade inställningar till en deltagare och begränsade inställningar till en inloggad användare som inte deltar.

Värmekarta över träningspass #

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

Värmekartan samlar accepterade GPS-aktiviteter i rutnätsceller på cirka 150 meter. Varje cell är [longitude, latitude, weight], där vikten är antalet unika aktiviteter som passerade genom den. En aktivitet bidrar högst en gång till varje cell och träningspass som markerats som privata i källappen utesluts.

Värmekartor genereras vid behov. När ingen lagrad värmekarta finns startar den första begäran generering i bakgrunden och returnerar:

{"status": "pending"}

Fråga igen efter några sekunder. Ett färdigt svar innehåller generated_at, cell_size, activity_count, max_weight, truncated och cells. Lagrade data kan fortsätta att visas medan en inaktuell värmekarta uppdateras i bakgrunden.

Använd max_weight för att normalisera ett viktat densitetslager. Om truncated är true innehåller svaret de tyngsta cellerna i stället för alla genererade celler.

Slutpunkten returnerar 404 när arrangören inte har aktiverat show_heatmap, under en period med dolda resultat eller när offentliga resultat är begränsade och anroparen inte är deltagare.

Detaljerat deltagarresultat #

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

Svaret kombinerar:

• Deltagarens topplisterad, valda distans, placering och result_rank_total.
• statistics, till exempel distans, varaktighet, tempo eller hastighet, energi, steg, antal aktiviteter, aktiva dagar, längsta serie och genomsnittspuls när den finns.
• is_own_result, som anger om raden tillhör den autentiserade deltagaren.
• head_to_head, som bara är tillgängligt när en deltagare visar sitt eget resultat. Det innehåller placering och percentil, rankningsmåttet, avstånd till närliggande konkurrenter och ledaren, fältets genomsnitt samt pallraderna.
• activities, en nästlad paginerad lista över accepterade och synliga aktiviteter som tillgodoräknats resultatet. Varje rad innehåller grundläggande träningsmetadata, genomsnittstempo, en ruttform när den finns och has_analytics.

För ett resultat med fast distans slutar aktivitetslistan vid den aktivitet som slutförde den valda distansen. Senare aktiviteter visas inte eftersom de inte bidrog till det resultatet.

Nästlad aktivitetspaginering #

Aktivitetslistan har de vanliga fälten count, next, previous och results, men använder särskilda frågeparametrar så att den inte krockar med paginering på toppnivån:

Platsoberoende ruttformer #

Rutterna i aktivitetstidslinjen är inte geografiska koordinater. Servern flyttar och skalar varje GPS-spår till ett fast SVG-koordinatutrymme på 158 × 108 och returnerar endast:

• path — SVG-sökvägsdata
• start och end — punkter i det normaliserade koordinatutrymmet
• point_count — antal punkter i den returnerade formen

Absolut latitud, longitud, gränser och centrum ingår inte. Samma rutt flyttad till en annan plats ger samma form, så den passar som miniatyr men kan inte ritas på en geografisk karta.

Analys per aktivitet #

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

Aktiviteten måste vara accepterad, synlig och kopplad till just det deltagarresultatet. Svaret innehåller grundläggande distans, varaktighet, tempo och hastighet samt all analys som kan härledas från de lagrade dataströmmarna:

Varje block kan oberoende vara null eftersom leverantörer och enheter tillhandahåller olika dataströmmar. has_streams anger om användbar strömanalys finns. x_kind anger om diagrammets x-värden representerar kumulativ distans eller förfluten tid.

Block med låg känslighet — ruttform, mellantider, tempo och höjd — är tillgängliga för alla anropare som kan nå resultatet. Fysiologiska block — puls, zoner, kadens och ansträngning — är alltid tillgängliga för anroparens eget nåbara resultat. För en annan deltagares aktivitet returneras de bara när arrangören har aktiverat show_analytics och anroparen uppfyller reglerna för resultatsynlighet. Annars är blocken null och physio_restricted är true.

Regler för synlighet och sekretess #

Utmaningsdeltagare behåller åtkomst till fullständiga resultat utanför en period med dolda resultat. Organisationens personal kan ha annan åtkomst än deltagarna, men klienter ska ändå följa de anroparspecifika värden som returneras av result-settings/.

Relaterat #

• Offentlig API-översikt
• Whitelabel och företagsinställningar