تطوير تجارب الخطوات باستخدام Google Health API

تتتبّع واجهة Google Health API خطوات المستخدم وبيانات نشاطه باستخدام نوع بيانات الفاصل الزمني steps. يمثّل عدد الخطوات مقياسًا أساسيًا للنشاط البدني اليومي، ما يساعد المطوّرين في تتبُّع مستوى تقدّم اللياقة البدنية واحتساب الطاقة المستهلَكة وإنشاء ملخّصات للنشاط اليومي موجَّهة للمستخدمين.

تعرَّف على كيفية قراءة مقاييس عدد الخطوات وتنظيمها في تطبيقك لتقديم أفضل تجربة للمستخدمين.

أنواع البيانات المتوافقة

تتيح واجهة برمجة التطبيقات استخدام نوع البيانات التالي لتتبُّع عدد الخطوات:

الجدول: أنواع بيانات الخطوات في Google Health API

نوع البيانات	العمليات المتاحة	النطاق
الخطوات dataType: steps filter parameter: steps نوع السجلّ: Interval دقة التخزين: دقيقة واحدة دعم Webhook دعم True zeros دليل الخطوات الأجهزة المتوافقة Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

الإرشادات

عند دمج ميزة تتبُّع الخطوات في تطبيقك، اتّبِع إرشادات التصميم والتنفيذ التالية.

احتساب السرعة والوتيرة

تستخدم واجهة Google Health API صيغًا عادية لاحتساب السرعة والوتيرة:

• السرعة = distance / time(hour)
• مستوى السرعة = time(seconds) / distance

يحدّد العنوان Accept-Language المحدّد في الطلب وحدة المسافة.

ملخّص يومي

لتجميع عدد الخطوات اليومية بدقة أثناء السفر أو تغييرات المنطقة الزمنية أو التوقيت الصيفي، لا تُجرِ عمليات حسابية للمدة من جهة العميل. بدلاً من ذلك، يمكنك الاستعلام عن نقطة النهاية dailyRollUp التي تعمل على تسوية فجوات البيانات المادية تلقائيًا باستخدام إزاحات التوقيت العالمي المنسق. تعرض عملية التجميع StepsRollupValue يحتوي على الحقل countSum، والذي يمثّل إجمالي الخطوات المتراكمة لليوم المطلوب. لمعرفة التفاصيل، يُرجى الاطّلاع على التجميع على مدار أيام التقويم في دليل البيانات المجمّعة.

رسم واجهات المستخدم (التسوية)

عند إنشاء عناصر واجهة المستخدم لعرض بيانات الخطوات، استخدِم نقطة النهاية reconcile. إذا سجّلت مصادر بيانات متعددة (مثل ساعة ذكية وهاتف جوّال) الخطوات في الوقت نفسه، تحلّ نقطة النهاية reconcile التعارضات وتدمج مصادر البيانات لعرض مصدر بيانات واحد متوافق.

للحصول على معلومات حول التعامل مع الفترات المتداخلة من عمليات مزامنة الأجهزة المتصلة وقابلية تغيير الطابع الزمني، يُرجى الاطّلاع على دليل إدارة البيانات.

التتبُّع والمدرّجات التكرارية خلال اليوم

لعرض نشاط المستخدم المفصّل على مدار اليوم (مثل المخططات والرسوم البيانية):

• المدرّجات التكرارية للخطوات بالساعة أو بالدقيقة: يمكنك طلب نقطة النهاية rollUp، مع تحديد المدة (مثل 60s لدقيقة واحدة أو 3600s لساعة واحدة) باستخدام المَعلمة windowSize. بما أنّ بيانات الخطوات يتم تسجيلها على فترات زمنية مدتها دقيقة واحدة (60s)، يجب ضبط windowSize على 60s على الأقل. لا يتم تقسيم إجمالي الدقائق الفردية في الطلبات التي تتضمّن أحجام نوافذ أقل من دقيقة (مثل 10s أو 30s)، بل يتم وضع عدد الدقائق الكاملة في أول مجموعة فرعية مطابقة. لمعرفة التفاصيل، يُرجى الاطّلاع على نافذة التجميع ودقة التخزين.
• جميع سجلّات الخطوات: استخدِم نقطة النهاية list لجلب سجلّات الخطوات الأولية الأكثر دقة.

تقبل نقاط النهاية rollUp وdailyRollUp وreconcile المَعلمة dataSourceFamily، ما يتيح لك فلترة البيانات من مجموعات مصادر معيّنة. لمزيد من التفاصيل وأمثلة على الاستخدام، يُرجى الاطّلاع على قسم الفلترة حسب مجموعة مصادر البيانات في دليل "فلترة البيانات".

المزامنة في الوقت الفعلي باستخدام الردود التلقائية على الويب

اشترِك في مجموعة أنواع بيانات steps لتلقّي إشعارات في الوقت الفعلي عند استيراد بيانات جديدة للخطوات أو مزامنتها. بدلاً من استطلاع نقاط نهاية REST، يمكنك تعديل لوحات البيانات من جهة العميل بشكل ديناميكي استجابةً لإشعارات الويب هوك هذه. للحصول على تفاصيل حول كيفية إعداد الاشتراكات، يُرجى الاطّلاع على اشتراكات الويب هوك.