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

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

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

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

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

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

סוג הנתונים	פעולות זמינות	היקף
השלבים 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, שמייצג את מספר הצעדים הכולל שנצברו ביום המבוקש. פרטים נוספים זמינים במאמר צבירת נתונים לפי ימים קלנדריים במדריך לצבירת נתונים.

ממשקי משתמש לציור (התאמה)

כשיוצרים רכיבים בממשק המשתמש כדי להציג נתוני צעדים, משתמשים בנקודת הקצה (endpoint) reconcile. אם כמה מקורות נתונים (כמו שעון חכם וטלפון נייד) תיעדו צעדים באותו זמן, נקודת הקצה reconcile פותרת את ההתנגשויות וממזגת את הנתונים כדי להחזיר מקור נתונים אחד ומותאם.

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

מעקב והיסטוגרמות במהלך היום

כדי להציג פעילות מפורטת של המשתמשים לאורך היום (כמו תרשימים וגרפים):

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

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

סנכרון בזמן אמת באמצעות תגובות לפעולה מאתר אחר (webhook)

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