שיפור התאימות של האפליקציה במכשירי Wear OS

ממשק ה-API של Wear Health Services‏ (WHS) הוא רכיב חובה בכל המכשירים שמופעלת בהם מערכת Wear OS מגרסה 3 ואילך, כי הוא מספק פלטפורמת אינטגרציה עקבית למפתחים של אפליקציות בריאות וכושר. כדאי לבנות את האפליקציה כך שהיא תותאם בצורה חלקה למכשירים רבים ולתכונות השונות שלהם, כדי לשמור על תאימות בין המכשירים ולמנוע בעיות בחוויית המשתמש. כדי לעשות זאת, צריך להצהיר על תלות רק עבור הלקוחות שהאפליקציה משתמשת בהם. בנוסף, אפשרו לאפליקציה להציג או להסיר מדדים מתקדמים אופציונליים בהתאם לזמינות שלהם.

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

במדריך הזה מתוארות ההתנהגויות הצפויות וסוגי הנתונים שנתמכים על ידי לקוחות שונים ב-Wear Health Services.

לקוח של פעילות גופנית

בקטעים הבאים מתוארים סוגי הנתונים וההתנהגויות הצפויות של התג ExerciseClient.

התנהגויות צפויות

בExerciseClient, חלק מסוגי התרגילים תלויים בזמינות של סוגי נתונים מסוימים. לדוגמה, תרגילי כיסא גלגלים זמינים רק אם יש תמיכה בדחיפות של כיסא גלגלים. אפשר להפעיל ולהשבית את האפשרויות האלה בהתאם לזמינות שלהן במכשיר מסוים.

רוב סוגי הנתונים של פעילות גופנית נדגמים ומועברים במרווחי זמן של שנייה אחת, עם כמה חריגים:

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

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

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

סוגי הנתונים

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

סוגי נתונים מובטחים של פעילות גופנית

סוגי הנתונים הבאים של פעילות גופנית זמינים בכל המכשירים.

• לסוגי הנתונים לדוגמה יש סוג נתונים תואם של _STATS שמחזיר ערכים מינימליים, מקסימליים וממוצעים מהתרגיל. לדוגמה, אפשר לשלוף נתונים סטטיסטיים של PACE באמצעות סוג הנתונים PACE_STATS.
• לסוגי נתונים של מרווחי זמן יש סוג נתונים תואם של ‎_TOTAL שמחזיר את הערך המצטבר מהפעילות. לדוגמה, אפשר לשלוף נתונים סטטיסטיים של DISTANCE באמצעות סוג הנתונים DISTANCE_TOTAL.

מדד	הנתונים הצפויים	הערות לגבי התנהגויות צפויות
HEART_RATE_BPM	פעימות לדקה [סוג נתונים: Double]	בכל המכשירים, הדופק נמדד פעם בשנייה במהלך האימון. חלק מהמכשירים מדווחים על ערך של פעימות בדקה בכל שנייה. חלק מהמכשירים מדווחים על BPM רק אם הוא השתנה מאז הערך הקודם. אל תצפו לקבל ערך של פעימות בדקה (BPM) בכל שנייה בכל המכשירים.
מיקום	קו רוחב וקו אורך [סוג נתונים: Double]	נתוני המיקום מבוססים רק על ה-GPS של השעון. אל תצפו שנתוני המיקום יגיעו מספק המיקום המשולב או משירותים אחרים של Android). כל נקודת נתונים כוללת גם ערך דיוק (שנקרא גם שגיאת מיקום אופקי) וזמינות.
צעדים	[סוג הנתונים: Long]	מספר הצעדים הוא סכום מצטבר לאורך משך האימון, לא כולל הזמן שבו האימון מושהה
DISTANCE	מטרים [סוג נתונים: Double]	מחושב ממיקום מבוסס-GPS כשהוא זמין, ומצעדים אחרת. הסכום הכולל מתייחס לכל משך התרגיל, לא כולל הזמן שבו התרגיל מושהה.
מהירות	‫[meters / second] ‫[סוג נתונים: Double]	הפונקציה מחזירה את הערכים המינימליים, המקסימליים והממוצעים. הנתונים האלה מתייחסים למשך התרגיל, לא כולל הזמן שבו התרגיל מושהה.
קצב	‫[seconds / meter] ‫[סוג נתונים: Double]	ערך ברירת המחדל הוא 0 אם המהירות היא 0. החישוב של הממוצעים מתבצע על משך התרגיל, לא כולל הזמן שבו התרגיל מושהה.
ELEVATION_GAIN	מטרים. ‫[סוג נתונים: Double]	שינויים חיוביים בגובה. הנתון הכולל מדווח על פני משך האימון, לא כולל הזמן שבו האימון מושהה.
TOTAL_CALORIES	קק"ל [סוג נתונים: Double]	קלוריות שנשרפו בזמן פעילות, שנוספו לקצב חילוף החומרים הבסיסי. הערך של הקלוריות שמוצג כאן מחושב על סמך הגובה, המשקל, הגיל והמגדר של המשתמש, כפי שצוין בהגדרות המערכת. הקלוריות לא כוללות נתוני פרופיל משתמש שנאספו באפליקציה. הסכום הכולל שמוצג הוא לכל משך האימון, לא כולל הזמן שבו האימון מושהה.

