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

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