Egzersiz rotası ekleme

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

Egzersiz rotaları, kullanıcıların ilişkili egzersiz etkinlikleri için bir GPS rotasını izlemesine ve antrenmanlarının haritalarını diğer uygulamalarla paylaşmasına olanak tanır.

Özellik kullanılabilirliği

Kullanıcının cihazının Health Connect'te egzersiz rotalarını destekleyip desteklemediğini belirlemek için istemcide FEATURE_PLANNED_EXERCISE uygulamasının kullanılabilirliğini kontrol edin:

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

  // Feature is available
} else {
  // Feature isn't available
}

Daha fazla bilgi için Özelliklerin kullanılabilirliğini kontrol etme başlıklı makaleyi inceleyin.

Bu kılavuzda, kullanıcıdan nasıl izin isteyeceğinizle ilgili bilgiler verilmekte ve uygulamaların egzersiz oturumu kapsamında rota verilerini yazma iznini nasıl alacağı açıklanmaktadır.

Egzersiz rotaları için okuma ve yazma işlevleri şunlardır:

  1. Uygulamalar, egzersiz rotaları için yeni bir yazma izni oluşturur.
  2. Ekleme işlemi, alanı olarak rotayı içeren bir egzersiz oturumu yazılarak yapılır.
  3. Okuma:
    1. Oturum sahibi için verilere oturum okuma işlemi kullanılarak erişilir.
    2. Üçüncü taraf uygulamasından, kullanıcının rotayı tek seferlik okumasına izin veren bir iletişim kutusu aracılığıyla.

Kullanıcının yazma izni yoksa ve rota ayarlanmamışsa rota güncellenmez.

Uygulamanızın rota yazma izni varsa ve rotası olmayan bir oturum nesnesi ileterek oturumu güncellemeye çalışırsa mevcut rota silinir.

Gerekli izinler

Antrenman rotasına erişim aşağıdaki izinlerle korunur:

  • android.permission.health.READ_EXERCISE_ROUTE
  • android.permission.health.WRITE_EXERCISE_ROUTE

Uygulamanıza egzersiz rotası özelliği eklemek için öncelikle ExerciseSession veri türü için yazma izni isteyerek başlayın.

Egzersiz rotası yazabilmek için bildirmeniz gereken izin şudur:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_EXERCISE_ROUTE" />
...
</application>

Egzersiz rotasını okumak için aşağıdaki izinleri istemeniz gerekir:

<application>
  <uses-permission
android:name="android.permission.health.READ_EXERCISE_ROUTE" />
...
</application>

Ayrıca, her rota bir egzersiz oturumuyla ilişkilendirildiğinden (bir oturum = bir antrenman) egzersiz izni beyan etmeniz gerekir.

İzin istemek için uygulamanızı Health Connect'e ilk kez bağladığınızda PermissionController.createRequestPermissionResultContract() yöntemini kullanın. İsteyebileceğiniz birkaç izin şunlardır:

  • Rota verileri de dahil olmak üzere sağlık verilerini okuma: HealthPermission.getReadPermission(ExerciseSessionRecord::class)
  • Rota verileri de dahil olmak üzere sağlık verilerini yazma: HealthPermission.getWritePermission(ExerciseSessionRecord::class)
  • Egzersiz rotası verilerini yazma: HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

Kullanıcıdan izin isteme

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

Bunun için gerekli veri türleri için bir izin grubu oluşturun. Gruptaki izinlerin önce Android manifestinizde tanımlandığından emin olun.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::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ı yönetmesi gerekir.

Egzersiz oturumu kaydında yer alan bilgiler

Her egzersiz oturumu kaydı aşağıdaki bilgileri içerir:

  • Egzersiz türü (ör. bisiklet).
  • Enlem, boylam ve yükseklik gibi bilgileri içeren egzersiz rotası.

Desteklenen toplamalar

Bu veri türü için desteklenen toplama işlemi yok.

Örnek kullanım

Bir oturumdan rota isteyin veya rota yazın.

Bir oturumdan rota isteğinde bulunma

