Meydan okuma sonuçları API'si

White-label portallar ve desteklenen diğer entegrasyonlar, aşağıdaki uç noktalarla bir meydan okuma sonuç deneyimi oluşturabilir. Bu uç noktaların tümü meydan okuma kodunu kullanır ve kimliği doğrulanmış bir API isteği gerektirir.

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

Uç nokta sırası #

result-settings/ ile başlayın. Her meydan okumanın aynı sonuç biçimine sahip olduğunu varsaymak yerine, hangi denetimlerin ve ekranların gösterileceğine karar vermek için buradaki bayrakları ve sütun açıklamalarını kullanın.

challenger_id değerlerini meydan okumanın sayfalanmış results/ liderlik tablosundan alın. Aktivite kimlikleri, ayrıntılı yanıttaki iç içe activities.results listesinde bulunur.

Sonuç ayarları #

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

Yanıt, meydan okumanın mevcut sonuç sunumunu açıklar:

• primary_column ve ordered_by, sıralama ölçütünü ve varsayılan düzeni belirtir.
• columns ve team_columns sıralı görüntüleme açıklamalarıdır; anahtarları katılımcı ve takım liderlik tablosu satırlarındaki alanlarla eşleşir.
• totals, progress, sections, distances ve participant_data, meydan okuma genelinde isteğe bağlı bağlam sağlar.
• show_map ve show_heatmap, istemciye hangi harita görünümlerinin sunulacağını bildirir. show_analytics, isteği yapan kullanıcının başka bir katılımcının fizyolojik aktivite verilerini görüp göremeyeceğini belirtir; kullanıcının kendi erişilebilir analizlerini kısıtlamaz.
• results_limited, sınırsız sonuçlar için null değerindedir. Bir sayı, isteği yapan kullanıcının yalnızca bu kadar üst sırayı görebileceği ve sonuç filtreleme, sıralama ve sayfalama denetimlerinin gizlenmesi gerektiği anlamına gelir.

Bu değerler isteği yapan kullanıcıya göre uyarlanır. Örneğin aynı meydan okuma, bir katılımcıya sınırsız ayarlar; oturum açmış ancak katılımcı olmayan bir kullanıcıya ise sınırlı ayarlar döndürebilir.

Antrenman ısı haritası #

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

Isı haritası, kabul edilen GPS aktivitelerini yaklaşık 150 metrelik ızgara hücrelerinde toplar. Her hücre [longitude, latitude, weight] biçimindedir; ağırlık, o hücreden geçen farklı aktivitelerin sayısıdır. Bir aktivite her hücreye en fazla bir kez katkıda bulunur ve kaynak uygulamada özel olarak işaretlenen antrenmanlar dahil edilmez.

Isı haritaları gerektiğinde oluşturulur. Kayıtlı bir ısı haritası yoksa ilk istek arka planda oluşturmayı başlatır ve şu yanıtı döndürür:

{"status": "pending"}

Birkaç saniye sonra verileri yeniden isteyin. Hazır yanıt generated_at, cell_size, activity_count, max_weight, truncated ve cells alanlarını içerir. Eski bir ısı haritası arka planda yenilenirken kayıtlı veriler sunulmaya devam edebilir.

Ağırlıklı yoğunluk katmanını normalleştirmek için max_weight değerini kullanın. truncated true ise yanıt, oluşturulan tüm hücreler yerine en yüksek ağırlığa sahip hücreleri içerir.

Organizatör show_heatmap özelliğini etkinleştirmediyse, sonuçların gizlendiği bir dönem etkinse veya herkese açık sonuçlar sınırlıyken isteği yapan kullanıcı katılımcı değilse uç nokta 404 döndürür.

Ayrıntılı katılımcı sonucu #

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

Yanıt şunları birleştirir:

• Katılımcının liderlik tablosu satırı, seçilen mesafe, sıralama ve result_rank_total.
• Mesafe, süre, tempo veya hız, enerji, adımlar, aktivite sayısı, aktif günler, en uzun seri ve mevcut olduğunda ortalama kalp atış hızı gibi statistics verileri.
• Satırın kimliği doğrulanmış katılımcıya ait olup olmadığını belirten is_own_result.
• Yalnızca bir katılımcı kendi sonucuna baktığında kullanılabilen head_to_head. Sıralama ve yüzdelik dilim, sıralama ölçütü, yakındaki rakiplere ve lidere olan farklar, tüm katılımcıların ortalaması ve podyum satırlarını içerir.
• Sonuca dahil edilen, kabul edilmiş ve görünür aktivitelerden oluşan iç içe sayfalanmış activities listesi. Her satır temel antrenman meta verilerini, ortalama tempoyu, mevcut olduğunda rota şeklini ve has_analytics alanını içerir.

Sabit mesafeli bir sonuçta aktivite listesi, seçilen mesafenin tamamlandığı aktivitede sona erer. Daha sonraki aktiviteler bu sonuca katkıda bulunmadıkları için görüntülenmez.

İç içe aktivite sayfalaması #

Aktivite listesinde standart count, next, previous ve results alanları bulunur; ancak üst düzey sayfalamayla çakışmaması için özel sorgu parametreleri kullanılır:

Konumdan bağımsız rota şekilleri #

Aktivite zaman çizelgesindeki rotalar coğrafi koordinatlar değildir. Sunucu her GPS izini sabit bir 158 × 108 SVG koordinat alanına taşır ve ölçeklendirir; yalnızca şunları döndürür:

• path — SVG yol verileri
• start ve end — normalleştirilmiş koordinat alanındaki noktalar
• point_count — döndürülen şekildeki nokta sayısı

Mutlak enlem, boylam, sınırlar ve merkez dahil edilmez. Başka bir konuma taşınan aynı rota aynı şekli üretir; bu nedenle küçük resim için uygundur, ancak coğrafi bir haritada çizilemez.

Aktivite başına analiz #

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

Aktivite kabul edilmiş ve görünür olmalı, ayrıca tam olarak bu katılımcı sonucuna bağlı olmalıdır. Yanıt temel mesafe, süre, tempo ve hız bilgileriyle birlikte kayıtlı veri akışlarından türetilebilen analizleri içerir:

Sağlayıcılar ve cihazlar farklı akışlar sunduğundan her blok diğerlerinden bağımsız olarak null olabilir. has_streams, kullanılabilir akış analizlerinin bulunup bulunmadığını bildirir. x_kind, grafiklerin x değerlerinin kümülatif mesafeyi mi yoksa geçen süreyi mi temsil ettiğini belirtir.

Düşük hassasiyetli bloklara — rota şekli, bölümler, tempo ve yükseklik — sonuca erişebilen her kullanıcı ulaşabilir. Fizyolojik bloklar — kalp atış hızı, bölgeler, kadans ve efor — isteği yapan kullanıcının kendi erişilebilir sonucu için her zaman kullanılabilir. Başka bir katılımcının aktivitesinde ise yalnızca organizatör show_analytics özelliğini etkinleştirmişse ve isteği yapan kullanıcı sonuç görünürlük kurallarını karşılıyorsa döndürülür. Aksi durumda bu bloklar null, physio_restricted ise true olur.

Görünürlük ve gizlilik kuralları #

Meydan okuma katılımcıları, sonuçların gizlendiği bir dönem dışında tüm sonuçlara erişmeye devam eder. Organizasyon personelinin erişimi katılımcı erişiminden farklı olabilir; ancak istemciler yine de result-settings/ tarafından döndürülen, isteği yapan kullanıcıya özel değerleri izlemelidir.

İlgili #

• Genel API genel bakış
• Beyaz Etiket ve Kurumsal Kurulum