Izaicinājuma rezultātu API

White-label portāli un citas atbalstītas integrācijas var izveidot izaicinājuma rezultātu skatu, izmantojot tālāk norādītos galapunktus. Tie visi izmanto izaicinājuma kodu, un tiem nepieciešams autentificēts API pieprasījums.

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

Galapunktu secība #

Galapunkts	Lietojums
GET result-settings/	Noskaidro rezultātu kolonnas, kārtošanu, kopsummas, sadaļas, distances un pieejamos neobligātos skatus
GET heatmap/	Ielādē apkopotas treniņu blīvuma šūnas, ja ir iespējots show_heatmap
GET results/{challenger_id}/detailed/	Ielādē viena dalībnieka rezultātu, apkopoto statistiku, salīdzinājumus un aktivitāšu laika joslu
GET results/{challenger_id}/activities/{activity_id}/analytics/	Ielādē vienas pieņemtas aktivitātes starplaikus, diagrammas un atļauto sensoru analītiku

Sāc ar result-settings/. Izmanto tā karogus un kolonnu aprakstus, lai noteiktu, kuras vadīklas un skatus parādīt, nevis pieņemtu, ka visiem izaicinājumiem ir vienāds rezultātu formāts.

challenger_id vērtības iegūsti no izaicinājuma results/ kopvērtējuma ar lapošanu. Aktivitāšu ID ir pieejami detalizētās atbildes ligzdotajā sarakstā activities.results.

Rezultātu iestatījumi #

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

Atbilde apraksta pašreizējo izaicinājuma rezultātu attēlojumu:

• primary_column un ordered_by norāda ranga aprēķina rādītāju un noklusējuma secību.
• columns un team_columns ir sakārtoti attēlošanas apraksti; to atslēgas atbilst laukiem dalībnieku un komandu kopvērtējuma rindās.
• totals, progress, sections, distances un participant_data nodrošina neobligātu visa izaicinājuma kontekstu.
• show_map un show_heatmap norāda klientam, kurus kartes skatus piedāvāt. show_analytics norāda, vai šis pieprasītājs drīkst skatīt cita dalībnieka aktivitātes fizioloģiskos datus; tas neierobežo pieprasītāja paša pieejamo analītiku.
• results_limited ir null, ja rezultāti nav ierobežoti. Skaitlis nozīmē, ka pieprasītājs var skatīt tikai tik daudz augstāko rezultātu rindu, un rezultātu filtrēšanas, kārtošanas un lapošanas vadīklas ir jāpaslēpj.

Šīs vērtības ir pielāgotas pieprasītājam. Piemēram, vienam un tam pašam izaicinājumam dalībnieks var saņemt neierobežotus iestatījumus, bet pieteicies lietotājs, kurš nav dalībnieks, — ierobežotus iestatījumus.

Treniņu blīvuma karte #

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

Blīvuma kartē pieņemtās GPS aktivitātes tiek apkopotas aptuveni 150 metru režģa šūnās. Katra šūna ir [longitude, latitude, weight], kur svars ir to atšķirīgo aktivitāšu skaits, kas šķērsojušas attiecīgo šūnu. Viena aktivitāte katrā šūnā tiek ieskaitīta ne vairāk kā vienu reizi, un treniņi, kas avota lietotnē atzīmēti kā privāti, netiek iekļauti.

Blīvuma kartes tiek ģenerētas pēc pieprasījuma. Ja saglabātas kartes nav, pirmais pieprasījums sāk ģenerēšanu fonā un atgriež:

{"status": "pending"}

Pēc dažām sekundēm pieprasi datus atkārtoti. Gatavā atbilde ietver generated_at, cell_size, activity_count, max_weight, truncated un cells. Saglabātos datus var turpināt rādīt, kamēr novecojusi blīvuma karte tiek atjaunināta fonā.

Izmanto max_weight, lai normalizētu svērtā blīvuma slāni. Ja truncated ir true, atbildē ir ietvertas blīvākās šūnas, nevis visas ģenerētās šūnas.

Galapunkts atgriež 404, ja organizators nav iespējojis show_heatmap, ja ir aktīvs rezultātu slēpšanas periods vai ja publiskie rezultāti ir ierobežoti un pieprasītājs nav dalībnieks.

Detalizēts dalībnieka rezultāts #

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

Atbilde apvieno:

• Dalībnieka kopvērtējuma rindu, izvēlēto distanci, vietu un result_rank_total.
• statistics datus, piemēram, distanci, ilgumu, tempu vai ātrumu, enerģiju, soļus, aktivitāšu skaitu, aktīvās dienas, garāko secīgo aktīvo dienu sēriju un vidējo pulsu, ja tas ir pieejams.
• is_own_result, kas norāda, vai rinda pieder autentificētajam dalībniekam.
• head_to_head, kas ir pieejams tikai dalībniekam, skatot savu rezultātu. Tas ietver vietu un procentili, ranga aprēķina rādītāju, atšķirību līdz tuvākajiem konkurentiem un līderim, visu dalībnieku vidējo rādītāju un godalgoto vietu rindas.
• activities — ligzdotu sarakstu ar lapošanu, kurā iekļautas rezultātā ieskaitītās, pieņemtās un redzamās aktivitātes. Katrā rindā ir treniņa pamatdati, vidējais temps, maršruta forma, ja tā pieejama, un has_analytics.

