دليل نقل البيانات

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

تم تصميم الدليل لمساعدة المطوّرين على نقل تطبيقاتهم الحالية التي تستخدم Fitbit Web API إلى Google Health API الجديدة.

لماذا يجب نقل البيانات؟

في ما يلي مزايا استخدام Google Health API:

  • الأمان المحسَّن: الامتثال لأفضل ممارسات الأمان في Google، بما يتوافق مع معايير الأمان والخصوصية والهوية في Google
  • التطابق: يزيل هذا الإصدار عدم التطابق القديم في تنسيقات البيانات والمناطق الزمنية ووحدات القياس ومعالجة الأخطاء، ما يوفّر تجربة أكثر سلاسة للمطوّرين.
  • قابلية التوسّع ومواكبة التغييرات المستقبلية: تم تصميمها لتتوسّع بما يتناسب مع المتطلبات المستقبلية، وتتوافق مع البروتوكولات الحديثة، مثل gRPC.

تسجيل التطبيق

يجب تسجيل جميع تطبيقات Google Health API باستخدام Google Cloud Console التي تعمل كمركز مركزي لإدارة جميع تطبيقات Google.

للحصول على تعليمات حول كيفية تسجيل تطبيقك، اتّبِع الخطوات الواردة في بدء الاستخدام. في ما يلي الاختلافات التي ستلاحظها عند تسجيل تطبيقاتك.

Fitbit Web API Google Health API
الروابط المتاحة للجميع https://dev.fitbit.com/apps https://console.cloud.google.com
إضافة تطبيق جديد اضغط على تسجيل تطبيق جديد.
  1. إنشاء مشروع على Google Cloud
  2. تفعيل Google Health API
المعلومات الأساسية الحقول المطلوب إكمالها:
  • اسم التطبيق
  • الوصف
  • عنوان URL للموقع الإلكتروني الخاص بالتطبيق
  • المؤسسة
  • عنوان URL للموقع الإلكتروني للمؤسسة
  • عنوان URL لبنود الخدمة
  • عنوان URL "سياسة الخصوصية"
 الحقول المطلوب إكمالها:
  • اسم التطبيق
  • البريد الإلكتروني للحصول على الدعم
  • الجمهور (داخلي أو خارجي)
  • عنوان البريد الإلكتروني الخاص بجهة الاتصال
  • رمز الشعار
  • عنوان URL للموقع الإلكتروني الخاص بالتطبيق
  • عنوان URL لسياسة الخصوصية
  • عنوان URL لبنود الخدمة
  • النطاق المسموح به
أنواع التطبيقات على المطوّر اختيار أيّ مما يلي:
  • الخادم
  • العميل
  • التخصيص
  • تطبيق الويب
  • Android
  • إضافة Chrome
  • iOS
  • أجهزة التلفزيون
  • تطبيق لأجهزة الكمبيوتر المكتبي
  • منصّة Universal Windows
معرِّف العميل يتم التسجيل عند حفظ إعدادات التطبيق مسجَّل بشكل منفصل
نوع الوصول يتم التحكّم في إذن القراءة والكتابة على مستوى التطبيق يتم التحكّم في إذن القراءة والكتابة على مستوى النطاق
عناوين URL إضافية
  • عنوان URL لإعادة التوجيه: الموقع الإلكتروني الذي تتم إعادة توجيه المستخدمين إليه بعد منحهم الإذن بالنطاقات
  • مصادر JavaScript المسموح بها: مصدر HTTP الذي يستضيف تطبيق الويب
  • عنوان URL لإعادة التوجيه: الموقع الإلكتروني الذي تتم إعادة توجيه المستخدمين إليه بعد منحهم الإذن بالنطاقات

تنفيذ OAuth

تتوافق تطبيقات Google Health API فقط مع مكتبات عميل Google OAuth2. تتوفّر مكتبات العملاء للأُطر الشائعة، ما يسهّل تنفيذ OAuth 2.0. في ما يلي الاختلافات بين مكتبات Google OAuth2 ومكتبات OAuth2 المفتوحة المصدر:

Fitbit Web API Google Health API
التوافق مع مكتبة OAuth2 برنامج مفتوح المصدر مكتبات عملاء Google OAuth2
الوظائف عدم الاتساق على مستوى المنصات متوافق مع جميع المنصات
عنوان URL للتفويض https://www.fitbit.com/oauth2/authorize https://accounts.google.com/o/oauth2/v2/auth
عنوان URL للرمز المميز https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
مدة صلاحية رمز الدخول المميز 8 ساعات ساعة واحدة
حجم رمز الدخول 1024 بايت ‫2048 بايت
إعادة تحميل الرمز المميز يتم إنشاء رموز مميزة لإعادة التحقّق من الصحة عند استخدام مسار منح رمز التفويض. يمكن إنشاء رمز مميّز واحد لإعادة التحميل لكل مستخدم. لا تنتهي صلاحية الرموز المميزة أبدًا، ولا يمكن استخدامها إلا مرة واحدة. لإنشاء رمز مميّز لإعادة التحميل، يجب أن يحتوي سلسلة التفويض على مَعلمة طلب البحث "access_type=offline". يمكن إنشاء رموز مميزة متعددة لإعادة التحميل لمستخدم واحد. يمكن أن تكون رموز إعادة التحميل مستندة إلى الوقت. ستنتهي صلاحية الرموز إذا لم يتم استخدامها خلال 6 أشهر، أو إذا منح المستخدم إذن الوصول لفترة زمنية محدّدة، أو إذا كان التطبيق في وضع "الاختبار". يمكنك الاطّلاع على انتهاء صلاحية الرمز المميز لإعادة التحميل لمزيد من التفاصيل.
ردّ الرمز المميز تحتوي استجابة JSON على ما يلي:
  • رمز الدخول
  • انتهاء صلاحية رمز الدخول
  • النطاقات
  • نوع الرمز المميّز
  • الرمز المميز لإعادة التحميل
  • رقم تعريف المستخدم
 تحتوي استجابة JSON على ما يلي:
  • رمز الدخول
  • انتهاء صلاحية رمز الدخول
  • النطاقات
  • نوع الرمز المميّز
  • الرمز المميز لإعادة التحميل

للحصول على رقم تعريف المستخدم، استخدِم نقطة النهاية users.getIdentity.

على مستخدمي Fitbit إعادة الموافقة على عملية الدمج الجديدة لأنّ تطبيقك يستخدم مكتبة OAuth مختلفة. لا يمكن نقل رموز الدخول ورموز التحديث إلى Google Health API واستخدامها.

المستويات

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

نطاقات Google Health API هي عناوين URL تستخدم HTTP تبدأ بـ https://www.googleapis.com/auth/googlehealth.{scope}. على سبيل المثال، https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

تعيينات النطاق

في ما يلي كيفية ربط نطاقات Fitbit Web API بنطاقات Google Health API:

الجدول: عمليات ربط نطاقات Fitbit Web API بنطاقات Google Health API
نطاقات Fitbit Web API نطاقات Google Health API
النشاط ‎.activity_and_fitness
.activity_and_fitness.readonly
cardio_fitness ‎.activity_and_fitness
.activity_and_fitness.readonly
معدل نبضات القلب .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
الموقع ‎.location.readonly
المعلومات الغذائية .nutrition
.nutrition.readonly
oxygen_saturation .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
الملف الشخصي .profile
.profile.readonly
respiratory_rate .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
الإعدادات .settings
.settings.readonly
النوم .sleep
.sleep.readonly
درجة الحرارة .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
الوزن .health_metrics_and_measurements
.health_metrics_and_measurements.readonly

أنواع البيانات

في ما يلي قائمة بأنواع البيانات في Google Health API وكيفية ربطها بواجهة Fitbit Web API.

الجدول: عمليات ربط أنواع البيانات بين Fitbit Web API وGoogle Health API
نوع بيانات Fitbit Web API نوع بيانات Google Health API
  رقم تعريف نقطة النهاية
دقائق منطقة نشطة دقائق نطاق النشاط
  active-zone-minutes
يحتوي على تغييرات في مستويات نشاط المستخدم مستوى النشاط
  activity-level
الارتفاع الارتفاع
  altitude
نسبة الدهون بالجسم دهون الجسم
  body-fat
caloriesOut في كل نطاق من نطاقات معدّل نبضات القلب السعرات الحرارية في منطقة معدل ضربات القلب
  calories-in-heart-rate-zone
ملخّص مقياس HRV تغيُّر معدّل نبضات القلب اليومي
  daily-heart-rate-variability
ملخّص نسبة الأكسجين بالدم تشبّع الأكسجين اليومي
  daily-oxygen-saturation
معدّل النبض أثناء الراحة معدّل النبض أثناء الراحة يوميًا
  daily-resting-heart-rate
درجة حرارة الجلد القيم المشتقة لدرجة حرارة الجسم أثناء النوم
  daily-sleep-temperature-derivations
المسافة المسافة
  distance
النشاط المسجّل ممارسة التمارين الرياضية
  exercise
الطوابق الطوابق
  floors
معدّل نبضات القلب معدّل نبضات القلب
  heart-rate
معدّل ضربات القلب المتغير خلال اليوم تغيُّر معدّل نبضات القلب
  heart-rate-variability
نسبة الأكسجين بالدم خلال اليوم تشبّع الأكسجين
  oxygen-saturation
قيمة الحدّ الأقصى لاستهلاك الأكسجين عند الجري Run VO2 Max
  run-vo2-max
سلسلة الوقت للنشاط البدني بالدقائق (الجلوس) فترة الخمول
  sedentary-period
النوم النوم
  sleep
الخطوات الخطوات
  steps
النشاط caloriesOut إجمالي السعرات الحرارية
  total-calories
قيمة السعة القصوى للأكسجين السعة القصوى للأكسجين
  vo2-max
الوزن الوزن
  weight

نقاط النهاية

تستخدم نقاط نهاية REST بنية متسقة لجميع أنواع البيانات.

  • نقطة نهاية الخدمة: يتغيّر عنوان URL الأساسي الذي يستخدم HTTP إلى https://health.googleapis.com.
  • بنية نقطة النهاية: تتيح Google Health API عددًا محدودًا من نقاط النهاية التي يمكن استخدامها مع معظم أنواع البيانات المتوافقة. يوفّر ذلك بنية متسقة لجميع أنواع البيانات ويسهّل استخدام نقاط النهاية.
  • معرّف المستخدم: يجب تحديد معرّف المستخدم أو me في بنية نقطة النهاية. عند استخدامي، يتم استنتاج رقم تعريف المستخدم من رمز الدخول المميز.

مثال: في ما يلي مثال على نقطة نهاية GET Profile التي يتم استدعاؤها باستخدام Google Health API

GET https://health.googleapis.com/v4/users/me/profile

تعيينات نقاط النهاية

راجِع جدول أنواع البيانات المتاحة للاطّلاع على قائمة بأنواع البيانات المتاحة وطُرق واجهة برمجة التطبيقات التي تتوافق معها.

نوع نقطة نهاية Fitbit Web API Google Health API
GET (Log | Summary | Daily Summary) where you are requesting a single day of data طريقة dailyRollup مع windowSize = يوم واحد
‫GET (خلال اليوم) حيث تطلب بيانات تفصيلية طريقة القائمة
GET (سلسلة زمنية) حسب التاريخ أو الفاصل الزمني طريقة rollUp أو dailyRollUp التي تتضمّن نطاقًا زمنيًا
GET (قائمة السجلّ) طريقة القائمة
إنشاء سجلات وتعديلها طريقة patch
حذف السجلات طريقة batchDelete
GET Profile تعرض الدالة users.getProfile معلومات المستخدم المحدّدة تعرض الدالة
users.getSettings وحدات المستخدم والمناطق الزمنية
تعديل الملف الشخصي تعدّل الدالة users.updateProfile المعلومات المحدّدة للمستخدم تعدّل الدالة
users.updateSettings الوحدات والمناطق الزمنية للمستخدم
الحصول على رقم تعريف المستخدم تعرض الدالة users.getIdentity معرّف المستخدم القديم في Fitbit ومعرّف المستخدم في Google.

نقل المستخدمين

