Egzersiz rotası ekleme

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

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

Bu kılavuzda, kullanıcıdan nasıl izin isteneceği hakkında bilgi verilmektedir. Ayrıca, uygulamaların egzersiz oturumu kapsamında rota verileri yazma iznini nasıl aldığı da açıklanmaktadır.

Egzersiz rotaları için okuma ve yazma işlevi şunları içerir:

  1. Uygulamalar, egzersiz rotaları için yeni bir yazma izni oluşturur.
  2. Ekleme, alanı bir rota olan 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 bir rotayı tek seferlik okuma izni vermesine olanak tanıyan bir iletişim kutusu aracılığıyla.

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

Uygulamanızda rota yazma izni varsa ve rota içermeyen bir oturum nesnesi göndererek oturumu güncellemeye çalışırsa mevcut rota silinir.

Gerekli izinler

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

  • android.permission.health.READ_EXERCISE_ROUTES
  • android.permission.health.WRITE_EXERCISE_ROUTE

Uygulamanıza egzersiz rotası özelliği eklemek için belirli bir veri türü için yazma izinleri isteğinde bulunarak başlayın.

Her rota bir egzersiz oturumuyla (bir oturum = bir antrenman) ilişkilendirildiğinden egzersiz izni de belirtmeniz gerekir.

Egzersiz rotaları yazabilmek için beyan etmeniz gereken izin:

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

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

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

İzin istemek için uygulamanızı Health Connect'e ilk kez bağlarken PermissionController.createRequestPermissionResultContract() yöntemini kullanın. İsteyebilirsiniz bazı izinler şunlardır:

  • Rota verileri dahil olmak üzere sağlık verilerini okuma: HealthPermission.getReadPermission(ExerciseSessionRecord::class)
  • Rota verileri 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

Uygulamanızın, istemci örneği oluşturduktan sonra kullanıcıdan izin istemesi gerekir. Kullanıcıların diledikleri zaman izin vermesine veya reddetmesine izin verilmelidir.

Bunun için gerekli veri türleri için bir dizi izin oluşturun. Öncelikle, gruptaki izinlerin Android manifest dosyanızda beyan edildiğinden 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'u kullanın. Aksi takdirde bu izinleri istemek için createRequestPermissionResultContract değerini 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)
  }
}

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

Egzersiz seansı kaydına dahil edilen bilgiler

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

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

Desteklenen toplama işlemleri

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

Örnek kullanım

Bir oturumdan rota isteğinde bulunun veya rota yazın.

Oturumdan rota isteğinde bulunma

Health Connect'te bir oturumu okumak ve bu oturumdan rota isteğinde bulunmak için:

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