Fiksētas distances rezultātam aktivitāšu saraksts beidzas ar aktivitāti, kurā pabeigta izvēlētā distance. Vēlākas aktivitātes netiek rādītas, jo tās nav devušas ieguldījumu šajā rezultātā.

Ligzdotā aktivitāšu lapošana #

Aktivitāšu sarakstam ir ierastie lauki count, next, previous un results, bet tas izmanto atsevišķus vaicājuma parametrus, lai nerastos konflikts ar augstākā līmeņa lapošanu:

Parametrs	Nozīme
activities_page	Lapas numurs, sākot ar 1
activities_per_page	Vienumu skaits lapā; pēc noklusējuma 25, ievērojot API maksimālo ierobežojumu

Atrašanās vietai nepiesaistītas maršruta formas #

Aktivitāšu laika joslā redzamie maršruti nav ģeogrāfiskās koordinātas. Serveris pārbīda un mērogo katru GPS ierakstu fiksētā 158 × 108 SVG koordinātu telpā un atgriež tikai:

• path — SVG ceļa datus
• start un end — punktus normalizētajā koordinātu telpā
• point_count — punktu skaitu atgrieztajā formā

Absolūtais ģeogrāfiskais platums un garums, robežas un centrs netiek iekļauti. Tas pats maršruts, kas pārvietots uz citu atrašanās vietu, veido tādu pašu formu, tāpēc to var izmantot sīktēlam, bet nevar attēlot ģeogrāfiskā kartē.

Atsevišķas aktivitātes analītika #

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

Aktivitātei jābūt pieņemtai, redzamai un piesaistītai tieši šī dalībnieka rezultātam. Atbildē ir distances, ilguma, tempa un ātruma pamatdati, kā arī visa analītika, ko iespējams iegūt no saglabātajām datu plūsmām:

Bloks	Saturs
route	Tā pati atrašanās vietai nepiesaistītā maršruta forma, ko izmanto aktivitāšu laika joslā
km_splits	Pilnu kilometru starplaiki un neobligāts pēdējais nepilnais posms, tostarp ātrākā un lēnākā posma atzīmes
elevation	Samazinātas izšķirtspējas augstuma profils, kāpums, kritums, minimālā un maksimālā vērtība
heart_rate un hr_zones	Samazinātas izšķirtspējas pulsa datu virkne, vidējais un maksimālais pulss, atsauces maksimālais pulss un laiks piecās zonās
cadence	Samazinātas izšķirtspējas kadences datu virkne un vidējā vērtība
effort_score	Pēc pulsa aprēķināts slodzes novērtējums

Katram blokam atsevišķi var nebūt vērtības, jo dažādi pakalpojumu sniedzēji un ierīces nodrošina atšķirīgas datu plūsmas. has_streams norāda, vai ir pieejama izmantojama datu plūsmu analītika. x_kind norāda, vai diagrammas x vērtības apzīmē kopējo distanci vai pagājušo laiku.

Zema jutīguma bloki — maršruta forma, starplaiki, temps un augstums — ir pieejami ikvienam pieprasītājam, kurš var piekļūt rezultātam. Fizioloģiskie bloki — pulss, pulsa zonas, kadence un slodze — vienmēr ir pieejami pieprasītāja paša rezultātam, ja šim rezultātam var piekļūt. Cita dalībnieka aktivitātei tie tiek atgriezti tikai tad, ja organizators ir iespējojis show_analytics un pieprasītājs atbilst rezultātu redzamības noteikumiem. Pretējā gadījumā šie bloki ir null, bet physio_restricted ir true.

Redzamības un privātuma noteikumi #

Iestatījums vai stāvoklis	Ietekme
show_heatmap izslēgts	Blīvuma karte atgriež 404; result-settings ziņo show_heatmap: false
show_analytics izslēgts	Citu dalībnieku fizioloģisko aktivitāšu bloki tiek noņemti; paša pieejamā analītika netiek ietekmēta
Aktīvs rezultātu slēpšanas periods	Dalībnieku detalizētie rezultāti tiek slēpti; blīvuma karte atgriež 404; show_heatmap un show_analytics ir false
hide_results_public ieslēgts	Pieteikušies lietotāji, kuri nav dalībnieki, var redzēt tikai konfigurēto labāko rezultātu skaitu, nevar ielādēt blīvuma karti un nevar skatīt citu dalībnieku fizioloģisko analītiku
Treniņš nav pieņemts vai nav redzams	Tas netiek iekļauts laika joslā, un to nevar atvērt analītikas galapunktā

Ārpus rezultātu slēpšanas perioda izaicinājuma dalībniekiem ir pieejami visi rezultāti. Organizācijas darbinieku piekļuve var atšķirties no dalībnieku piekļuves, tomēr klientiem vienmēr jāievēro konkrētajam pieprasītājam paredzētās vērtības, ko atgriež result-settings/.

Saistītie raksti #

• Publiskā API pārskats
• White-label un uzņēmumu iestatīšana