Pierwsze kroki z aplikacją Health Connect

Ten przewodnik jest zgodny z Health Connect w wersji 1.1.0-alpha12.

Z tego przewodnika dowiesz się, jak zacząć korzystać z Health Connect w swojej aplikacji.

Krok 1. Przygotuj aplikację Health Connect

Aplikacja Health Connect odpowiada za obsługę wszystkich żądań wysyłanych przez Twoją aplikację za pomocą pakietu SDK Health Connect. Obejmują one przechowywanie danych oraz zarządzanie dostępem do nich w celu odczytu i zapisu.

Dostęp do Health Connect zależy od wersji Androida zainstalowanej na telefonie. W poniższych sekcjach opisujemy, jak postępować w przypadku kilku ostatnich wersji Androida.

Android 14

Od Androida 14 (poziom 34 interfejsu API) Health Connect jest częścią platformy Android. Ta wersja Health Connect to moduł platformy. Nie musisz niczego konfigurować.

Android 13 i starsze

Na Androidzie 13 (API na poziomie 33) i starszych wersjach Health Connect nie jest częścią platformy Android. W tym celu musisz zainstalować aplikację Health Connect ze Sklepu Google Play.

Jeśli Twoja aplikacja jest zintegrowana z Health Connect na Androidzie 13 lub starszym i chcesz przeprowadzić migrację na Androida 14, zapoznaj się z sekcją Migracja z Androida 13 na Androida 14.

Otwórz aplikację Health Connect.

Health Connect nie będzie już domyślnie wyświetlać się na ekranie głównym. Aby otworzyć Zarządzanie danymi o zdrowiu, kliknij Ustawienia > Aplikacje > Zarządzanie danymi o zdrowiu lub dodaj Zarządzanie danymi o zdrowiu do menu Szybkie ustawienia.

Dodatkowo Health Connect wymaga, aby użytkownik miał włączoną blokadę ekranu z kodem PIN, wzorem lub hasłem, dzięki czemu dane o zdrowiu przechowywane w Health Connect są chronione przed złośliwymi podmiotami, gdy urządzenie jest zablokowane. Aby ustawić blokadę ekranu, otwórz Ustawienia > Zabezpieczenia > Blokada ekranu.

Krok 2. Dodaj do aplikacji pakiet SDK Health Connect

Pakiet SDK Health Connect odpowiada za używanie interfejsu Health Connect API do wysyłania żądań podczas wykonywania operacji na magazynie danych w aplikacji Health Connect.

Dodaj zależność pakietu SDK Health Connect w pliku build.gradle na poziomie modułu:

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

Najnowszą wersję znajdziesz w informacjach o wersjach Health Connect.

Uwaga: pakiet SDK Health Connect obsługuje Androida 8 (poziom interfejsu API 26) lub nowszego, a aplikacja Health Connect jest zgodna tylko z Androidem 9 (poziom interfejsu API 28) lub nowszym. Oznacza to, że aplikacje innych firm mogą obsługiwać użytkowników Androida 8, ale z Health Connect mogą korzystać tylko użytkownicy Androida 9 lub nowszego.

Krok 3. Skonfiguruj aplikację

W sekcjach poniżej znajdziesz informacje o konfigurowaniu aplikacji pod kątem integracji z Health Connect.

Deklarowanie uprawnień

Dostęp do danych o zdrowiu i aktywności fizycznej jest kwestią wrażliwą. Health Connect wdraża warstwę zabezpieczeń w operacjach odczytu i zapisu, co pozwala utrzymać zaufanie użytkowników.

W aplikacji zadeklaruj uprawnienia do odczytu i zapisu w pliku AndroidManifest.xml na podstawie wymaganych typów danych, które powinny być zgodne z typami danych, do których zadeklarowano dostęp w Konsoli Play.

Health Connect używa standardowego formatu deklaracji uprawnień na Androidzie. Przypisz uprawnienia za pomocą tagów <uses-permission>. Umieść je w tagach <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>

Pełną listę uprawnień i odpowiadających im typów danych znajdziesz w tym artykule.

Wyświetlanie okna dialogowego polityki prywatności aplikacji

Plik manifestu Androida musi zawierać aktywność, która wyświetla politykę prywatności aplikacji. Jest to uzasadnienie żądanych uprawnień, które opisuje, jak dane użytkownika są używane i przetwarzane.

Zadeklaruj tę aktywność, aby obsługiwać intencję ACTION_SHOW_PERMISSIONS_RATIONALE, która jest wysyłana do aplikacji, gdy użytkownik kliknie link do polityki prywatności na ekranie uprawnień 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>
...

Pobieranie klienta Health Connect

