ट्रेनिंग के प्लान

यह गाइड, Health Connect के 1.1.0-alpha11 वर्शन के साथ काम करती है.

Health Connect, प्लान की गई कसरत का डेटा टाइप उपलब्ध कराता है. इससे ट्रेनिंग ऐप्लिकेशन, ट्रेनिंग प्लान लिख सकते हैं और वर्कआउट ऐप्लिकेशन, ट्रेनिंग प्लान पढ़ सकते हैं. रिकॉर्ड की गई कसरत (वर्कआउट) को फिर से पढ़ा जा सकता है, ताकि उपयोगकर्ताओं की परफ़ॉर्मेंस का निजी तौर पर विश्लेषण किया जा सके. इससे उन्हें ट्रेनिंग के लक्ष्यों को हासिल करने में मदद मिलती है.

इस सुविधा को कौन इस्तेमाल कर सकता है

यह पता करने के लिए कि उपयोगकर्ता के डिवाइस पर, Health Connect पर ट्रेनिंग प्लान काम करते हैं या नहीं, क्लाइंट पर FEATURE_PLANNED_EXERCISE की उपलब्धता देखें:

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

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

ज़्यादा जानने के लिए, सुविधा की उपलब्धता देखें लेख पढ़ें.

ज़रूरी अनुमतियां

ट्रेनिंग प्लान का ऐक्सेस, इन अनुमतियों से सुरक्षित होता है:

• android.permission.health.READ_PLANNED_EXERCISE
• android.permission.health.WRITE_PLANNED_EXERCISE

अपने ऐप्लिकेशन के लिए, Play Console और ऐप्लिकेशन के मेनिफ़ेस्ट में इन अनुमतियों का एलान करें:

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

आपको उन सभी अनुमतियों के बारे में बताना होगा जिनका इस्तेमाल आपको अपने डिवाइसों और ऐप्लिकेशन में करना है. आपको यह भी देखना चाहिए कि इस्तेमाल करने से पहले, उपयोगकर्ता ने हर अनुमति दी है या नहीं.

मिलती-जुलती अनुमतियां

ट्रेनिंग प्लान, कसरत के सेशन से जुड़े होते हैं. इसलिए, Health Connect की इस सुविधा का पूरा फ़ायदा पाने के लिए, उपयोगकर्ता को ट्रेनिंग प्लान से जुड़े हर तरह के रिकॉर्ड का इस्तेमाल करने की अनुमति देनी होगी.

उदाहरण के लिए, अगर कोई ट्रेनिंग प्लान, कई रनों के दौरान उपयोगकर्ता की दिल की दर को मेज़र करता है, तो हो सकता है कि डेवलपर को इन अनुमतियों का एलान करना पड़े और उपयोगकर्ता को उन्हें अनुमति देनी पड़े. ऐसा, कसरत के सेशन को रिकॉर्ड करने और बाद में उसका आकलन करने के लिए किया जाता है:

• android.permission.health.READ_EXERCISE
• android.permission.health.READ_EXERCISE_ROUTE
• android.permission.health.READ_HEART_RATE
• android.permission.health.WRITE_EXERCISE
• android.permission.health.WRITE_EXERCISE_ROUTE
• android.permission.health.WRITE_HEART_RATE

हालांकि, अक्सर ट्रेनिंग प्लान बनाने और प्लान के हिसाब से परफ़ॉर्मेंस का आकलन करने वाला ऐप्लिकेशन, ट्रेनिंग प्लान का इस्तेमाल करने और असल कसरत का डेटा लिखने वाले ऐप्लिकेशन से अलग होता है. ऐप्लिकेशन के टाइप के आधार पर, पढ़ने और लिखने की सभी अनुमतियों की ज़रूरत नहीं होती. उदाहरण के लिए, आपको हर तरह के ऐप्लिकेशन के लिए सिर्फ़ इन अनुमतियों की ज़रूरत पड़ सकती है:

ट्रेनिंग प्लान ऐप्लिकेशन	वर्कआउट ऐप्लिकेशन
WRITE_PLANNED_EXERCISE	READ_PLANNED_EXERCISE
READ_EXERCISE	WRITE_EXERCISE
READ_EXERCISE_ROUTE	WRITE_EXERCISE_ROUTE
READ_HEART_RATE	WRITE_HEART_RATE

अहम जानकारी: 'लिखने की अनुमति' का इस्तेमाल करके रिकॉर्ड किए गए डेटा को पढ़ने का ऐक्सेस भी मिलता है. किसी डेटा टाइप के लिए, पढ़ने और लिखने, दोनों की अनुमति का अनुरोध करना ज़रूरी नहीं है.

प्लान किए गए कसरत के सेशन के रिकॉर्ड में शामिल जानकारी

• सेशन का टाइटल.
• कसरत के लिए शेड्यूल किए गए ब्लॉक की सूची.
• सेशन के शुरू और खत्म होने का समय.
• कसरत का टाइप.
• गतिविधि के लिए नोट.
• मेटाडेटा.
• प्लान किए गए कसरत के सेशन के खत्म होने के बाद, यह आईडी अपने-आप लिखा जाता है.

प्लान किए गए कसरत ब्लॉक के रिकॉर्ड में शामिल जानकारी

प्लान किए गए वर्कआउट ब्लॉक में, वर्कआउट के चरणों की सूची होती है. इससे, चरणों के अलग-अलग ग्रुप को दोहराने में मदद मिलती है. उदाहरण के लिए, एक पंक्ति में पांच बार ऐर्म कर्ल, बर्पी, और क्रंच करें.

• ब्लॉक के बारे में जानकारी.
• कसरत के लिए तय किए गए चरणों की सूची.
• दोहराव की संख्या.

प्लान की गई कसरत के स्टेप के रिकॉर्ड में शामिल जानकारी

• चरण के बारे में जानकारी.
• कसरत की कैटगरी.
• कसरत का टाइप.
• परफ़ॉर्मेंस के लक्ष्यों की सूची.
• पूरा होने का लक्ष्य.

इस्तेमाल किए जा सकने वाले एग्रीगेशन

इस डेटा टाइप के लिए, एग्रीगेशन की सुविधा काम नहीं करती.

इस्तेमाल का उदाहरण

मान लें कि कोई उपयोगकर्ता दो दिन बाद 90 मिनट की दौड़ का प्लान बनाता है. इस रन में, झील के चारों ओर तीन चक्कर लगाए जाएंगे. साथ ही, धड़कन की दर को 90 से 110 बीपीएम के बीच बनाए रखने का टारगेट भी होगा.

1. ट्रेनिंग प्लान ऐप्लिकेशन में, उपयोगकर्ता इनके साथ प्लान किया गया कसरत सेशन तय करता है:
   1. रन के शुरू और खत्म होने का समय
   2. कसरत का टाइप (दौड़ना)
   3. लैप (दोहराव) की संख्या
   4. धड़कन की दर के लिए परफ़ॉर्मेंस टारगेट (90 से 110 बीपीएम के बीच)
2. इस जानकारी को कसरत के ब्लॉक और चरणों में बांटा जाता है. साथ ही, ट्रेनिंग प्लान ऐप्लिकेशन इसे PlannedExerciseSessionRecord के तौर पर Health Connect में लिखता है.
3. उपयोगकर्ता, प्लान किया गया सेशन (चल रहा है) करता है.
4. सेशन से जुड़ा कसरत का डेटा इनमें से किसी एक तरीके से रिकॉर्ड किया जाता है:
   1. सेशन के दौरान, पहने जाने वाले डिवाइस से. उदाहरण के लिए, धड़कन की दर. यह डेटा, गतिविधि के रिकॉर्ड टाइप के तौर पर Health Connect में सेव किया जाता है. इस मामले में, HeartRateRecord.
   2. सेशन के बाद, उपयोगकर्ता मैन्युअल तरीके से. उदाहरण के लिए, असल रन के शुरू और खत्म होने का समय बताना. यह डेटा, Health Connect में ExerciseSessionRecord के तौर पर सेव किया जाता है.
5. बाद में, ट्रेनिंग प्लान ऐप्लिकेशन, Health Connect से डेटा पढ़ता है. इससे, उपयोगकर्ता के तय किए गए लक्ष्यों के मुकाबले, असल परफ़ॉर्मेंस का आकलन किया जाता है. यह आकलन, तय किए गए कसरत के सेशन के दौरान किया जाता है.

कसरत का प्लान बनाना और टारगेट सेट करना

उपयोगकर्ता आने वाले समय में अपनी कसरत का प्लान बना सकता है और टारगेट सेट कर सकता है. इसे तय किए गए कसरत के सेशन के तौर पर, Health Connect में लिखें.

