Health Connect'i kullanmaya başlama

Bu kılavuz, Health Connect 1.1.0-alpha12 veya sonraki sürümlerle uyumludur.

Bu kılavuzda, uygulamanızda Health Connect'i kullanmaya nasıl başlayacağınız gösterilmektedir.

1. adım: Health Connect uygulamasını hazırlayın

Health Connect uygulaması, uygulamanızın Health Connect SDK'sı üzerinden gönderdiği tüm istekleri işlemekten sorumludur. Bu istekler arasında veri depolama ve okuma/yazma erişimini yönetme yer alır.

Health Connect'e erişim, telefonda yüklü Android sürümüne bağlıdır. Aşağıdaki bölümlerde, Android'in son sürümlerinin nasıl işleneceği açıklanmaktadır.

Android 14

Android 14'ten (API düzeyi 34) itibaren Health Connect, Android çerçevesinin bir parçasıdır. Health Connect'in bu sürümü bir çerçeve modülüdür. Bu sayede kurulum yapmanız gerekmez.

Android 13 ve önceki sürümler

Android 13 (API düzeyi 33) ve önceki sürümlerde Health Connect, Android çerçevesinin bir parçası değildir. Bunun için Google Play Store'dan Health Connect uygulamasını yüklemeniz gerekir.

Uygulamanızı Android 13 ve önceki sürümlerde Health Connect ile entegre ettiyseniz ve Android 14'e taşımak istiyorsanız Android 13'ten 14'e taşıma başlıklı makaleyi inceleyin.

Health Connect uygulamasını açın.

Health Connect artık varsayılan olarak ana ekranda görünmez. Health Connect'i Ayarlar'dan açabilirsiniz ancak izlenecek yol Android sürümüne göre değişiklik gösterir:

  • Android 14 ve sonraki sürümlerde: Ayarlar > Güvenlik ve Gizlilik > Gizlilik Denetimleri > Health Connect'e gidin veya Ayarlar'da Health Connect'i arayın.
  • Android 13 ve önceki sürümlerde: Ayarlar > Uygulamalar > Health Connect'e gidin veya Health Connect'i Hızlı Ayarlar menünüze ekleyin.

2. adım: Health Connect SDK'sını uygulamanıza ekleyin

Health Connect SDK'sı, Health Connect uygulamasındaki veri deposunda işlem yapmak için istek göndermek üzere Health Connect API'yi kullanmaktan sorumludur.

Modül düzeyindeki build.gradle dosyanıza Health Connect SDK bağımlılığını ekleyin:

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

En yeni sürüm için Health Connect sürümleri başlıklı makaleyi inceleyin.

connect-client uygulamasının 1.1.0 ve sonraki sürümleri için compileSdk = 36 ve Android Gradle eklentisinin (AGP) 8.9.1 veya sonraki sürümleri gerekir. Modül düzeyindeki build.gradle dosyanızda compileSdk öğesini güncelleyin:

android {
  compileSdk = 36
}

Canary sürüm kanalı özelliklerini kullanma

Canary sürüm kanalındaki özellikleri kullanmak için modül düzeyindeki build.gradle dosyanızda compileSdk sürümünü değiştirin:

android {
  compileSdkPreview = "CANARY"
}

3. adım: Uygulamanızı yapılandırın

Aşağıdaki bölümlerde, uygulamanızı Health Connect ile entegre olacak şekilde nasıl yapılandıracağınız açıklanmaktadır.

Özelliklerin kullanıma sunulma durumunu kontrol etme

Health Connect'e yeni özellikler eklendiğinde kullanıcılar Health Connect sürümlerini her zaman güncellemeyebilir. Feature Availability API, Health Connect'teki bir özelliğin kullanıcınızın cihazında kullanılabilir olup olmadığını kontrol etmenin ve hangi işlemin yapılacağına karar vermenin bir yoludur.

Özelliklerin kullanılabilirliğini kontrol etmek için kullanılan temel işlev getFeatureStatus() işlevidir. Bu işlev, FEATURE_STATUS_AVAILABLE veya FEATURE_STATUS_UNAVAILABLE tam sayı sabitlerini döndürür:

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

İzinleri beyan etme

Sağlık ve fitness verilerine erişim hassas bir konudur. Health Connect, okuma ve yazma işlemlerine bir güvenlik katmanı ekleyerek kullanıcıların güvenini korur.

Uygulamanızda, gerekli veri türlerine göre AndroidManifest.xml dosyasında okuma ve yazma izinlerini beyan edin. Bu izinler, Google Play Console'da erişim beyan ettiğiniz izinlerle eşleşmelidir.

Health Connect, standart Android izin beyanı biçimini kullanır. <uses-permission> etiketleriyle izinler atayın. Bunları <manifest> etiketlerinin içine yerleştirin.

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

İzinlerin ve bunlara karşılık gelen veri türlerinin tam listesi için Veri türlerinin listesi başlıklı makaleyi inceleyin.

Uygulamanızın gizlilik politikası iletişim kutusunu gösterme