HealthConnectClient to punkt wejścia do interfejsu Health Connect API. Umożliwia aplikacji korzystanie z magazynu danych w aplikacji Health Connect. Automatycznie zarządza połączeniem z bazową warstwą pamięci i obsługuje wszystkie procesy IPC oraz serializację żądań wychodzących i odpowiedzi przychodzących.

Aby uzyskać instancję klienta, najpierw zadeklaruj nazwę pakietu Health Connect w pliku manifestu Androida.

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

Następnie w sekcji Aktywność sprawdź, czy Health Connect jest zainstalowana, korzystając z getSdkStatus. Jeśli tak jest, uzyskaj instancję 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

Krok 4. Poproś użytkownika o uprawnienia

Po utworzeniu instancji klienta aplikacja musi poprosić użytkownika o uprawnienia. Użytkownicy muszą mieć możliwość przyznania lub odmowy przyznania uprawnień w dowolnym momencie.

Aby to zrobić, utwórz zestaw uprawnień dla wymaganych typów danych. Sprawdź, czy uprawnienia w zestawie są najpierw zadeklarowane w pliku manifestu Androida.

// 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)
)

Użyj getGrantedPermissions, aby sprawdzić, czy Twoja aplikacja ma już przyznane wymagane uprawnienia. Jeśli nie, użyj createRequestPermissionResultContract, aby poprosić o te uprawnienia. Wyświetli się ekran uprawnień 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)
  }
}

Użytkownicy mogą w dowolnym momencie przyznawać i anulować uprawnienia, dlatego aplikacja musi okresowo sprawdzać, czy uprawnienia zostały przyznane, i obsługiwać sytuacje, w których uprawnienia zostaną utracone.

Krok 5. Wykonaj operacje

Gdy wszystko będzie gotowe, wykonaj w aplikacji operacje odczytu i zapisu.

Zapisywanie danych

Uporządkuj dane w rekord. Zapoznaj się z listą typów danych dostępnych w Health Connect.

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

Następnie wpisz rekord, używając znaku 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
    }
}

Odczytywanie danych

Możesz odczytywać dane pojedynczo za pomocą funkcji readRecords.

Uwaga: w przypadku typów danych skumulowanych, takich jak StepsRecord, używaj aggregate() zamiast readRecords(), aby uniknąć podwójnego zliczania z wielu źródeł i zwiększyć dokładność. Więcej informacji znajdziesz w artykule Odczytywanie zagregowanych danych.

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
    }
}

Możesz też odczytywać dane w formie zagregowanej za pomocą 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
    }
}

Ważne: Health Connect może odczytywać dane z okresu do 30 dni przed przyznaniem uprawnień. Jeśli chcesz, aby aplikacja odczytywała rekordy starsze niż 30 dni, użyj uprawnienia PERMISSION_READ_HEALTH_DATA_HISTORY. Więcej informacji znajdziesz w sekcji Ograniczenia dotyczące odczytu.

Samouczki wideo

Obejrzyj te filmy, aby dowiedzieć się więcej o funkcjach Health Connect oraz o sprawdzonych metodach, które pomogą Ci w płynnej integracji:

• Zarządzanie uprawnieniami w Health Connect
• Odczytywanie i zapisywanie danych w Health Connect
• Wskazówki dotyczące dobrej integracji z Health Connect

Materiały

Zapoznaj się z tymi zasobami, które pomogą Ci w późniejszym etapie tworzenia.

• Pakiet SDK Health Connect (dostępny w Jetpacku): dołącz ten pakiet SDK do aplikacji, aby korzystać z interfejsu Health Connect API.
• Dokumentacja interfejsu API: zapoznaj się z dokumentacją Jetpack dotyczącą interfejsu Health Connect API.
• Zadeklaruj użycie typów danych: w Konsoli Play zadeklaruj dostęp do typów danych Health Connect, które Twoja aplikacja odczytuje i do których zapisuje dane.
• Opcjonalny przykładowy kod GitHub i ćwiczenie z codelabu: zapoznaj się z przykładowym kodem GitHub w repozytorium i ćwiczeniem z codelabu, które pomogą Ci zacząć.

Uwaga: jeśli przesyłasz kolejną prośbę, ponieważ Twoja aplikacja wymaga nowych typów danych, musisz uwzględnić zarówno nowe, jak i dotychczasowe typy danych, a także wykluczyć wszystkie typy danych, których już nie potrzebujesz. Jeśli chcesz usunąć dostęp tylko do określonych typów danych, uwzględnij wszystkie dotychczasowe typy danych, ale wyklucz te, których już nie potrzebujesz.

Dalsze kroki

W sekcji Typowe procesy znajdziesz informacje o tym, jak wykonywać w Health Connect takie działania jak:

• Zapisywanie danych
• Odczytywanie surowych danych
• Odczytywanie danych zbiorczych