Health Connect'te bir oturumu okuma ve bu oturumdan rota isteme adımları:

suspend fun readExerciseSessionAndRoute() {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofHours(1))

    val grantedPermissions =
        healthConnectClient.permissionController.getGrantedPermissions()
    if (!grantedPermissions.contains(
          HealthPermission.getReadPermission(ExerciseSessionRecord::class))) {
        // The user doesn't allow the app to read exercise session data.
        return
    }

    val readResponse =
      healthConnectClient.readRecords(
        ReadRecordsRequest(
          ExerciseSessionRecord::class,
          TimeRangeFilter.between(startTime, endTime)
        )
      )
    val exerciseRecord = readResponse.records.first()
    val recordId = exerciseRecord.metadata.id

    // See https://developer.android.com/training/basics/intents/result#launch
    // for appropriately handling ActivityResultContract.
    val requestExerciseRouteLauncher = fragment.registerForActivityResul
    (ExerciseRouteRequestContract()) { exerciseRoute: ExerciseRoute? ->
            if (exerciseRoute != null) {
                displayExerciseRoute(exerciseRoute)
            } else {
                // Consent was denied
            }
        }

    val exerciseSessionRecord =
      healthConnectClient.readRecord(ExerciseSessionRecord::class, recordId).record

    when (val exerciseRouteResult = exerciseSessionRecord.exerciseRouteResult) {
        is ExerciseRouteResult.Data ->
            displayExerciseRoute(exerciseRouteResult.exerciseRoute)
        is ExerciseRouteResult.ConsentRequired ->
            requestExerciseRouteLauncher.launch(recordId)
        is ExerciseRouteResult.NoData -> Unit // No exercise route to show
        else -> Unit
    }
  }

  fun displayExerciseRoute(route: ExerciseRoute?) {
    val locations = route.route.orEmpty()
    for (location in locations) {
      // Handle location.
    }
  }

Bir oturumdan rota yazma

Aşağıdaki kodda, egzersiz rotası içeren bir oturumun nasıl kaydedileceği gösterilmektedir:

suspend fun InsertExerciseRoute(healthConnectClient: HealthConnectClient) {
    val grantedPermissions =
        healthConnectClient.permissionController.getGrantedPermissions()
    if (!grantedPermissions.contains(
          getWritePermission(ExerciseSessionRecord::class))) {
        // The user doesn't allow the app to write exercise session data.
        return
    }

    val sessionStartTime = Instant.now()
    val sessionDuration = Duration.ofMinutes(20)
    val sessionEndTime = sessionStartTime.plus(sessionDuration)

    val exerciseRoute =
        if (grantedPermissions.contains(PERMISSION_WRITE_EXERCISE_ROUTE)) ExerciseRoute(
            listOf(
                ExerciseRoute.Location(
                    // Location times must be on or after the session start time
                    time = sessionStartTime,
                    latitude = 6.5483,
                    longitude = 0.5488,
                    horizontalAccuracy = Length.meters(2.0),
                    verticalAccuracy = Length.meters(2.0),
                    altitude = Length.meters(9.0),
                ), ExerciseRoute.Location(
                    // Location times must be before the session end time
                    time = sessionEndTime.minusSeconds(1),
                    latitude = 6.4578,
                    longitude = 0.6577,
                    horizontalAccuracy = Length.meters(2.0),
                    verticalAccuracy = Length.meters(2.0),
                    altitude = Length.meters(9.2),
                )
            )
        )
        else
        // The user doesn't allow the app to write exercise route data.
            null
    val exerciseSessionRecord = ExerciseSessionRecord(
        startTime = sessionStartTime,
        startZoneOffset = ZoneOffset.UTC,
        endTime = sessionEndTime,
        endZoneOffset = ZoneOffset.UTC,
        exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_BIKING,
        title = "Morning Bike Ride",
        exerciseRoute = exerciseRoute,
        metadata = Metadata.manualEntry(
            device = Device(type = Device.TYPE_PHONE)
        ),
    )
    val response = healthConnectClient.insertRecords(listOf(exerciseSessionRecord))
}