פיתוח חוויות אימון באמצעות Google Health API

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

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

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

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

טבלה: סוגי נתונים של אימונים ב-Google Health API
סוג הנתונים
  dataType הפרמטר
  filter		 סוג
הרשומה		 פעולות
זמינות		 היקף תמיכה ב-Webhook
 תמיכה באפסים אמיתיים
תרגיל
  exercise
  exercise 		סשן list, get, reconcile, create, update, batchDelete activity_and_fitness

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

בטבלה הבאה מפורטים השדות באובייקט metricsSummary של סוג הנתונים exercise, והמיפוי שלהם לסוגי הנתונים המתאימים של טלמטריה גולמית ב-Google Health API:

שדה סיכום (metricsSummary) שם סוג הנתונים של טלמטרייה במהלך היום מזהה סוג נתוני טלמטריה של API
caloriesKcal אנרגיה שנשרפה בזמן פעילות active-energy-burned
distanceMillimeters מרחק distance
steps שלבים steps
averageHeartRateBeatsPerMinute דופק heart-rate
activeZoneMinutes דקות טווח דופק active-zone-minutes

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

אימונים

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

מאפייני סשן

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

  • זמן הסשן (interval): שעת ההתחלה ושעת הסיום של אימון כולל, יחד עם ההפרשים מאזור הזמן שהיו פעילים בנקודות הזמן האלה.
  • סוג הפעילות (exerciseType): קטגוריית הפעילות שבוצעה (למשל RUNNING,‏ WALKING,‏ BIKING או AEROBIC_WORKOUT). צריך לציין את הסוג המדויק של האימון הגופני.
  • שם לתצוגה (displayName): שם ידידותי למשתמש לאימון (לדוגמה, 'ריצת שטח אחר הצהריים').
  • משך הפעילות (activeDuration): משך הפעילות האמיתי של האימון, לא כולל הפסקות. בפורמט סטנדרטי משתמשים בפורמט Duration (לדוגמה, "1800s").

מדדי סיכום

האובייקט המקונן metricsSummary מכיל מדדים כוללים וממוצעים שמחושבים על פני משך הזמן הכולל של סשן האימון:

  • ‫caloriesKcal: סך הקלוריות הפעילות שנשרפו במהלך האימון, נמדד בקילוקלוריות (kcal).
  • ‫distanceMillimeters: המרחק הכולל שעבר, שנמדד במילימטרים כדי לשמור על דיוק גבוה בכל היחידות.
  • ‫steps: מספר הצעדים הכולל שבוצעו במהלך האימון.
  • ‫averageHeartRateBeatsPerMinute: הדופק הממוצע של המשתמש במהלך הדקות הפעילות בסשן.
  • ‫activeZoneMinutes: דקות טווח הדופק המצטברות שנצברו במהלך האימון.
  • ‫averageSpeedMillimetersPerSecond: מהירות התנועה הממוצעת במילימטרים לשנייה.
  • ‫averagePaceSecondsPerMeter: הקצב הממוצע במהלך הדקות הפעילות של הסשן, שנמדד בשניות למטר.
  • elevationGainMillimeters: סה"כ עלייה בגובה במהלך האימון.

הקפות וזמני ביניים

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

כל פיצול מכיל:

  • startTime וendTime ספציפיים.
  • ‫activeDuration שמייצג את זמן ההקפה האמיתי.
  • metricsSummary שמוגבל רק לפלח הזה.
  • ‫splitType כדי להגדיר את גבולות הפיצול (למשל DISTANCE,‏ DURATION או MANUAL).

אירועי פעילות גופנית

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

כל אירוע מכיל את חותמת הזמן (eventTime) ואת הסוג:

  • ‫START / STOP: מציין חותמות זמן של גבולות שבהן המשתמש התחיל או הפסיק את ההקלטה באופן מפורש.
  • ‫PAUSE / RESUME: מציין מתי הסשן הושהה או חודש באופן ידני.
  • ‫AUTO_PAUSE / AUTO_RESUME: מציין הפסקות אוטומטיות או המשכים אוטומטיים של הפעלה שמבוססים על חיישנים.

כתיבת נתוני אימון

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

דוגמה לייצוג REST

בדוגמה הבאה אפשר לראות איך כותבים אימון באמצעות המתודה POST:

בקשה

POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

תשובה

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

מסלולי GPS ומעקב אחר מיקום

ה-API שומר סיכומים בסיסיים של סשנים ישירות בנקודת הנתונים של exercise, אבל מטפל בהיסטוריית מיקומים מפורטת ובקואורדינטות של מסלולי GPS כמקור נתונים נפרד.

כדי להוריד את נתוני המסלול המפורטים של אימון בחוץ, מפעילים את השיטה exportExerciseTcx בהתאמה אישית. נקודת הקצה הזו מחזירה את המסלול בפורמט XML של מרכז האימונים (TCX) שהוא פורמט סטנדרטי בתעשייה.

