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 Health Connect SDK. Te żądania obejmują przechowywanie danych oraz zarządzanie dostępem do odczytu i zapisu.

Dostęp do Health Connect zależy od wersji Androida zainstalowanej na telefonie. W sekcjach poniżej opisujemy, jak obsługiwać kilka najnowszych wersji Androida.

Android 14

Od Androida 14 (poziom API 34) Health Connect jest częścią platformy Android. Ta wersja Health Connect to moduł platformy. Dlatego nie wymaga konfiguracji.

Android 13 i starsze wersje

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

Jeśli masz zintegrowaną aplikację z Health Connect na Androidzie 13 lub starszym i chcesz przeprowadzić migrację na Androida 14, przeczytaj artykuł Migracja z Androida 13 na 14.

Otwórz aplikację Health Connect

Health Connect nie jest już domyślnie wyświetlana na ekranie głównym. Możesz otworzyć Health Connect w Ustawieniach, ale ścieżka dostępu różni się w zależności od wersji Androida:

  • W Androidzie 14 i nowszych wersjach: kliknij Ustawienia > Bezpieczeństwo i prywatność > Kontrola prywatności > Health Connect lub wyszukaj Health Connect w Ustawieniach.
  • W Androidzie 13 i starszych wersjach: kliknij Ustawienia > Aplikacje > Health Connect lub dodaj Health Connect do menu Szybkie ustawienia.

Krok 2. Dodaj pakiet Health Connect SDK do swojej aplikacji

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

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

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

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

Korzystanie z funkcji w kanale wersji do wczesnych testów

Aby korzystać z funkcji w kanale wersji Canary, zmodyfikuj wersję compileSdk w pliku build.gradle na poziomie modułu:

android {
  compileSdkPreview = "CANARY"
}

Krok 3. Skonfiguruj aplikację

W sekcjach poniżej dowiesz się, jak skonfigurować aplikację do integracji z Health Connect.

Sprawdzanie dostępności funkcji

Gdy do Health Connect dodawane są nowe funkcje, użytkownicy nie zawsze aktualizują swoją wersję Health Connect. Interfejs Feature Availability API umożliwia sprawdzenie, czy funkcja w Health Connect jest dostępna na urządzeniu użytkownika, i podjęcie odpowiednich działań.

Główną funkcją sprawdzania dostępności funkcji jest getFeatureStatus(). Zwraca ona stałe całkowite FEATURE_STATUS_AVAILABLE lub FEATURE_STATUS_UNAVAILABLE:

@OptIn(ExperimentalFeatureAvailabilityApi::class)
fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}

Deklarowanie uprawnień

Dostęp do danych o zdrowiu i aktywności fizycznej jest wrażliwy. Health Connect implementuje warstwę zabezpieczeń do operacji 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 zadeklarowanymi w Konsoli Play.

Health Connect używa standardowego formatu deklaracji uprawnień Androida. 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 artykule Lista typów danych.

Wyświetlanie okna z polityką prywatności aplikacji

Manifest Androida musi zawierać aktywność, która wyświetla politykę prywatności aplikacji, czyli uzasadnienie żądanych uprawnień, opisujące, jak dane użytkownika są używane i przetwarzane.

Zadeklaruj tę aktywność, aby obsługiwała intencję ACTION_SHOW_PERMISSIONS_RATIONALE, która jest wysyłana do aplikacji, gdy użytkownik kliknie link polityka 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 warstwą pamięci i obsługuje wszystkie IPC oraz serializację żądań wychodzących i odpowiedzi przychodzących.

Aby uzyskać instancję klienta, najpierw zadeklaruj nazwę pakietu Health Connect w manifeście Androida.

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

Następnie w aktywności sprawdź, czy Health Connect jest zainstalowany za pomocą getSdkStatus. Jeśli tak, uzyskaj instancję HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

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 uprawnień w dowolnym momencie. Aby to zrobić, utwórz zestaw uprawnień dla wymaganych typów danych. Upewnij się, że uprawnienia w zestawie są najpierw zadeklarowane w manifeście Androida. 

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ż wymagane uprawnienia. Jeśli nie, użyj createRequestPermissionResultContract aby poprosić o te uprawnienia. Spowoduje to wyświetlenie ekranu uprawnień Health Connect. 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 Ponieważ użytkownicy mogą przyznawać i cofać uprawnienia w dowolnym momencie, aplikacja musi sprawdzać uprawnienia za każdym razem przed ich użyciem i obsługiwać sytuacje, w których uprawnienia zostaną utracone.

Wprowadzanie użytkowników

Wiele aplikacji ma niestandardowy proces wprowadzania, np. edukację dotyczącą funkcji lub prośbę o zgodę użytkownika. Aby umożliwić Health Connect uruchomienie procesu wprowadzania, dodaj do manifestu te informacje:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

Użytkownicy mogą inicjować połączenie z Twoją aplikacją bezpośrednio z aplikacji Health Connect, a nie z Twojej aplikacji. Jeśli Twoja aplikacja wymaga dodatkowej interakcji poza przyznaniem uprawnień do odczytu lub zapisu danych, udostępnij aktywność wprowadzającą.

Pamiętaj, że aktywność wprowadzająca może zostać uruchomiona więcej niż raz, np. jeśli użytkownik później cofnie uprawnienia Twojej aplikacji, a następnie ponownie ją połączy.

Krok 5. Wykonaj operacje

Teraz, gdy wszystko jest skonfigurowane, możesz wykonywać operacje odczytu i zapisu w swojej aplikacji.

Użytkownicy mogą korzystać z innych aplikacji, które synchronizują dane z Health Connect, aby Twoja aplikacja mogła uzyskać do nich dostęp. Jeśli użytkownik nie skonfigurował jeszcze tych aplikacji do zapisywania danych w Health Connect , możesz użyć interfejsu Matchmaking API, aby bezproblemowo połączyć te aplikacje dla użytkowników.

Zapisywanie danych

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

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Następnie zapisz rekord za pomocą insertRecords.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Odczytywanie danych

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

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}

Możesz też odczytywać dane w sposób zagregowany za pomocą aggregate.

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

Samouczki wideo

Obejrzyj te filmy, aby dowiedzieć się więcej o funkcjach Health Connect oraz o sprawdzonych metodach zapewniających płynną integrację:

Zasoby

Zapoznaj się z tymi zasobami, które pomogą Ci w dalszym rozwoju.

  • Pakiet Health Connect SDK (dostępny w Jetpacku): dodaj ten pakiet SDK do swojej aplikacji, aby korzystać z interfejsu Health Connect API.
  • Dokumentacja API: zapoznaj się z dokumentacją Jetpacka dotyczącą interfejsu Health Connect API.
  • Deklarowanie użycia typów danych: w Konsoli Play zadeklaruj dostęp do typów danych Health Connect, z których Twoja aplikacja odczytuje i do których zapisuje dane.
  • Opcjonalny przykład kodu i ćwiczenie w codelabu na GitHubie: aby rozpocząć, zapoznaj się z repozytorium przykładów kodu na GitHubie i ćwiczeniem w codelabu.

Dalsze kroki

Zapoznaj się z Typowymi procesami , aby dowiedzieć się, jak wykonywać operacje w Health Connect, takie jak: