Health Connect'i kullanmaya başlama

Bu rehberde, Health Connect'i uygulamanızda 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 üzerinden gönderdiği tüm istekleri ele almaktan sorumludur. Bu istekler arasında verilerin depolanması ve okuma ve 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 birkaç sürümünün nasıl işleneceği özetlenmektedir.

Android 14

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

Android 13 ve önceki sürümler

Health Connect, Android 13 (API Düzeyi 33) ve daha eski sürümlerde Android Framework'ün bir parçası değildir. Bununla birlikte, Google Play Store'dan Health Connect uygulamasını yüklemeniz gerekir.

Uygulamanızı Android 13 ve önceki bir sürümde 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 ana ekranda varsayılan olarak görünmez. Health Connect'i açmak için Ayarlar > Uygulamalar > Health Connect'e gidin veya Health Connect'i Hızlı Ayarlar menünüze ekleyin.

Ayrıca Health Connect'te, Health Connect'te depolanan sağlık verilerinin cihaz kilitliyken kötü amaçlı taraflardan korunması için kullanıcının bir PIN, desen veya şifreyle ekran kilidini etkinleştirmesi gerekir. Bir ekran kilidi ayarlamak için Ayarlar > Güvenlik > Ekran kilidi'ne gidin.

2. Adım: Health Connect SDK'yı uygulamanıza ekleyin

Health Connect SDK, Health Connect uygulamasındaki veri deposuna yönelik işlemler sırasında istek göndermek için Health Connect API'nin kullanılmasından sorumludur.

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alpha02"
  ...
}

En son sürüm için Health Connect sürümlerine göz atın.

Not: Health Connect SDK, Android 8 (API düzeyi 26) veya sonraki sürümleri destekler. Health Connect uygulaması ise yalnızca Android 9 (API düzeyi 28) veya sonraki sürümlerle uyumludur. Yani üçüncü taraf uygulamaları, Android 8 yüklü kullanıcıları destekleyebilir ancak yalnızca Android 9 veya sonraki sürümlere sahip kullanıcılar 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.

İzinleri beyan et

Sağlık ve fitness verilerine erişim hassastır. Health Connect, işlemleri okuma ve yazma işlemleri için güvenlik katmanı uygulayarak kullanıcı güvenini korur.

Gerekli veri türlerine göre AndroidManifest.xml dosyası için okuma ve yazma izinleri tanımlayın. Formu doldurduktan sonra erişim istediğiniz izin grubunu kullandığınızdan emin olun.

Health Connect, standart Android izin beyanı biçimini kullanır. İzinleri <uses-permission> etiketleriyle 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 tam listesi ve bunlara karşılık gelen veri türleri için Veri türlerinin listesi bölümüne bakın.

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

Android manifestinizde, uygulamanızın gizlilik politikasını görüntüleyen bir Etkinlik bulunmalıdır. Bu etkinlik, uygulamanızın istenen izinlere yönelik gerekçesini ifade eder ve kullanıcı verilerinin nasıl kullanıldığını ve işlendiğini açıklar.

Bu etkinliği, kullanıcı Health Connect izin ekranındaki gizlilik politikası bağlantısını tıkladığında uygulamaya gönderildiği ACTION_SHOW_PERMISSIONS_RATIONALE niyetini 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'ye giriş noktasıdır. Uygulamanın Health Connect uygulamasındaki veri deposunu kullanmasına olanak tanır. Temel depolama katmanıyla olan bağlantısını otomatik olarak yönetir ve giden istekler ile gelen yanıtların tüm IPC'si ile serileştirilmesi işlemlerini gerçekleştirir.

İstemci örneği almak için önce Android manifestinizde Health Connect paket adını tanımlayın.

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

Ardından, Etkinliğinize giderek Health Connect'in getSdkStatus kullanılarak yüklenip yüklenmediğini kontrol edin. Öyleyse bir 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

Not: Bazı cihazlar Health Connect'i desteklemeyebilir. Örneğin, şu anda yalnızca Android 9 veya sonraki sürümleri çalıştıran cihazlar desteklenmektedir. Kullanıcının cihazının Health Connect ile uyumlu olup olmadığını kontrol etmek için HealthConnectClient.isApiSupported adresini kullanın. Yanlış yanıtı döndürürse uygulama, kullanıcıdan Health Connect'i yüklemesini istememelidir.

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 istedikleri zaman izin vermesine veya reddetmesine izin verilmelidir.

Bunu yapmak için gerekli veri türlerine yönelik bir izin grubu oluşturun. Öncelikle kümedeki izinlerin Android manifest'inizde tanımlandığından 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ızın verilmiş gerekli izinlere zaten sahip olup olmadığını görmek için getGrantedPermissions adresini kullanın. Aksi takdirde bu izinleri istemek için createRequestPermissionResultContract adresini kullanın. Health Connect izinleri ekranı gösterilir.

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

İzinlerin sabit olduğunu varsaymayın çünkü kullanıcılar bu izinleri istedikleri zaman verebilir veya iptal edebilir. Uygulamanızın verilen izinleri düzenli olarak kontrol etmesi ve iznin kaybedildiği senaryoları işlemesi gerekir.

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

Her şey ayarlandıktan sonra uygulamanızda okuma ve yazma işlemleri gerçekleştirin.

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) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Verileri okuma

readRecords kullanarak verilerinizi tek tek okuyabilirsiniz.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    StepsRecord::class,
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        for (stepRecord in response.records) {
            // Process each step 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, iznin ilk kez verilmesinden önceki 30 güne kadar olan verileri okuyabilir. Ancak, kullanıcı uygulamanızı silerse izin geçmişi kaybolur. Kullanıcı uygulamanızı yeniden yükler ve tekrar izin verirse Health Connect, yeni veri kullanımına izin verildiği tarihten 30 gün öncesine kadar olan verileri okuyabilir.

Video eğiticiler

Health Connect özellikleri ve sorunsuz bir entegrasyon sağlamak için en iyi uygulama yönergeleri hakkında daha fazla bilgi veren şu 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 (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.
• API İstek Geliştirici Beyan Formu: Veri türlerini okuma ve yazma erişimi talep etmek için bu formu kullanın. Daha fazla bilgi için Health Connect veri türlerine erişim isteme bölümüne bakın.
• İsteğe bağlı GitHub kod örneği ve codelab: Başlamanıza yardımcı olması için GitHub kod örneği repository ve codelab alıştırmasına göz atın.

Not: Uygulamanızın yeni veri türleri gerektirmesi ihtimaline karşı başka bir istek için başvuruyorsanız hem yeni hem de mevcut veri türlerini dahil etmeniz, artık ihtiyacınız olmayan veri türlerini hariç tutmanız gerekir. Yalnızca belirli veri türlerine erişimi kaldırmanız gerekiyorsa mevcut veri türlerinizin tümünü dahil edin ancak artık ihtiyacınız olmayan veri türlerini hariç tutun.

Sonraki adımlar

Health Connect'te aşağıdaki gibi işlemlerin nasıl gerçekleştirileceğini öğrenmek için Yaygın iş akışları sayfasına göz atın:

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