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

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

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

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

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

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

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

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

הצהרת ההרשאות

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

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

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

צריך להצהיר על הפעילות הזו כדי לטפל ב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, למשל: