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

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

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

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

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

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

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

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

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