إنّ نقل البيانات من Fitbit Web API إلى Google Health API ليس مجرّد تحديث فني. على المستخدمين إعادة تقديم موافقتهم على عملية الدمج الجديدة بسبب تغيير مكتبة OAuth. لا يمكن نقل رموز الدخول ورموز إعادة التحميل إلى Google Health API واستخدامها. للمساعدة في الحفاظ على المستخدمين أثناء عملية نقل البيانات، إليك بعض الاقتراحات الفنية والاستراتيجية لضمان نجاح عملية نقل البيانات.

استراتيجية المكتبة المزدوجة

بما أنّ واجهة Fitbit Web API وGoogle Health API تستخدمان مكتبات مختلفة من OAuth2، عليك إدارة فترة "ربط" تتضمّن المكتبتين في قاعدة الرموز البرمجية.

إدارة التفويض المتزامن

  • تغليف العملاء: أنشئ طبقة تجريد أو واجهة لـ "خدمة الصحة". يتيح ذلك لبقية تطبيقك طلب البيانات بدون معرفة المكتبة النشطة (بروتوكول OAuth من Fitbit أو بروتوكول OAuth من Google) للمستخدم المحدّد.
  • تعديل مخطط قاعدة البيانات: عدِّل جدول المستخدمين ليشمل علامة oauth_type. على سبيل المثال، استخدِم fitbit لبروتوكول OAuth من Fitbit وgoogle لبروتوكول OAuth من Google.
    • المستخدمون الجدد: يتم تلقائيًا استخدام Google Health API ومكتبة Google OAuth. اضبط قيمة oauth_type على google.
    • المستخدمون الحاليون: سيتم الاحتفاظ بهم على Fitbit Web API إلى أن يكملوا عملية إعادة الموافقة. اضبط قيمة oauth_type على fitbit.

مسار إعادة الحصول على الموافقة "Step-Up"

بدلاً من فرض تسجيل الخروج، استخدِم أسلوب التفويض المتزايد:

  1. رصد الرمز المميز المفتوح المصدر في Fitbit: عندما يفتح مستخدم Fitbit Web API التطبيق، يتم إرسال إشعار "تحديث الخدمة".
  2. بدء عملية Google OAuth: عندما ينقر المستخدم على "تعديل"، ابدأ عملية مكتبة OAuth2 من Google.
  3. الاستبدال والإبطال: بعد تلقّي رمز Google OAuth المميّز بنجاح، احفظه في الملف الشخصي للمستخدم، وعدِّل oauth_type من fitbit إلى google، وأبطِل (إذا أمكن) رمز fitbit القديم آليًا للحفاظ على أمان الملف الشخصي للمستخدم.

زيادة معدّل الاحتفاظ بالمستخدمين إلى أقصى حد

تُعد إعادة الحصول على الموافقة "منطقة الخطر" بالنسبة إلى معدّل التوقّف عن استخدام الخدمة. لمنع المستخدمين من التوقّف عن استخدام التطبيق، اتّبِع أفضل الممارسات التالية المتعلّقة بتجربة المستخدم:

التواصل الذي يركّز على القيمة

لا تبدأ رسالتك بعبارة "عدّلنا واجهة برمجة التطبيقات". إليك المزايا الرئيسية للنظام الجديد الذي تدعمه Google:

  • الأمان المحسّن: أشر إلى ميزات الحماية الرائدة التي يقدّمها حساب Google، مثل المصادقة الثنائية.
  • الموثوقية: أوقات مزامنة أسرع واتصالات بيانات أكثر استقرارًا
  • حظر الميزات: إبلاغ المستخدمين بلطف بأنّ الميزات الجديدة وأنواع البيانات تتطلّب التحديث.

التوقيت الذكي

  • عدم مقاطعة المهام المهمة: لا تعرض أبدًا شاشة إعادة الموافقة أثناء ممارسة المستخدم للتمارين الرياضية أو تسجيله معلومات عن الطعام.
  • مرحلة "التذكير": خلال أول 30 يومًا، استخدِم بانر يمكن إغلاقه.
  • مرحلة "الإيقاف النهائي": لن يصبح الحصول على الموافقة مجددًا إلزاميًا إلا بعد عدة أسابيع من التحذيرات، وذلك بالتزامن مع المواعيد النهائية الرسمية لإيقاف واجهة Fitbit Web API نهائيًا.

مقارنة مسار النقل

يساعد التمييز المرئي الواضح بين المسارين القديم والجديد المطوّرين على فهم موضع تفرّع المنطق.

الميزة Fitbit Web API (الإصدار القديم) Google Health API (Google-Identity)
مكتبة المصادقة البرامج المفتوحة المصدر العادية خدمات Google Identity Services (GIS) / Google Auth
حسابات المستخدمين بيانات اعتماد Fitbit القديمة حساب Google
نوع الرمز المميز الوصول إلى بيانات Fitbit وتحديثها رموز الدخول/إعادة التحميل الصادرة عن Google
إدارة النطاق الأذونات الواسعة أذونات دقيقة / تدريجية

التعامل مع الفروق الدقيقة في عملية نقل الحساب

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

  • التحقّق من صلاحية الرمز المميّز: استخدِم backgroundworker للتحقّق مما إذا كانت الرموز المميّزة الخاصة بـ Fitbit تتسبّب في ظهور أخطاء "غير مصرّح به". قد يشير ذلك إلى أنّ المستخدم نقل بيانات حسابه ولكن تطبيقك لم يلحق بذلك.
  • التعطُّل السلس: في حال تعذُّر تنفيذ طلب Fitbit OAuth، عليك إعادة توجيه المستخدم إلى صفحة مخصّصة بعنوان "إعادة ربط حساب Fitbit" تستخدم تحديدًا مسار Google OAuth الجديد.

مثال على الرمز

لنقل البيانات من واجهة Fitbit Web API القديمة إلى Google Health API، عليك الانتقال من مكتبات OAuth2 العامة إلى Google Auth Library. في ما يلي اقتراح بشأن التصميم وتنفيذ رمز زائف مكتوب بلغة JavaScript للتعامل مع حالة "المكتبة المزدوجة".

1. "التبديل بين البرامج الوسيطة"

بما أنّه لا يمكنك نقل جميع المستخدمين في وقت واحد، يجب أن تحدّد الخلفية المكتبة التي سيتم استخدامها استنادًا إلى قيمة apiVersion الحالية للمستخدم والمخزّنة في قاعدة البيانات.

التنفيذ

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. نقل مسار تجربة المستخدم

لتحقيق الحد الأقصى من الاحتفاظ بالمستخدمين، استخدِم نمط "المقاطعة والترقية". يضمن ذلك عدم اضطرار المستخدم إلى تسجيل الدخول مرة أخرى إلا بعد أن يتفاعل مع التطبيق.

منطق إعادة التوجيه

عندما يستخدم أحد مستخدمي Fitbit Web API ميزة معيّنة، ابدأ عملية نقل البيانات باتّباع الخطوات التالية:

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3- عمليات النقل الفنية الرئيسية

عند كتابة نصوص برامج نقل بيانات JavaScript، يجب مراعاة هذه الاختلافات:

الميزة Fitbit Web API (الإصدار القديم) Google Health API (Google-Identity)
نقطة نهاية الرمز المميز https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
مكتبة المصادقة البرامج المفتوحة المصدر العادية Google Auth
النطاق النشاط https://www.googleapis.com/auth/googlehealth.activity_and_fitness
رقم تعريف المستخدم رقم التعريف المشفّر في Fitbit الذي تم عرضه في استجابة /oauth2/token رقم تعريف المستخدم الذي تم إرجاعه من نقطة النهاية users.getIdentity

4. قائمة التحقّق من الاحتفاظ بالبيانات

  • استمرار الجلسة: لا تمحُ جلسة واجهة برمجة تطبيقات Fitbit Web القديمة للمستخدم إلا بعد إثبات صحة رمز access_token لواجهة Google Health API بنجاح وحفظه في قاعدة البيانات.
  • الإبطال التلقائي: بعد اكتمال عملية نقل البيانات إلى Google Health API، استخدِم طلب POST إلى نقطة نهاية الإبطال القديمة في Fitbit: https://api.fitbit.com/oauth2/revoke. ويضمن ذلك عدم ظهور أذونات التطبيق "المكرّرة" للمستخدم في إعدادات Fitbit.
  • التعامل مع الأخطاء: إذا عرضت مكالمة Fitbit الرمز 401 Unauthorized، يجب إعادة التوجيه تلقائيًا إلى عملية Google OAuth بدلاً من عرض رسالة خطأ.