איך מתחילים להשתמש ב-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 לאפליקציה

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

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

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

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

הערה: ה-SDK של Health Connect תומך ב-Android 8 (רמת API‏ 26) ואילך, אבל אפליקציית Health Connect תואמת רק ל-Android 9 (רמת API‏ 28) ואילך. המשמעות היא שאפליקציות של צד שלישי יכולות לתמוך במשתמשים עם Android 8, אבל רק משתמשי Android מגרסה 9 ואילך יכולים להשתמש ב-Health Connect.

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

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

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

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

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

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

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

סרטוני הדרכה

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

• ניהול ההרשאות ב-Health Connect
• קריאה וכתיבה ב-Health Connect
• טיפים לשילוב מצוין עם Health Connect

משאבים

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

• Health Connect SDK (זמין ב-Jetpack): כדי להשתמש ב-Health Connect API, צריך לכלול את ה-SDK הזה באפליקציה.
• מידע על API: כדאי לעיין במידע על Jetpack לגבי Health Connect API.
• להצהיר על שימוש בסוגי נתונים: ב-Play Console, להצהיר על גישה לסוגי הנתונים של Health Connect האפליקציה קוראת מ- וכותבת אליה.
• קוד לדוגמה ו-codelab ב-GitHub: כדי להתחיל, אפשר לעיין במאגר של הקוד לדוגמה ב-GitHub ובתרגיל codelab.

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

השלבים הבאים

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

• כתיבת נתונים
• קריאת נתונים גולמיים
• קריאת נתונים נצברים