סוגי נתונים אופציונליים של פעילות גופנית

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

בהמשך מפורטות דוגמאות לסוגי נתונים אופציונליים. זוהי רשימה חלקית בלבד:

מדד	הנתונים הצפויים	הערות לגבי התנהגויות צפויות
ABSOLUTE_ELEVATION	‫[סוג נתונים: Double]
ELEVATION_LOSS	מטרים [סוג נתונים: Double]	שינויים שליליים בגובה. הערך חיובי. לדוגמה, אם יש ירידה בגובה של מטר אחד, הפונקציה מחזירה 1 ולא ‎-1.
STEPS_PER_MINUTE	[סוג הנתונים: Long]
WHEELCHAIR_PUSHES	[סוג הנתונים: Long]	מספר הדחיפות של כיסא הגלגלים לשימוש בתרגילים שמבוססים על כיסא גלגלים.
REP_COUNT	[סוג הנתונים: Long]
SWIM_STROKE_COUNT	[סוג הנתונים: Long]
SWIM_LAP_COUNT	[סוג הנתונים: Long]

סוגי נתונים לכל תרגיל

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

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

הנה כמה דוגמאות:

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

Passive Monitoring Client

סוגי הנתונים הבאים נדרשים בכל המכשירים שמריצים Wear OS כדי לתמוך באפליקציות שעוקבות באופן פסיבי אחרי נתוני בריאות כמו הדופק ומספר הצעדים. כל אחד מסוגי הנתונים האלה צריך להיות נגזר אך ורק מנתונים שנוצרו על ידי חיישנים בשעון.

התנהגויות צפויות

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

אל תניחו שיש מרווחי זמן מוגדרים מראש או צפויים ליצירת קבוצות (batching) של נתונים מסוגים שונים.

סוגי נתונים של מעקב פסיבי

