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

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

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

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

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

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

نوع البيانات	العمليات المتاحة	النطاق
الخطوات نوع البيانات: steps مَعلمة الفلتر: steps نوع السجلّ: الفاصل الزمني إتاحة الويب هوك إتاحة القيم الصفرية دليل الخطوات الأجهزة المتوافقة 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، مع تحديد المدة (مثلاً 3600s لمدة ساعة واحدة) باستخدام المَعلمة windowSize.
• جميع سجلّات الخطوات: استخدِم نقطة النهاية list لجلب سجلّات الخطوات الأولية الأكثر تفصيلاً.

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

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

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

التعامل مع الأصفار الحقيقية

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

يتيح لك ذلك التمييز بين ما يلي:

• فترات الثبات على المعصم: يرتدي المستخدم الجهاز ولكنّه لا يمشي. سيؤدي ذلك إلى عرض سجلّات بدون السمة count (يتم تفسيرها على أنّها صفر خطوة).
• فترات عدم ارتداء الساعة: لا يرتدي المستخدم الجهاز. ولا يُرجع ذلك أي سجلّ، ما يؤدي إلى حدوث فجوات كبيرة في البيانات.

راجِع دليل توفر البيانات والأصفار الحقيقية لمزيد من التفاصيل.