איך מתחילים להשתמש ב-Health Connect

במדריך הזה מוסבר איך להתחיל להשתמש ב-Health Connect באפליקציה.

שלב 1: הכנת אפליקציית Health Connect

אפליקציית Health Connect אחראית לטיפול בכל הבקשות שהאפליקציה שולחת דרך Health Connect SDK. הבקשות האלה כוללות אחסון נתונים וניהול גישת קריאה וכתיבה.

הגישה ל-Health Connect תלויה בגרסת Android שמותקנת בטלפון. בקטעים הבאים מוסבר איך לטפל בכמה גרסאות עדכניות של Android.

Android 14

החל מגרסה Android 14 (רמת API 34), Health Connect הוא חלק מ-Android Framework. הגרסה הזו של Health Connect היא מודול framework. לכן אין צורך בהגדרה.

Android מגרסה 13 ומטה

ב-Android 13 (רמת API ‏33) ובגרסאות קודמות, Health Connect לא נכלל ב-Android Framework. לאחר מכן, צריך להתקין את אפליקציית Health Connect מחנות Google Play.

אם שילבתם את האפליקציה עם Health Connect ב-Android מגרסה 13 ומטה, ואתם רוצים לעבור מ-Android 14, תוכלו לקרוא את המאמר העברה מ-Android 13 לגרסה 14.

פותחים את אפליקציית Health Connect.

אפליקציית Health Connect לא מופיעה יותר במסך הבית כברירת מחדל. כדי לפתוח את Health Connect, עוברים אל הגדרות > אפליקציות > Health Connect או מוסיפים את Health Connect לתפריט הגדרות מהירות.

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

שלב 2: מוסיפים את Health Connect SDK לאפליקציה

ה-SDK של Health Connect אחראי לשימוש ב-Health Connect API כדי לשלוח בקשות לביצוע פעולות במאגר הנתונים באפליקציית Health Connect.

מוסיפים את התלות של Health Connect בקובץ build.gradle ברמת המודול:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alph10"
  ...
}

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

שלב 3: מגדירים את האפליקציה

בקטעים הבאים מוסבר איך להגדיר את האפליקציה כך שתשתלב עם Health Connect.

הצהרה על הרשאות

הגישה לנתוני הבריאות והכושר היא רגישת. ב-Health Connect מופעלת שכבת אבטחה לפעולות קריאה וכתיבה, כדי לשמור על אמון המשתמשים.

ב-Play Console, מצהירים על גישה לסוגי הנתונים של Health Connect שהאפליקציה קוראת מהם וכותבת אליהם.

באפליקציה, מגדירים הרשאות קריאה וכתיבה בקובץ AndroidManifest.xml על סמך סוגי הנתונים הנדרשים, שצריכים להתאים לאלה שהצהרתם על גישה אליהם ב-Play Console.

ב-Health Connect נעשה שימוש בפורמט הסטנדרטי של הצהרת הרשאות ב-Android. מקצים הרשאות באמצעות התגים <uses-permission>. צריך להטמיע אותם בתוך תגי <manifest>.

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

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

הצגת תיבת הדו-שיח של מדיניות הפרטיות של האפליקציה

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

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

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

אחזור לקוח של Health Connect

HealthConnectClient היא נקודת כניסה ל-Health Connect API. היא מאפשרת לאפליקציה להשתמש במאגר הנתונים באפליקציית Health Connect. היא מנהלת באופן אוטומטי את החיבור לשכבת האחסון הבסיסית, ומטפלת בכל ה-IPC ובסידור ההטורי של הבקשות היוצאות והתשובות הנכנסות.

כדי לקבל מופע לקוח, קודם צריך להצהיר על שם החבילה של Health Connect במניפסט של Android.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

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

val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // Optionally redirect to package installer to find a provider, for example:
  val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
  context.startActivity(
    Intent(Intent.ACTION_VIEW).apply {
      setPackage("com.android.vending")
      data = Uri.parse(uriString)
      putExtra("overlay", true)
      putExtra("callerId", context.packageName)
    }
  )
  return
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

שלב 4: מבקשים הרשאות מהמשתמש

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

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

// Create a set of permissions for required data types
val PERMISSIONS =
setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

אפשר להשתמש ב-getGrantedPermissions כדי לבדוק אם האפליקציה כבר קיבלה את ההרשאות הנדרשות. אם לא, צריך להשתמש ב-createRequestPermissionResultContract כדי לבקש את ההרשאות האלה. יוצג המסך של הרשאות Health Connect.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

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

שלב 5: ביצוע פעולות

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

כתיבת נתונים

מגדירים את המבנה של הנתונים ברשומה. כדאי לעיין ברשימת סוגי הנתונים שזמינים ב-Health Connect.

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

לאחר מכן כותבים את הרשומה באמצעות insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

קריאת נתונים

אפשר לקרוא את הנתונים בנפרד באמצעות readRecords.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    StepsRecord::class,
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        for (stepRecord in response.records) {
            // Process each step record
        }
    } catch (e: Exception) {
        // Run error handling here.
    }
}

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

suspend fun aggregateSteps(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

סרטוני הדרכה

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

משאבים

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

השלבים הבאים

בתהליכי עבודה נפוצים מוסבר איך לבצע פעולות ב-Health Connect, כמו: