W 2026 r. zaczniemy wycofywać interfejsy Google Fit API. Więcej informacji o migracji z Google Fit znajdziesz w przewodniku po migracji.

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. Żądania te 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.

Otwieranie aplikacji Health Connect

Health Connect nie jest już domyślnie wyświetlana na ekranie głównym. Możesz otworzyć Health Connect, klikając Ustawienia, 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:

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

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, utrzymując 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 dostęp został zadeklarowany w Konsoli Play.

Health Connect używa standardowego formatu deklaracji uprawnień Androida. Przypisz uprawnienia za pomocą tagów <uses-permission>. Zagnieźdź 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

Plik manifestu 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 masowej 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 pliku manifestu 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 zainstalowana za pomocą getSdkStatus. Jeśli tak, 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 Twoja aplikacja musi poprosić użytkownika o uprawnienia. Użytkownicy muszą mieć możliwość przyznawania i odmawiania 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 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. Spowoduje to wyświetlenie ekranu 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)
  }
}

Ponieważ użytkownicy mogą przyznawać i cofać uprawnienia w dowolnym momencie, Twoja aplikacja musi sprawdzać uprawnienia za każdym razem przed ich użyciem i obsługiwać sytuacje, w których uprawnienia zostaną utracone.

Dodawanie użytkowników

Wiele aplikacji ma niestandardowy proces dodawania użytkowników, np. informowanie o funkcjach lub proszenie o zgodę użytkownika. Aby umożliwić Health Connect uruchamianie procesu dodawania użytkowników, dodaj do pliku 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ść dodawania użytkowników 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 stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

Następnie zapisz rekord za pomocą 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ą 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
    }
}

Możesz też odczytywać dane w sposób zagregowany 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
    }
}

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 Jetpack): dodaj ten pakiet SDK do swojej aplikacji, aby korzystać z interfejsu Health Connect API.
Dokumentacja API: zapoznaj się z dokumentacją Jetpack 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 codelabie na GitHubie: aby rozpocząć, zapoznaj się z repozytorium przykładów kodu na GitHubie i ćwiczeniem w codelabie.

Dalsze kroki

Zapoznaj się z sekcją Typowe procesy , aby dowiedzieć się, jak wykonywać operacje w Health Connect, takie jak: