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

המדריך הזה תואם לגרסה 1.1.0-alpha12 של 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 היא מודול של מסגרת. לכן, לא צריך להגדיר שום דבר.

‫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 לאפליקציה

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

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha01"
  ...
}

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

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

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

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

הגישה לנתוני בריאות וכושר היא רגישה. ב-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>

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

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

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

צריך להצהיר על הפעילות הזו כדי לטפל ב-intent‏ 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) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

קריאת נתונים

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

suspend fun readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each 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, כמו: