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

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

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

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

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

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

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

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

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

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

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

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

סוגי הנתונים

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

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

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

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

טבלה 1: סוגי נתוני פעילות גופנית שזמינים בכל המכשירים

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

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

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

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

טבלה 2: דוגמאות לסוגים אופציונליים של נתוני פעילות גופנית

מדד	הנתונים הצפויים	הערות לגבי התנהגויות צפויות
ABSOLUTE_ELEVATION	‫[Data type: 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 ונשלחות באצווה לשירותי הבריאות. התוצאות האלה מוחזרות במרווחי זמן שונים, בהתאם להתנהגות המערכת. דוגמאות לכך הן החזרת קבוצות של נתונים כשמאגרי החיישנים מלאים, או כשהמשתמש מקיים אינטראקציה עם המסך.

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

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

טבלה 3: סוגי נתונים נדרשים של מעקב פסיבי למכשירי Wear OS

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

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

טבלה 4: מדדי יעדים יומיים של מעקב פסיבי

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

MeasureClient

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

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

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

סוגי הנתונים

MeasureClient

טבלה 5: סוגי נתונים

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

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

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

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

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

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

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

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

מדינות

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

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

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

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