API نتائج التحديات

يمكن للبوابات ذات العلامة البيضاء وغيرها من عمليات التكامل المدعومة إنشاء تجربة لنتائج التحديات باستخدام نقاط النهاية أدناه. تستخدم جميعها رمز التحدي وتتطلب طلب API مصادقًا عليه.

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

تسلسل نقاط النهاية #

نقطة النهاية	الاستخدام
GET result-settings/	اكتشاف أعمدة النتائج وترتيبها والإجماليات والأقسام والمسافات والعروض الاختيارية المتاحة
GET heatmap/	تحميل خلايا كثافة التدريبات المجمعة عند تمكين show_heatmap
GET results/{challenger_id}/detailed/	تحميل نتيجة مشارك واحد والإحصاءات المجمعة والمقارنات والمخطط الزمني للأنشطة
GET results/{challenger_id}/activities/{activity_id}/analytics/	تحميل التقسيمات والرسوم البيانية وتحليلات المستشعرات المسموح بها لنشاط مقبول واحد

ابدأ بـ result-settings/. استخدم علاماته وأوصاف الأعمدة لتحديد عناصر التحكم والشاشات التي ينبغي عرضها، بدلًا من افتراض أن جميع التحديات تستخدم تنسيق النتائج نفسه.

احصل على قيم challenger_id من لوحة متصدري results/ المرقّمة بالصفحات للتحدي. تتوفر معرّفات الأنشطة في القائمة المتداخلة activities.results ضمن الاستجابة التفصيلية.

إعدادات النتائج #

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

تصف الاستجابة العرض الحالي لنتائج التحدي:

• يحدد primary_column وordered_by مقياس الترتيب والترتيب الافتراضي.
• يمثل columns وteam_columns أوصاف عرض مرتبة؛ وتتطابق مفاتيحها مع الحقول في صفوف لوحات متصدري المشاركين والفرق.
• يوفر totals وprogress وsections وdistances وparticipant_data سياقًا اختياريًا على مستوى التحدي كله.
• يخبر show_map وshow_heatmap العميل بعروض الخرائط التي يمكن توفيرها. ويحدد show_analytics ما إذا كان طالب البيانات يستطيع رؤية البيانات الفسيولوجية لنشاط مشارك آخر؛ ولا يقيّد التحليلات المتاحة لنتيجته الخاصة.
• تكون قيمة results_limited هي null عندما تكون النتائج غير مقيدة. ويعني الرقم أن طالب البيانات لا يمكنه رؤية سوى ذلك العدد من الصفوف الأولى، وأنه ينبغي إخفاء عناصر التحكم في تصفية النتائج وترتيبها وترقيم صفحاتها.

تُكيّف هذه القيم وفق طالب البيانات. فعلى سبيل المثال، يمكن أن يعيد التحدي نفسه إعدادات غير مقيدة لمشارك وإعدادات مقيدة لمستخدم سجّل الدخول لكنه غير مشارك.

خريطة كثافة التدريبات #

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

تجمع خريطة الكثافة أنشطة GPS المقبولة في خلايا شبكة يبلغ حجمها نحو 150 مترًا. تكون كل خلية بالشكل [longitude, latitude, weight]، حيث يمثل الوزن عدد الأنشطة المختلفة التي مرت بها. لا يساهم النشاط بأكثر من مرة واحدة في كل خلية، وتُستبعد التدريبات المحددة على أنها خاصة في تطبيقها المصدر.

تُنشأ خرائط الكثافة عند الحاجة. عندما لا توجد خريطة محفوظة، يبدأ الطلب الأول إنشاءها في الخلفية ويعيد:

{"status": "pending"}

أعد طلب البيانات بعد بضع ثوانٍ. تتضمن الاستجابة الجاهزة generated_at وcell_size وactivity_count وmax_weight وtruncated وcells. يمكن مواصلة عرض البيانات المحفوظة بينما تُحدّث خريطة قديمة في الخلفية.

استخدم max_weight لتطبيع طبقة الكثافة الموزونة. إذا كانت قيمة truncated هي true، فتتضمن الاستجابة الخلايا الأعلى وزنًا بدلًا من كل الخلايا المنشأة.

تعيد نقطة النهاية 404 عندما لا يكون المنظم قد مكّن show_heatmap، أو أثناء فترة إخفاء النتائج، أو عندما تكون النتائج العامة مقيدة وطالب البيانات ليس مشاركًا.

نتيجة مشارك تفصيلية #

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

تجمع الاستجابة ما يلي:

• صف المشارك في لوحة المتصدرين والمسافة المختارة والترتيب وresult_rank_total.
• بيانات statistics مثل المسافة والمدة والوتيرة أو السرعة والطاقة والخطوات وعدد الأنشطة والأيام النشطة وأطول سلسلة ومتوسط معدل ضربات القلب عند توفره.
• is_own_result الذي يحدد ما إذا كان الصف يعود إلى المشارك المصادق عليه.
• head_to_head المتاح فقط عندما يعرض المشارك نتيجته الخاصة. ويتضمن الترتيب والنسبة المئينية ومقياس الترتيب والفوارق مع المنافسين القريبين والمتصدر ومتوسط جميع المشاركين وصفوف المراكز الثلاثة الأولى.
• activities، وهي قائمة متداخلة ومرقّمة بالصفحات للأنشطة المقبولة والمرئية المحتسبة ضمن النتيجة. يتضمن كل صف البيانات الوصفية الأساسية للتدريب ومتوسط الوتيرة وشكل المسار عند توفره وhas_analytics.

بالنسبة إلى نتيجة ذات مسافة ثابتة، تنتهي قائمة الأنشطة عند النشاط الذي اكتملت فيه المسافة المختارة. ولا تظهر الأنشطة اللاحقة لأنها لم تسهم في تلك النتيجة.

ترقيم صفحات الأنشطة المتداخلة #

تحتوي قائمة الأنشطة على الحقول المعتادة count وnext وprevious وresults، لكنها تستخدم معلمات طلب مخصصة حتى لا تتعارض مع ترقيم الصفحات في المستوى الأعلى:

المعلمة	المعنى
activities_page	رقم الصفحة، بدءًا من 1
activities_per_page	عدد العناصر في الصفحة؛ الافتراضي 25 ويخضع للحد الأقصى في API

أشكال مسارات غير مرتبطة بالموقع #

لا تمثل المسارات في المخطط الزمني للأنشطة إحداثيات جغرافية. ينقل الخادم كل مسار GPS ويغير مقياسه إلى مساحة إحداثيات SVG ثابتة بحجم 158 × 108، ولا يعيد إلا:

• path — بيانات مسار SVG
• start وend — نقاطًا في مساحة الإحداثيات المطبّعة
• point_count — عدد النقاط في الشكل المعاد

لا تتضمن الاستجابة خط العرض أو خط الطول أو الحدود أو المركز المطلقة. ينتج المسار نفسه الشكل ذاته عند نقله إلى موقع آخر، لذا فهو مناسب لصورة مصغرة، لكن لا يمكن رسمه على خريطة جغرافية.

تحليلات كل نشاط #

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

يجب أن يكون النشاط مقبولًا ومرئيًا ومرتبطًا بنتيجة هذا المشارك تحديدًا. تحتوي الاستجابة على بيانات المسافة والمدة والوتيرة والسرعة الأساسية، إلى جانب أي تحليلات يمكن اشتقاقها من تدفقات البيانات المحفوظة:

الكتلة	المحتوى
route	شكل المسار غير المرتبط بالموقع نفسه المستخدم في المخطط الزمني للأنشطة
km_splits	تقسيمات الكيلومترات الكاملة مع تقسيم جزئي أخير اختياري، بما في ذلك علامتا أسرع تقسيم وأبطئه
elevation	ملف ارتفاع منخفض الدقة، والصعود، والهبوط، والحد الأدنى، والحد الأقصى
heart_rate وhr_zones	سلسلة معدل ضربات قلب منخفضة الدقة، والمتوسط، والحد الأقصى، والحد الأقصى المرجعي، والوقت في خمس مناطق
cadence	سلسلة إيقاع منخفضة الدقة ومتوسطها
effort_score	تقدير للجهد مشتق من معدل ضربات القلب

يمكن أن تكون كل كتلة null بصورة مستقلة لأن موفري الخدمات والأجهزة يرسلون تدفقات مختلفة. يوضح has_streams ما إذا كانت هناك تحليلات قابلة للاستخدام للتدفقات. ويحدد x_kind ما إذا كانت قيم x في الرسوم البيانية تمثل المسافة التراكمية أم الوقت المنقضي.

تتوفر الكتل منخفضة الحساسية — شكل المسار والتقسيمات والوتيرة والارتفاع — لأي طالب بيانات يمكنه الوصول إلى النتيجة. أما الكتل الفسيولوجية — معدل ضربات القلب والمناطق والإيقاع والجهد — فتتوفر دائمًا لنتيجة طالب البيانات نفسه متى كان يمكنه الوصول إليها. وبالنسبة إلى نشاط مشارك آخر، لا تُعاد إلا إذا مكّن المنظم show_analytics واستوفى طالب البيانات قواعد رؤية النتائج. وفي الحالات الأخرى تكون هذه الكتل null وتكون قيمة physio_restricted هي true.

قواعد الرؤية والخصوصية #

الإعداد أو الحالة	التأثير
تعطيل show_heatmap	تعيد خريطة الكثافة 404؛ ويبلغ result-settings عن show_heatmap: false
تعطيل show_analytics	تُزال كتل الأنشطة الفسيولوجية للمشاركين الآخرين؛ ولا تتأثر التحليلات المتاحة للنتيجة الخاصة
فترة إخفاء النتائج نشطة	تُخفى تفاصيل نتائج المشاركين؛ وتعيد خريطة الكثافة 404؛ وتكون قيمتا show_heatmap وshow_analytics false
تفعيل hide_results_public	يقتصر المستخدمون الذين سجّلوا الدخول ولم يشاركوا على العدد المعدّ من أعلى النتائج، ولا يمكنهم تحميل خريطة الكثافة أو عرض التحليلات الفسيولوجية للمشاركين الآخرين
التدريب غير مقبول أو غير مرئي	يُحذف من المخطط الزمني ولا يمكن فتحه عبر نقطة نهاية التحليلات

يحتفظ المشاركون في التحدي بإمكانية الوصول إلى النتائج الكاملة خارج فترة إخفاء النتائج. وقد يختلف وصول موظفي المؤسسة عن وصول المشاركين، لكن ينبغي للعملاء دائمًا اتباع القيم الخاصة بطالب البيانات التي يعيدها result-settings/.

ذات صلة #

• نظرة عامة على API العامة
• إعداد العلامة البيضاء والمؤسسات