מדד	הנתונים הצפויים	הערות
HEART_RATE_BPM	פעימות לדקה [סוג נתונים: Double]	יכול להיות שהמכשירים יחזירו קריאות של קצב הלב במרווחי זמן שונים. יכול להיות שחלק מהמכשירים יקראו את הנתונים כל שנייה. יכול להיות שמכשירים אחרים יקראו את הנתונים כל עשר דקות. האפליקציות לא יכולות לגשת למרווחי הזמן האלה. אפליקציות צריכות להתאים את עצמן בצורה חלקה למרווחי דגימה שונים.
STEPS_DAILY/STEPS	[סוג הנתונים: Long]	מספר הצעדים היומי הוא המספר הכולל של הצעדים שצעדתם מאז האיפוס האחרון, שמתבצע על ידי WHS בחצות. הנתון הזה כולל את כל הפעולות שבוצעו בזמן שהתרגיל הפעיל היה בהשהיה. המדד Steps הוא דלתא גרנולרית מאז הבדיקה האחרונה.
DISTANCE_DAILY/DISTANCE	מטרים [סוג נתונים: Double]	מחושב מנתוני מד התאוצה או מספר הצעדים. אל תבצעו חישובים במהלך השימוש ב-GPS כדי לוודא שמשתמשים שהשביתו את שירותי המיקום עדיין יוכלו לקבל נתונים מדויקים של מספר הצעדים.
מהירות	‫[meters / second] ‫[סוג נתונים: Double]
CALORIES_DAILY	קק"ל [סוג נתונים: Double]	קלוריות ליום, כולל קלוריות בפעילות וקצב חילוף חומרים בסיסי (BMR). נתון הקלוריות שמוצג כאן מתייחס לגובה, למשקל, לגיל ולמגדר של המשתמש, כפי שצוין בהגדרות המערכת. הערך הקלורי לא מותאם לפי נתוני פרופיל משתמש שנאספים באפליקציה.
RUNNING_STEPS (אופציונלי)	[סוג הנתונים: Long]	ההפרש במספר הצעדים במהלך אימון ובזמנים אחרים. לעקוב אחרי שניהם בו-זמנית.
WALKING_STEPS (אופציונלי)	[סוג הנתונים: Long]
ELEVATION_GAIN	מטרים [סוג נתונים: Double]	כולל רק את השינויים החיוביים בגובה
ELEVATION_LOSS	מטרים [סוג נתונים: Double]	כולל רק את הדלתאות השליליות בגובה
FLOORS_DAILY	‫[סוג נתונים: Double]	יכול להיות שיוצגו קומות חלקיות

יעדים יומיים של מעקב פסיבי

מדד	הנתונים הצפויים	הערות
STEPS_DAILY	[סוג הנתונים: Long]	המספר היומי של הצעדים, כולל צעדים שנעשו בזמן שהאימון הפעיל היה מושהה, הוא המספר הכולל של הצעדים שנעשו מאז האיפוס האחרון. הזמן שמוקצב לשימוש מתאפס בחצות.
FLOORS_DAILY	‫[סוג נתונים: Double]	יכול להיות שיוצגו כחלקים של מדרגות.
CALORIES_DAILY	קק"ל [סוג נתונים: Double]	קלוריות ליום, כולל קלוריות בפעילות ו-BMR.
DISTANCE_DAILY	מטרים [סוג נתונים: Double]	מחושב ממד התאוצה או ממספר הצעדים. אל תשתמשו ב-GPS כדי לחשב את הנתון הזה, כדי שמשתמשים שהשביתו את שירותי המיקום עדיין יוכלו לקבל נתונים מדויקים של מספר הצעדים.
DAILY_ELEVATION_GAIN	מטרים [סוג נתונים: Double]	כולל רק את השינויים החיוביים בגובה

MeasureClient

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

התנהגויות צפויות

יש כמה דברים דומים בין MeasureClient לבין PassiveClient. שניהם מספקים נתונים סטטיסטיים לגבי הבריאות שלא קשורים לפעילות גופנית. אפשר להשתמש בשני המדדים כדי למדוד את קצב הלב, אבל ההבדל העיקרי הוא שבמדד MeasureClient נכללת זמינות הנתונים של קצב הלב, ובמדד PassiveClient לא נכלל מידע על הזמינות.

סוגי הנתונים

מדד	הנתונים הצפויים	הערות
HEART_RATE_BPM	פעימות לדקה [סוג נתונים: Double]	כולל גם זמינות

תכונות נתמכות

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

טריגרים לאירועים

כל המכשירים תומכים בטריגרים הנפוצים הבאים:

• יעדים יומיים למרחק ולצעדים
• יעדי פעילות גופנית של צעדים, מרחק ומשך זמן.

יכול להיות שבמכשירים אחרים יש תמיכה בהפעלת אירועים מתקדמת יותר. דוגמאות:

• ספירת הקפות בשחייה
• יעדי פעילות גופנית לקלוריות שנשרפו
• יעדים של תרגילים למהירות מיידית

מדינות

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

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

התראות לגבי תקינות במעקב פסיבי

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