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

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

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

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

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

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

סוג הנתונים   dataType הפרמטר   filter	סוג הרשומה	פעולות זמינות	היקף	תמיכה ב-Webhook	תמיכה בערכים אפסיים אמיתיים
שלבים   steps   steps	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

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

היקפים נדרשים

כדי לגשת לסוג הנתונים הזה, האפליקציה צריכה לבקש את היקפי ההרשאות הבאים ל-OAuth:

• קריאה: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• כתיבה: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly

הנחיות

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

סקירה יומית

כדי לצבור נתונים מדויקים של מספר הצעדים היומיים במקרים של נסיעות, שינויים באזור הזמן או מעבר לשעון קיץ, אל תבצעו חישובי משך בצד הלקוח. במקום זאת, אפשר לשלוח שאילתה לנקודת הקצה dailyRollUp, שמתקנת באופן אוטומטי את הפערים בנתונים הפיזיים באמצעות ההפרשים מ-UTC. הסיכום מחזיר StepsRollupValue שמכיל את השדה countSum, שמייצג את מספר הצעדים המצטבר הכולל במהלך היום המבוקש.

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

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

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

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

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

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

סנכרון בזמן אמת באמצעות ווּבְּהוּקים

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

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

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