פיתוח חוויות של צעדים באמצעות Google Health API

‫Google Health API עוקב אחרי נתוני פעילות וצעדים של משתמשים באמצעות steps סוג הנתונים interval. מספר הצעדים הוא מדד בסיסי של פעילות גופנית יומית, שעוזר למפתחים לעקוב אחרי ההתקדמות בכושר, לחשב את הוצאת האנרגיה וליצור סיכומים יומיים של פעילות גופנית שמוצגים למשתמשים.

כדי לספק למשתמשים את חוויית השימוש הטובה ביותר, חשוב להבין איך לקרוא את מדדי מספר הצעדים באפליקציה ולבנות אותם.

סוגי נתונים נתמכים

ה-API תומך בסוג הנתונים הבא למעקב אחר מספר הצעדים:

טבלה: סוגי נתונים של שלבים ב-Google Health API

סוג הנתונים	פעולות זמינות	היקף
שלבים ‫dataType: steps filter parameter: steps סוג הרשומה: מרווח תמיכה ב-Webhook תמיכה באפסים אמיתיים מדריך לשלבים מכשירים תואמים 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 ומציינים את משך הזמן (למשל, 3600s לשעה אחת) באמצעות הפרמטר windowSize.
• כל רשומות הצעדים: משתמשים בנקודת הקצה list כדי לאחזר את רשומות הצעדים הגולמיות והמפורטות ביותר.

נקודות הקצה rollUp,‏ dailyRollUp ו-reconcile מקבלות את הפרמטר dataSourceFamily, שמאפשר לסנן נתונים מקבוצות ספציפיות של מקורות. לפרטים נוספים ולדוגמאות לשימוש, אפשר לעיין בקטע סינון וצבירה לפי משפחת מקורות נתונים במדריך לנקודות קצה.

סנכרון בזמן אמת באמצעות Webhooks

כדי לקבל התראה בזמן אמת כשנתוני צעדים חדשים מיובאים או מסונכרנים, צריך להירשם למינוי של אוסף נתוני סוג הנתונים steps. במקום לבצע סקר של נקודות קצה של REST, אפשר לעדכן באופן דינמי לוחות בקרה בצד הלקוח בתגובה להתראות האלה של webhook. הוראות להגדרת מינויים זמינות במאמר בנושא מינויים ל-Webhook.

טיפול באפסים אמיתיים

‫Google Health API מיישם אפסים אמיתיים כדי לפתור בעיות שקשורות למרווחי זמן של חוסר פעילות. אם משתמש עונד מכשיר מעקב אבל לא הולך במהלך תקופה מסוימת, ה-API מחזיר רשומה למרווח הזמן הזה שמכילה את מקור הנתונים הרגיל ואת חותמת הזמן של המטא-נתונים, אבל לא כוללת את המאפיין count.

כך תוכלו להבחין בין:

• תקופות של חוסר תנועה כשהמכשיר על היד: המשתמש עונד את המכשיר אבל לא הולך. הפונקציה מחזירה רשומות ללא המאפיין count (הפרשנות היא אפס שלבים).
• תקופות שבהן השעון לא על היד: המשתמש לא עונד את המכשיר. הפונקציה לא מחזירה רשומה, ולכן יש פערים גדולים בנתונים.

פרטים נוספים זמינים במדריך בנושא נוכחות נתונים ואפסים אמיתיים.