Android manifest dosyanızda, uygulamanızın gizlilik politikasını gösteren bir etkinlik bulunmalıdır. Bu politika, uygulamanızın istenen izinleri neden istediğini açıklayarak kullanıcı verilerinin nasıl kullanıldığını ve işlendiğini belirtir.

Kullanıcı, Health Connect izinler ekranındaki gizlilik politikası bağlantısını tıkladığında uygulamaya gönderilen ACTION_SHOW_PERMISSIONS_RATIONALE intent'ini işlemek için bu etkinliği beyan edin.

...
<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 istemcisi edinme

HealthConnectClient, Health Connect API'nin giriş noktasıdır. Uygulamanın, Health Connect uygulamasındaki veri deposunu kullanmasına olanak tanır. Temel depolama katmanıyla bağlantısını otomatik olarak yönetir ve giden isteklerin ve gelen yanıtların tüm IPC ve serileştirme işlemlerini gerçekleştirir.

İstemci örneği almak için önce Android manifest dosyanızda Health Connect paket adını belirtin.

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

Ardından, etkinliğinizde getSdkStatus kullanarak Health Connect'in yüklü olup olmadığını kontrol edin. Ayarlanmışsa bir HealthConnectClient örneği alın.

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

4. adım: Kullanıcıdan izin isteyin

Uygulamanız, istemci örneği oluşturduktan sonra kullanıcıdan izin istemelidir. Kullanıcıların diledikleri zaman izin vermelerine veya izinleri reddetmelerine olanak tanınmalıdır. Bunun için gerekli veri türlerine yönelik bir izin grubu oluşturun. Öncelikle, kümedeki izinlerin Android manifest dosyanızda beyan edildiğinden emin olun. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 Uygulamanızın gerekli izinlere sahip olup olmadığını görmek için getGrantedPermissions yöntemini kullanın. Aksi takdirde bu izinleri istemek için createRequestPermissionResultContract yöntemini kullanın. Health Connect izinleri ekranı açılır. 
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.") }
    }
}
 Kullanıcılar istedikleri zaman izin verebildikleri veya izinleri iptal edebildikleri için uygulamanızın, izinleri kullanmadan önce her seferinde kontrol etmesi ve iznin kaybedildiği senaryoları yönetmesi gerekir.

Kullanıcıların ilk katılımını gerçekleştirme

Birçok uygulamada, özellik eğitimi veya kullanıcı rızası isteme gibi özel bir ilk katılım akışı vardır. Health Connect'in ilk katılım akışınızı başlatmasını sağlamak için manifest dosyanıza aşağıdakileri ekleyin:

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

Kullanıcılar, uygulamanıza bağlantıyı uygulamanızın içinden değil, doğrudan Health Connect uygulamasından başlatabilir. Uygulamanız, veri okuma veya yazma izni verilmesinin ötesinde ek etkileşim gerektiriyorsa bir ilk katılım etkinliği sağlayın.

Kullanıcı daha sonra uygulamanızın izinlerini iptal edip yeniden bağlarsa ilk katılım etkinliği birden fazla kez başlatılabilir.

5. adım: İşlemleri gerçekleştirme

Artık her şey hazır olduğuna göre uygulamanızda okuma ve yazma işlemlerini gerçekleştirebilirsiniz.

Kullanıcılarınız, uygulamanızın erişmesi için verileri Health Connect ile senkronize eden başka uygulamalar kullanabilir. Kullanıcı bu uygulamaları henüz Health Connect'e yazacak şekilde ayarlamadıysa kullanıcılarınız için bu uygulamaları sorunsuz bir şekilde bağlamak üzere Matchmaking API'yi kullanabilirsiniz.

Verileri yazma

Verilerinizi bir kayıt halinde yapılandırın. Health Connect'te kullanılabilen veri türlerinin listesine göz atın.

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

Ardından, insertRecords kullanarak kaydınızı yazın.

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

Verileri okuma

readRecords kullanarak verilerinizi tek tek okuyabilirsiniz.

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

Verilerinizi aggregate kullanarak toplu bir şekilde de okuyabilirsiniz.

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
}

Eğitim videoları

Health Connect özellikleri hakkında daha fazla bilgi edinmek ve sorunsuz bir entegrasyon için en iyi uygulama yönergelerini öğrenmek üzere bu videoları izleyin:

Kaynaklar

Daha sonra geliştirme sürecine yardımcı olacak aşağıdaki kaynaklara göz atın.

  • Health Connect SDK'sı (Jetpack'te kullanılabilir): Health Connect API'yi kullanmak için bu SDK'yı uygulamanıza ekleyin.
  • API referansı: Health Connect API için Jetpack referansına göz atın.
  • Veri türlerinin kullanımını beyan edin: Google Play Console'da, uygulamanızın okuduğu ve yazdığı Health Connect veri türlerine erişimi beyan edin.
  • İsteğe bağlı GitHub kod örneği ve codelab: Başlamanıza yardımcı olması için GitHub kod örneği deposu ve codelab alıştırmasına göz atın.

Sonraki adımlar

Health Connect'te aşağıdaki gibi işlemleri nasıl gerçekleştireceğinizi öğrenmek için Yaygın iş akışları bölümüne göz atın: