Challenge-Ergebnis-API

Whitelabel-Portale und andere unterstützte Integrationen können mit den folgenden Endpunkten eine Ergebnisansicht für Challenges erstellen. Sie verwenden alle den Challenge-Code und erfordern eine authentifizierte API-Anfrage.

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

Reihenfolge der Endpunkte #

Beginnen Sie mit result-settings/. Verwenden Sie dessen Flags und Spaltenbeschreibungen, um zu entscheiden, welche Steuerelemente und Ansichten dargestellt werden, statt davon auszugehen, dass jede Challenge dasselbe Ergebnisformat hat.

Die Werte für challenger_id stammen aus der paginierten results/-Rangliste der Challenge. Aktivitäts-IDs stammen aus der verschachtelten Liste activities.results in der Detailantwort.

Ergebniseinstellungen #

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

Die Antwort beschreibt die aktuelle Ergebnisdarstellung der Challenge:

• primary_column und ordered_by geben die Ranglistenmetrik und die Standardsortierung an.
• columns und team_columns sind geordnete Darstellungsbeschreibungen; ihre Schlüssel entsprechen Feldern in Teilnehmer- und Team-Ranglistenzeilen.
• totals, progress, sections, distances und participant_data liefern optionalen Challenge-weiten Kontext.
• show_map und show_heatmap geben dem Client vor, welche Kartenansichten angeboten werden. show_analytics gibt an, ob dieser Aufrufer physiologische Aktivitätsdaten eines anderen Teilnehmers sehen darf; die eigenen erreichbaren Analysen des Aufrufers werden dadurch nicht eingeschränkt.
• results_limited ist bei uneingeschränkten Ergebnissen null. Eine Zahl bedeutet, dass der Aufrufer nur so viele oberste Zeilen sehen kann; Filter-, Sortier- und Seitennavigationsfunktionen für Ergebnisse sollten dann ausgeblendet werden.

Diese Werte hängen vom Aufrufer ab. Dieselbe Challenge kann einem Teilnehmer beispielsweise uneingeschränkte Einstellungen und einem angemeldeten Nicht-Teilnehmer eingeschränkte Einstellungen liefern.

Workout-Heatmap #

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

Die Heatmap fasst akzeptierte GPS-Aktivitäten in etwa 150 Meter großen Rasterzellen zusammen. Jede Zelle hat die Form [longitude, latitude, weight]; der Wert weight ist die Anzahl verschiedener Aktivitäten, die diese Zelle durchquert haben. Eine Aktivität zählt höchstens einmal je Zelle, und in der Quell-App als privat markierte Workouts werden ausgeschlossen.

Heatmaps werden bei Bedarf erzeugt. Ist noch keine Heatmap gespeichert, startet die erste Anfrage die Hintergrundgenerierung und liefert:

{"status": "pending"}

Fragen Sie nach einigen Sekunden erneut ab. Eine fertige Antwort enthält generated_at, cell_size, activity_count, max_weight, truncated und cells. Gespeicherte Daten können ausgeliefert werden, während eine veraltete Heatmap im Hintergrund aktualisiert wird.

Verwenden Sie max_weight, um eine gewichtete Dichteschicht zu normalisieren. Wenn truncated den Wert true hat, enthält die Antwort die am stärksten gewichteten Zellen statt aller erzeugten Zellen.

Der Endpunkt liefert 404, wenn der Organisator show_heatmap nicht aktiviert hat, während eines Zeitfensters mit ausgeblendeten Ergebnissen oder wenn öffentliche Ergebnisse eingeschränkt sind und der Aufrufer kein Teilnehmer ist.

Detailliertes Teilnehmerergebnis #

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

Die Antwort kombiniert:

• Ranglistenzeile, gewählte Distanz, Rang und result_rank_total des Teilnehmers.
• statistics wie Distanz, Dauer, Pace oder Geschwindigkeit, Energie, Schritte, Aktivitätsanzahl, aktive Tage, längste Serie und durchschnittliche Herzfrequenz, sofern verfügbar.
• is_own_result, das angibt, ob die Zeile zum authentifizierten Teilnehmer gehört.
• head_to_head, das nur verfügbar ist, wenn ein Teilnehmer sein eigenes Ergebnis betrachtet. Es enthält Rang und Perzentil, die Ranglistenmetrik, Abstände zu benachbarten Teilnehmern und zum Führenden, den Felddurchschnitt sowie Podiumszeilen.
• activities, eine verschachtelte paginierte Liste akzeptierter, sichtbarer Aktivitäten, die dem Ergebnis gutgeschrieben wurden. Jede Zeile enthält grundlegende Workout-Metadaten, durchschnittliche Pace, eine Routenform, sofern verfügbar, und has_analytics.

Bei einem Ergebnis über eine feste Distanz endet die Aktivitätsliste bei der Aktivität, mit der die gewählte Distanz erreicht wurde. Spätere Aktivitäten erscheinen nicht, weil sie nicht zu diesem Ergebnis beigetragen haben.

Verschachtelte Aktivitäts-Paginierung #

Die Aktivitätsliste enthält die üblichen Felder count, next, previous und results, verwendet jedoch eigene Abfrageparameter, damit sie nicht mit der Paginierung auf oberster Ebene kollidiert:

Routenformen ohne Positionsdaten #

Routen in der Aktivitätszeitleiste sind keine geografischen Koordinaten. Der Server verschiebt und skaliert jede GPS-Spur in einen festen SVG-Koordinatenraum von 158 × 108 und liefert nur:

• path — SVG-Pfaddaten
• start und end — Punkte im normalisierten Koordinatenraum
• point_count — Anzahl der Punkte in der gelieferten Form

Absolute Werte für Breitengrad, Längengrad, Grenzen und Mittelpunkt sind nicht enthalten. Dieselbe an einen anderen Ort verschobene Route erzeugt dieselbe Form. Sie eignet sich daher für ein Vorschaubild, kann aber nicht auf einer geografischen Karte dargestellt werden.

Analyse einzelner Aktivitäten #

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

Die Aktivität muss akzeptiert und sichtbar sein und genau diesem Teilnehmerergebnis zugeordnet sein. Die Antwort enthält grundlegende Werte für Distanz, Dauer, Pace und Geschwindigkeit sowie alle Analysen, die sich aus den gespeicherten Datenströmen ableiten lassen:

Blöcke sind unabhängig voneinander nullfähig, da Anbieter und Geräte unterschiedliche Datenströme liefern. has_streams gibt an, ob nutzbare Datenstromanalysen vorhanden sind. x_kind gibt an, ob die x-Werte eines Diagramms die kumulierte Distanz oder die verstrichene Zeit darstellen.

Blöcke mit geringer Sensibilität – Routenform, Splits, Pace und Höhe – stehen jedem Aufrufer zur Verfügung, der das Ergebnis erreichen kann. Physiologische Blöcke – Herzfrequenz, Zonen, Trittfrequenz und Belastung – stehen dem Aufrufer für sein eigenes erreichbares Ergebnis immer zur Verfügung. Bei der Aktivität eines anderen Teilnehmers werden sie nur geliefert, wenn der Organisator show_analytics aktiviert hat und der Aufrufer die Sichtbarkeitsregeln für Ergebnisse erfüllt. Andernfalls sind diese Blöcke null und physio_restricted hat den Wert true.

Sichtbarkeits- und Datenschutzregeln #

Challenge-Teilnehmer behalten außerhalb eines Zeitfensters mit ausgeblendeten Ergebnissen Zugriff auf die vollständigen Ergebnisse. Der Zugriff von Organisationsmitarbeitern kann sich vom Teilnehmerzugriff unterscheiden; Clients sollten dennoch den aufruferspezifischen Werten aus result-settings/ folgen.

Verwandte Themen #

• Öffentliche API-Übersicht
• Whitelabel- und Enterprise-Einrichtung