ייצוא מסלול GPS

בקשה

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

תשובה

מטען ייעודי (payload) של HTTP עם הכותרות Content-Type: application/tcx+xml ו- שמנחות את הדפדפן לשמור את הקובץ.

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Id>2026-04-20T08:00:00Z</Id>
      <Lap StartTime="2026-04-20T08:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>380</Calories>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2026-04-20T08:00:00Z</Time>
            <Position>
              <LatitudeDegrees>37.7749</LatitudeDegrees>
              <LongitudeDegrees>-122.4194</LongitudeDegrees>
            </Position>
            <AltitudeMeters>15.0</AltitudeMeters>
            <DistanceMeters>0.0</DistanceMeters>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

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

כדי לקרוא או לכתוב נתונים של מסלולי GPS ומעקב מיקום, צריך לבקש את היקפי ה-OAuth הבאים באסימון הגישה של האפליקציה:

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

אם היקף נדרש חסר בכותרות ההרשאה, Google Health API מחזיר שגיאת הרשאה.

הנחיות

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

משך פעילות לעומת משך כולל

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

לדוגמה, אם משתמש מתחיל אימון בשעה 08:00 ומסיים אותו בשעה 08:35, משך האימון הכולל הוא 2,100 שניות. אם המשתמש הפסיק את האימון למשך 5 דקות (300 שניות), צריך להגדיר את activeDuration ל-"1800s" (2,100 – 300). ה-API משתמש במשך הפעילות כדי לחשב ממוצעים, ומחלק את המרחק הכולל ב-1,800 שניות במקום ב-2,100.

בקשת מיקום מוקדמת

אם האפליקציה ממפה מסלולים של אימונים, צריך לבקש הרשאות מיקום ואת היקף ההרשאות של Google Health‏ location בנוסף להיקף ההרשאות של פעילות וכושר. עליך להסביר למשתמשים למה האפליקציה שלך דורשת את היקף המיקום כשבודקים אימונים עם GPS.

כשהאפליקציה מבקשת את היקף ההרשאות למיקום (https://www.googleapis.com/auth/googlehealth.location.readonly), מערכת Google OAuth מציגה למשתמש בקשת הסכמה. להסביר למשתמשים שההרשאה הזו נחוצה כדי להציג שכבות-על של מסלולים ולייצא קובצי מעקב GPS ‏(TCX). אם משתמש מעניק הרשאה להיקף הפעילות אבל דוחה את הרשאת המיקום, פונקציית exportExerciseTcx מחזירה שגיאת הרשאה, אבל עדיין אפשר לגשת לנתוני סשן מצטברים ב-metricsSummary.

סנכרון בזמן אמת באמצעות Webhooks

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

כשהשרת מקבל התראה על webhook, היא מכילה את healthUserId ואת מרווח הזמן הפיזי הספציפי של האימון. השרת שלכם צריך לעבד את ההתראה באופן אסינכרוני ואז לשלוח בקשה לנקודת הקצה /users/me/dataTypes/exercise/dataPoints exercise כדי לקבל את נתון המיקום החדש. הוראות להגדרת מינויים זמינות במאמר בנושא מינויים ל-Webhook.

שמירה על מדדים עקביים

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

סנכרון של טלמטריה וסשנים (נתיב כתיבה)

כשמייבאים או כותבים אימון שהושלם אל Google Health API, צריך להטמיע דפוס כתיבה רב-שלבי:

  1. כתיבת הסשן: שולחים את אירוע הסיכום על ידי פרסום נקודה על הגרף בכתובת POST /users/me/dataTypes/exercise/dataPoints.
  2. כתיבת מרווחי זמן של סדרות עיתיות: כתיבה בו-זמנית של נקודות הנתונים המפורטות שנרשמו במהלך האימון (לדוגמה, צעדים או מרווחי שריפת קלוריות לפי דקה) באוספים המתאימים:
    • POST /users/me/dataTypes/steps/dataPoints
    • POST /users/me/dataTypes/active-energy-burned/dataPoints
    • POST /users/me/dataTypes/heart-rate/dataPoints

שאילתת נתונים מפורטים לתרשימים (נתיב קריאה)

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

  1. שאילתה על סיכומי הסשנים: Call /users/me/dataTypes/exercise/dataPoints to fetch the overall workout details and the final metricsSummary.
  2. אחזור מדדים של תרשים: בדיקת interval.startTime ו-interval.endTime של האימון. מבצעים קריאות משניות GET לאיסוף נתוני טלמטריה בחלון הזמן הספציפי הזה:
    • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
  3. שליפת מסלולי GPS: אם מטא-הנתונים של הסשן מציינים שקיימים נתוני GPS (הערך של exerciseMetadata.hasGps הוא true), מפעילים את שיטת העזר exportExerciseTcx כדי להוריד את קואורדינטות המסלול.
הקודם
קלוריות ואנרגיה