API wyników wyzwań

Portale whitelabel i inne obsługiwane integracje mogą tworzyć interfejs wyników wyzwania za pomocą poniższych punktów końcowych. Wszystkie używają kodu wyzwania i wymagają uwierzytelnionego żądania API.

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

Kolejność punktów końcowych #

Zacznij od result-settings/. Na podstawie jego flag i opisów kolumn wybierz elementy sterujące i ekrany do wyświetlenia, zamiast zakładać, że każde wyzwanie ma taki sam format wyników.

Wartości challenger_id pobierz z podzielonego na strony rankingu results/ wyzwania. Identyfikatory aktywności pochodzą z zagnieżdżonej listy activities.results w odpowiedzi szczegółowej.

Ustawienia wyników #

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

Odpowiedź opisuje bieżący sposób prezentacji wyników wyzwania:

• primary_column i ordered_by określają miarę rankingu i domyślną kolejność.
• columns i team_columns to uporządkowane opisy renderowania; ich klucze odpowiadają polom w wierszach rankingów uczestników i zespołów.
• totals, progress, sections, distances i participant_data dostarczają opcjonalnego kontekstu całego wyzwania.
• show_map i show_heatmap wskazują klientowi, które widoki mapy udostępnić. show_analytics określa, czy wywołujący może zobaczyć fizjologiczne dane aktywności innego uczestnika; nie ogranicza dostępnych analiz własnych wywołującego.
• results_limited ma wartość null dla wyników bez ograniczeń. Liczba oznacza, że wywołujący widzi tylko tyle najwyższych wierszy, a elementy filtrowania, sortowania i stronicowania wyników powinny być ukryte.

Wartości te zależą od wywołującego. To samo wyzwanie może na przykład zwrócić ustawienia bez ograniczeń uczestnikowi, a ograniczone ustawienia zalogowanej osobie niebędącej uczestnikiem.

Mapa cieplna treningów #

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

Mapa cieplna agreguje zaakceptowane aktywności GPS w komórkach siatki o rozmiarze około 150 metrów. Każda komórka ma postać [longitude, latitude, weight], gdzie weight oznacza liczbę różnych aktywności, które przez nią przebiegały. Aktywność wnosi wkład do każdej komórki najwyżej raz, a treningi oznaczone jako prywatne w aplikacji źródłowej są wykluczane.

Mapy cieplne są generowane na żądanie. Gdy nie ma zapisanej mapy, pierwsze żądanie uruchamia generowanie w tle i zwraca:

{"status": "pending"}

Ponów żądanie po kilku sekundach. Gotowa odpowiedź zawiera generated_at, cell_size, activity_count, max_weight, truncated i cells. Zapisane dane mogą być udostępniane, gdy nieaktualna mapa cieplna jest odświeżana w tle.

Użyj max_weight, aby znormalizować ważoną warstwę gęstości. Jeśli truncated ma wartość true, odpowiedź zawiera komórki o największej wadze zamiast wszystkich wygenerowanych komórek.

Punkt końcowy zwraca 404, gdy organizator nie włączył show_heatmap, podczas okresu ukrywania wyników albo gdy wyniki publiczne są ograniczone, a wywołujący nie jest uczestnikiem.

Szczegółowy wynik uczestnika #

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

Odpowiedź łączy:

• Wiersz rankingu uczestnika, wybrany dystans, miejsce i result_rank_total.
• statistics, takie jak dystans, czas trwania, tempo lub prędkość, energia, kroki, liczba aktywności, aktywne dni, najdłuższa seria oraz średnie tętno, jeśli jest dostępne.
• is_own_result, które wskazuje, czy wiersz należy do uwierzytelnionego uczestnika.
• head_to_head, dostępne tylko wtedy, gdy uczestnik wyświetla własny wynik. Obejmuje miejsce i percentyl, miarę rankingu, różnice do najbliższych rywali i lidera, średnią stawki oraz wiersze podium.
• activities, zagnieżdżoną, stronicowaną listę zaakceptowanych i widocznych aktywności zaliczonych do wyniku. Każdy wiersz zawiera podstawowe metadane treningu, średnie tempo, kształt trasy, gdy jest dostępny, oraz has_analytics.

Dla wyniku na ustalonym dystansie lista aktywności kończy się na aktywności, która ukończyła wybrany dystans. Późniejsze aktywności nie są wyświetlane, ponieważ nie przyczyniły się do tego wyniku.

Stronicowanie zagnieżdżonych aktywności #

Lista aktywności ma standardowe pola count, next, previous i results, ale używa osobnych parametrów zapytania, aby nie kolidować ze stronicowaniem najwyższego poziomu:

Kształty tras bez danych o położeniu #

Trasy na osi czasu aktywności nie są współrzędnymi geograficznymi. Serwer przesuwa i skaluje każdy ślad GPS do stałej przestrzeni współrzędnych SVG 158 × 108 i zwraca tylko:

• path — dane ścieżki SVG
• start i end — punkty w znormalizowanej przestrzeni współrzędnych
• point_count — liczba punktów w zwróconym kształcie

Bezwzględna szerokość i długość geograficzna, granice oraz środek nie są dołączane. Ta sama trasa przeniesiona w inne miejsce daje ten sam kształt, dlatego nadaje się do miniatury, ale nie można jej nanieść na mapę geograficzną.

Analizy poszczególnych aktywności #

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

Aktywność musi być zaakceptowana, widoczna i przypisana dokładnie do tego wyniku uczestnika. Odpowiedź zawiera podstawowy dystans, czas trwania, tempo i prędkość oraz analizy, które można uzyskać z zapisanych strumieni:

Poszczególne bloki mogą niezależnie mieć wartość null, ponieważ dostawcy i urządzenia udostępniają różne strumienie. has_streams informuje, czy są dostępne użyteczne analizy strumieni. x_kind wskazuje, czy wartości x wykresu oznaczają skumulowany dystans czy czas, który upłynął.

Bloki o niskiej wrażliwości — kształt trasy, międzyczasy, tempo i wysokość — są dostępne dla każdego wywołującego, który ma dostęp do wyniku. Bloki fizjologiczne — tętno, strefy, kadencja i wysiłek — są zawsze dostępne dla własnego osiągalnego wyniku wywołującego. W przypadku aktywności innego uczestnika są zwracane tylko wtedy, gdy organizator włączył show_analytics, a wywołujący spełnia reguły widoczności wyników. W przeciwnym razie bloki te mają wartość null, a physio_restricted ma wartość true.

Reguły widoczności i prywatności #

Poza okresem ukrywania wyników uczestnicy wyzwania zachowują dostęp do pełnych wyników. Dostęp pracowników organizacji może różnić się od dostępu uczestników, ale klienci powinni zawsze stosować wartości właściwe dla wywołującego, zwracane przez result-settings/.

Powiązane artykuły #

• Przegląd Publicznego API
• Whitelabel i konfiguracja dla przedsiębiorstw