इस्तेमाल के उदाहरण में दिए गए उदाहरण में, उपयोगकर्ता ने दो दिन बाद 90 मिनट की दौड़ का प्लान बनाया है. इस रन में, झील के चारों ओर तीन चक्कर लगाए जाएंगे. इस दौरान, धड़कन की दर 90 से 110 बीपीएम के बीच होनी चाहिए.

ऐसा स्निपेट, किसी ऐसे ऐप्लिकेशन के फ़ॉर्म हैंडलर में मिल सकता है जो प्लान किए गए कसरत के सेशन को Health Connect में लॉग करता है. यह इंटिग्रेशन के लिए, इंजेस्ट पॉइंट में भी मिल सकता है. जैसे, ट्रेनिंग देने वाली सेवा के साथ.

// Ensure the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
      HealthPermission.getWritePermission(PlannedExerciseSessionRecord::class))) {
    // The user hasn't granted the app permission to write planned exercise session data.
    return
}

val plannedDuration = Duration.ofMinutes(90)
val plannedStartDate = LocalDate.now().plusDays(2)

val plannedExerciseSessionRecord = PlannedExerciseSessionRecord(
    startDate = plannedStartDate,
    duration = plannedDuration,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    blocks = listOf(
        PlannedExerciseBlock(
            repetitions = 1, steps = listOf(
                PlannedExerciseStep(
                    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
                    exercisePhase = PlannedExerciseStep.EXERCISE_PHASE_ACTIVE,
                    completionGoal = ExerciseCompletionGoal.RepetitionsGoal(repetitions = 3),
                    performanceTargets = listOf(
                        ExercisePerformanceTarget.HeartRateTarget(
                            minHeartRate = 90.0, maxHeartRate = 110.0
                        )
                    )
                ),
            ), description = "Three laps around the lake"
        )
    ),
    title = "Run at lake",
    notes = null
)
val insertedPlannedExerciseSessions =
    healthConnectClient.insertRecords(listOf(plannedExerciseSessionRecord)).recordIdsList
val insertedPlannedExerciseSessionId = insertedPlannedExerciseSessions.first()

कसरत और गतिविधि का डेटा लॉग करना

दो दिन बाद, उपयोगकर्ता असल कसरत का सेशन लॉग करता है. इसे Health Connect में कसरत के सेशन के तौर पर सेव करें.

इस उदाहरण में, उपयोगकर्ता के सेशन की अवधि, तय की गई अवधि से पूरी तरह मैच हुई.

यहां दिया गया स्निपेट, ऐसे ऐप्लिकेशन के फ़ॉर्म हैंडलर में मिल सकता है जो Health Connect में कसरत के सेशन को लॉग करता है. यह डेटा, स्मार्टवॉच के लिए डेटा डालने और एक्सपोर्ट करने वाले हैंडलर में भी मिल सकता है. स्मार्टवॉच, कसरत के सेशन का पता लगाने और उन्हें लॉग करने में सक्षम होती है.

यहां insertedPlannedExerciseSessionId का इस्तेमाल, पिछले उदाहरण से फिर से किया गया है. किसी असली ऐप्लिकेशन में, आईडी का पता लगाने के लिए उपयोगकर्ता को मौजूदा सेशन की सूची से, प्लान किया गया कसरत सेशन चुनना होगा.

// Ensure the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
      HealthPermission.getWritePermission(ExerciseSessionRecord::class))) {
    // The user doesn't granted the app permission to write exercise session data.
    return
}

val sessionDuration = Duration.ofMinutes(90)
val sessionEndTime = Instant.now()
val sessionStartTime = sessionEndTime.minus(sessionDuration)

val exerciseSessionRecord = ExerciseSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    segments = listOf(
        ExerciseSegment(
            startTime = sessionStartTime,
            endTime = sessionEndTime,
            repetitions = 3,
            segmentType = ExerciseSegment.EXERCISE_SEGMENT_TYPE_RUNNING
        )
    ),
    title = "Run at lake",
    plannedExerciseSessionId = insertedPlannedExerciseSessionId,
)
val insertedExerciseSessions =
    healthConnectClient.insertRecords(listOf(exerciseSessionRecord))

स्मार्टवॉच, दौड़ के दौरान उनकी धड़कन की दर को भी रिकॉर्ड करती है. टारगेट की गई रेंज में रिकॉर्ड जनरेट करने के लिए, यहां दिए गए स्निपेट का इस्तेमाल किया जा सकता है.

