Health Connect'i kullanmaya başlama

Bu kılavuz, Health Connect'in 1.1.0-alpha12 sürümüyle uyumludur.

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

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

Health Connect uygulaması, uygulamanızın Health Connect SDK'sı aracılığıyla gönderdiği tüm istekleri işlemekten sorumludur. Bu istekler arasında verilerin depolanması ve okuma/yazma erişiminin yönetilmesi 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ümlerinden bazılarının nasıl ele alınacağı açıklanmaktadır.

Android 14

Android 14 (API düzeyi 34) sürümünden itibaren Health Connect, Android Framework'ün bir parçasıdır. Bu Health Connect sürümü bir framework modülüdür. Bu nedenle, kurulum gerekmez.

Android 13 ve önceki sürümler

Android 13 (API düzeyi 33) ve önceki sürümlerde Health Connect, Android Framework'ün bir parçası değildir. Bu nedenle, 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 geçmek istiyorsanız Android 13'ten 14'e geçiş başlıklı makaleyi inceleyin.

Health Connect uygulamasını açın.

Health Connect artık varsayılan olarak ana ekranda görünmüyor. Health Connect'i Ayarlar üzerinden açabilirsiniz. Ancak yol, Android sürümüne göre değişir:

• 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, Health Connect uygulamasındaki veri deposuna karşı işlemler gerçekleştirirken istek göndermek için 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-alpha02"
  ...
}

En son sürüm için Health Connect sürümlerine bakın.

Not: Health Connect SDK'sı Android 8 (API düzeyi 26) veya sonraki sürümleri desteklerken Health Connect uygulaması yalnızca Android 9 (API düzeyi 28) veya sonraki sürümlerle uyumludur. Bu nedenle, üçüncü taraf uygulamaları Android 8'deki kullanıcıları destekleyebilir ancak yalnızca Android 9 veya sonraki sürümleri kullananlar Health Connect'i kullanabilir.

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ılabilirlik durumunu kontrol edin

Health Connect'e yeni özellikler eklendiğinde kullanıcılar, Health Connect sürümlerini her zaman güncelleyemeyebilir. 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şlemi yapacağınıza karar vermenin bir yoludur.

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

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

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

Not: Bir özellik kullanılamıyorsa kullanıcıdan Health Connect'i güncellemesini isteyin. Sistem modülüne bağlı özellikler, APK ile birlikte bile Android 13 ve önceki sürümlerde kullanılamaz.

İzinleri beyan etme

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

Uygulamanızda, Play Console'da erişim beyan ettiğiniz veri türleriyle eşleşmesi gereken, gerekli veri türlerine dayalı olarak AndroidManifest.xml dosyasında okuma ve yazma izinlerini beyan edin.

Health Connect, standart Android izin beyanı biçimini kullanır. <uses-permission> etiketleriyle izin 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ürleri 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 etkinlik, istenen izinlerin gerekçesini, kullanıcının verilerinin nasıl kullanıldığını ve işlendiğini açıklamalıdır.

Bu etkinliği, kullanıcı Health Connect izinleri ekranında gizlilik politikası bağlantısını tıkladığında uygulamaya gönderilen ACTION_SHOW_PERMISSIONS_RATIONALE amacını işlemek için 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'sinin giriş noktasıdır. Bu izin, 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 manifestinizde Health Connect paket adını beyan edin.

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

Ardından, Etkinliğinizde Health Connect'in getSdkStatus kullanılarak yüklenip yüklenmediğini kontrol edin. Ayarlanmışsa HealthConnectClient örneği edinin.

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. adım: Kullanıcıdan izin isteyin

İstemci örneği oluşturduktan sonra uygulamanızın kullanıcıdan izin istemesi gerekir. Kullanıcıların izinleri istedikleri zaman vermesine veya reddetmesine izin verilmelidir.

Bunu yapmak için gerekli veri türleri için bir dizi izin oluşturun. Gruptaki izinlerin önce Android manifestinizde beyan edildiğinden emin olun.

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

Uygulamanıza gerekli izinlerin verilip verilmediğini görmek için getGrantedPermissions aracını kullanın. Aksi takdirde, bu izinleri istemek için createRequestPermissionResultContract simgesini kullanın. Bu işlem, Health Connect izinleri ekranını gösterir.

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

Kullanıcılar izinleri istedikleri zaman verebilir veya iptal edebilir. Bu nedenle, uygulamanızın verilen izinleri düzenli olarak kontrol etmesi ve izinlerin kaybedildiği senaryoları ele alması gerekir.

Kullanıcı oryantasyonu

Birçok uygulamada, özellik eğitimi veya kullanıcı izni isteme gibi özel bir ilk katılım akışı bulunur. Health Connect'in oryantasyon 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ı doğrudan Health Connect uygulamasından başlatabilir. Uygulamanızın, veri okuma veya yazma izni verilmesinin ötesinde ek etkileşim gerektirmesi durumunda bir ilk katılım etkinliği sağlayın.

Kullanıcı daha sonra uygulamanızın izinlerini iptal edip yeniden bağlarsa oryantasyon etkinliğinin birden fazla kez başlatılabileceğini unutmayın.

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

Artık her şey ayarlandığına göre uygulamanızda okuma ve yazma işlemleri yapın.

Verileri yazma

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

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

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

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

Verileri okuma

readRecords kullanarak verilerinizi tek tek okuyabilirsiniz.

Not: StepsRecord gibi kümülatif türler için birden fazla kaynaktan gelen verilerin iki kez sayılmasını önlemek ve doğruluğu artırmak amacıyla readRecords() yerine aggregate() kullanın. Daha fazla bilgi için Toplanan verileri okuma başlıklı makaleyi inceleyin.

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

Ayrıca aggregate kullanarak verilerinizi toplu şekilde okuyabilirsiniz.

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

Önemli: Health Connect, izin verilme zamanından önceki 30 güne ait verileri okuyabilir. Uygulamanızın 30 günden eski kayıtları okumasını istiyorsanız PERMISSION_READ_HEALTH_DATA_HISTORY iznini kullanın. Daha fazla bilgi için Okuma kısıtlamaları bölümüne bakın.

Video eğiticiler

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

• Health Connect'te izinleri yönetme
• Health Connect'te okuma ve yazma
• Mükemmel bir Health Connect entegrasyonu için ipuçları

Kaynaklar

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

• Health Connect SDK'sı (Jetpack'te kullanılabilir): Health Connect API'sini kullanmak için bu SDK'yı uygulamanıza ekleyin.
• API referansı: Health Connect API'si için Jetpack referansına göz atın.
• Veri türlerinin kullanımını beyan edin: 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 deposuna ve codelab alıştırmasına bakın.

Not: Uygulamanızın yeni veri türleri gerektirmesi durumunda başka bir istek için başvuruyorsanız hem yeni hem de mevcut veri türlerini eklemeniz ve artık ihtiyacınız olmayan veri türlerini çıkarmanız gerekir. Yalnızca belirli veri türlerine erişimi kaldırmanız gerekiyorsa mevcut tüm veri türlerinizi ekleyin ancak artık ihtiyacınız olmayan veri türlerini hariç tutun.

Sonraki adımlar

Health Connect'te aşağıdaki gibi işlemleri nasıl yapacağınızı öğrenmek için Sık kullanılan iş akışları başlıklı makaleyi inceleyin:

• Veri yazma
• Ham verileri okuma
• Birleştirilmiş verileri okuma