تطوير تجارب الخطوات باستخدام 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 التي تعمل على تسوية فجوات البيانات المادية تلقائيًا باستخدام إزاحات التوقيت العالمي المتفق عليه (UTC). تعرض عملية التجميع StepsRollupValue الذي يحتوي على الحقل countSum، والذي يمثّل إجمالي الخطوات المتراكمة في اليوم المطلوب.

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

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

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

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

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

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

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

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

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

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

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

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

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

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