किसी असल ऐप्लिकेशन में, इस स्निपेट के मुख्य हिस्से, स्मार्टवॉच से मिले मैसेज के लिए हैंडलर में मिल सकते हैं. यह डेटा इकट्ठा होने पर, मेज़रमेंट को Health Connect में लिख देगा.

// Ensure the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
      HealthPermission.getWritePermission(HeartRateRecord::class))) {
    // The user doesn't granted the app permission to write heart rate record data.
    return
}

val samples = mutableListOf<HeartRateRecord.Sample>()
var currentTime = sessionStartTime
while (currentTime.isBefore(sessionEndTime)) {
    val bpm = Random.nextInt(21) + 90
    val heartRateRecord = HeartRateRecord.Sample(
        time = currentTime,
        beatsPerMinute = bpm.toLong(),
    )
    samples.add(heartRateRecord)
    currentTime = currentTime.plusSeconds(180)
}

val heartRateRecord = HeartRateRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    samples = samples,
)
val insertedHeartRateRecords = healthConnectClient.insertRecords(listOf(heartRateRecord))

परफ़ॉर्मेंस टारगेट का आकलन करना

उपयोगकर्ता के वर्कआउट के अगले दिन, रजिस्टर की गई कसरत को वापस पाया जा सकता है. साथ ही, कसरत के लिए सेट किए गए टारगेट की जांच की जा सकती है. इसके अलावा, सेट किए गए टारगेट पूरे हुए हैं या नहीं, यह पता करने के लिए अन्य डेटा टाइप का आकलन किया जा सकता है.

ऐसा स्निपेट, परफ़ॉर्मेंस टारगेट का आकलन करने के लिए, समय-समय पर होने वाली किसी जॉब में मिल सकता है. इसके अलावा, ऐप्लिकेशन में परफ़ॉर्मेंस टारगेट के बारे में सूचना दिखाने और कसरत की सूची लोड करने के दौरान भी ऐसा स्निपेट मिल सकता है.

// Ensure the user has granted all necessary permissions for this task
val grantedPermissions =
     healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.containsAll(
        listOf(
            HealthPermission.getReadPermission(ExerciseSessionRecord::class),
            HealthPermission.getReadPermission(PlannedExerciseSessionRecord::class),
            HealthPermission.getReadPermission(HeartRateRecord::class)
        )
    )
) {
    // The user doesn't granted the app permission to read exercise session record data.
    return
}

val searchDuration = Duration.ofDays(1)
val searchEndTime = Instant.now()
val searchStartTime = searchEndTime.minus(searchDuration)

val response = healthConnectClient.readRecords(
    ReadRecordsRequest<ExerciseSessionRecord>(
        timeRangeFilter = TimeRangeFilter.between(searchStartTime, searchEndTime)
    )
)
for (exerciseRecord in response.records) {
    val plannedExerciseRecordId = exerciseRecord.plannedExerciseSessionId
    val plannedExerciseRecord =
        if (plannedExerciseRecordId == null) null else healthConnectClient.readRecord(
            PlannedExerciseSessionRecord::class, plannedExerciseRecordId
        ).record
    if (plannedExerciseRecord != null) {
        val aggregateRequest = AggregateRequest(
            metrics = setOf(HeartRateRecord.BPM_AVG),
            timeRangeFilter = TimeRangeFilter.between(
                exerciseRecord.startTime, exerciseRecord.endTime
            ),
        )
        val aggregationResult = healthConnectClient.aggregate(aggregateRequest)

        val maxBpm = aggregationResult[HeartRateRecord.BPM_MAX]
        val minBpm = aggregationResult[HeartRateRecord.BPM_MIN]
        if (maxBpm != null && minBpm != null) {
            plannedExerciseRecord.blocks.forEach { block ->
                block.steps.forEach { step ->
                    step.performanceTargets.forEach { target ->
                        when (target) {
                            is ExercisePerformanceTarget.HeartRateTarget -> {
                                val minTarget = target.minHeartRate
                                val maxTarget = target.maxHeartRate
                                if(
                                    minBpm >= minTarget && maxBpm <= maxTarget
                                ) {
                                  // Success!
                                }
                            }
                            // Handle more target types
                            }
                        }
                    }
                }
            }
        }
    }
}