Google Health API-এর মাধ্যমে ওয়ার্কআউট অভিজ্ঞতা ডেভেলপ করা

Google Health API, exercise সেশন ডেটা টাইপ ব্যবহার করে ব্যবহারকারীর ওয়ার্কআউট সেশন ও এক্সারসাইজ ইতিহাস ট্র্যাক করে। সেশন হল একটি কন্টেনার যা অ্যাক্টিভিটি মেটাডেটা, পজ ও আবার চালু করার ইভেন্ট, ল্যাপ বা স্প্লিট এবং সারসংক্ষেপ মেট্রিককে একসাথে বান্ডেল করে।

আপনার ব্যবহারকারীদের সেরা অভিজ্ঞতা প্রদান করতে, আপনার অ্যাপ্লিকেশনে কীভাবে ওয়ার্কআউট পড়বেন, লিখবেন এবং গঠন করবেন তা বুঝুন।

যেসব ডেটার ধরন কাজ করে

ওয়ার্কআউট ও অ্যাক্টিভিটি সেশন ট্র্যাক করার জন্য API নিম্নলিখিত ডেটা টাইপ সাপোর্ট করে:

টেবিল: Google Health API ওয়ার্কআউট ডেটার ধরন
ডেটার ধরন উপলভ্য
অপারেশন
সুযোগ
ব্যায়াম
dataType: exercise
filter parameter: exercise
রেকর্ডের ধরন: সেশন

মানানসই ডিভাইস

list, get, reconcile, create, update, batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly

ওয়ার্কআউট সেশন কন্টেনার হিসেবে exercise ডেটার ধরন ব্যবহার করলেও, পরে থাকা যায় এমন ডিভাইস সেশন চলাকালীন বিস্তারিত, হাই-ফ্রিকোয়েন্সি টেলিমেট্রি রেকর্ড করে। Google Health API-তে, এইসব গ্র্যানুলার ইন্ট্রাডে টেলিমেট্রি ডেটার ধরন শুধুমাত্র-পড়ার জন্য এবং তাদের নিজস্ব REST এন্ডপয়েন্টের মাধ্যমে সরাসরি তৈরি বা পরিবর্তন করা যাবে না। REST API-এর মাধ্যমে ওয়ার্ক-আউট সেশন লেখার সময়, exercise ডেটা পয়েন্টের metricsSummary অবজেক্টের মধ্যে মোট ওয়ার্ক-আউট মেট্রিক পাস করুন।

নিম্নলিখিত সারণী exercise.metricsSummary-এর মধ্যে থাকা সারসংক্ষেপ ফিল্ডকে সংশ্লিষ্ট শুধুমাত্র-পঠনযোগ্য ইন্ট্রাডে টেলিমেট্রি ডেটার ধরনের সাথে ম্যাপ করে, যার জন্য আপনি সেই ওয়ার্কআউটের টাইম উইন্ডোতে কোয়েরি করতে পারবেন:

সারসংক্ষেপ ফিল্ড (metricsSummary) ইন্ট্রাডে টেলিমেট্রি ডেটার ধরনের নাম API টেলিমেট্রি ডেটা টাইপ আইডি (শুধুমাত্র পঠনযোগ্য) ফিল্টার ফিল্ড (?filter=) OAuth স্কোপ পড়ার অনুমতি প্রয়োজন
caloriesKcal অ্যাক্টিভ এনার্জি বার্ন হয়েছে active-energy-burned active_energy_burned.interval.start_time activity_and_fitness.readonly
distanceMillimeters দূরত্ব distance distance.interval.start_time activity_and_fitness.readonly
steps ধাপ steps steps.interval.start_time activity_and_fitness.readonly
averageHeartRateBeatsPerMinute হার্ট রেট heart-rate heart_rate.sample_time.physical_time health_metrics_and_measurements.readonly
activeZoneMinutes অ্যাক্টিভ জোন মিনিট active-zone-minutes active_zone_minutes.interval.start_time activity_and_fitness.readonly

নিম্নলিখিত বিভাগে exercise ডেটার ধরন সম্পর্কে প্রযুক্তিগত বিবরণ দেওয়া হয়েছে, যার মধ্যে REST উপস্থাপনার উদাহরণ, জিপিএস রুট ম্যানেজ করা এবং ইন্টিগ্রেশন সংক্রান্ত নির্দেশিকা অন্তর্ভুক্ত।

ওয়ার্ক-আউট সেশন

exercise সেশন ডেটা পয়েন্ট হিসেবে দৈনিক অ্যাক্টিভিটি বা ওয়ার্ক-আউট লিখুন। প্রতিটি ডেটা পয়েন্ট সামগ্রিক সেশন, ইভেন্টের বিরতির বিবরণ (যেমন পজ ও আবার শুরু করার অ্যাকশন) এবং সারাংশ মেট্রিক (যেমন সামগ্রিক দূরত্ব, স্টেপ ও গড় হার্ট রেট) বর্ণনা করে।

সেশন অ্যাট্রিবিউট

কোনও এক্সারসাইজ ডেটা পয়েন্ট স্ট্রাকচার করার সময়, নিম্নলিখিত মূল কম্পোনেন্টগুলি যাচাই করুন:

  • সেশনের সময় (interval): সম্পূর্ণ ওয়ার্কআউট সেশনের শুরু ও শেষের সময়, সেইসাথে সেইসব পয়েন্টে অ্যাক্টিভ থাকা টাইমজোন অফসেট।
  • অ্যাক্টিভিটির ধরন (exerciseType): যে ধরনের অ্যাক্টিভিটি করা হয়েছে (যেমন RUNNING, WALKING, BIKING বা AEROBIC_WORKOUT)। শারীরিক ট্রেনিংয়ের নির্দিষ্ট ধরন উল্লেখ করুন।
  • যে নাম দেখানো হবে (displayName): ওয়ার্কআউট সেশনের জন্য ব্যবহার করা সহজ এমন নাম। REST API-এর মাধ্যমে তৈরি করা হলে, সার্ভার exerciseType-এর জন্য স্থানীয় ভাষায় দেখানো নাম পূরণ করে, যেমন RUNNING-এর জন্য "Run"।
  • অ্যাক্টিভ থাকার সময়সীমা (activeDuration): ওয়ার্ক-আউটের আসল অ্যাক্টিভ সময়, পজ করা বিরতি বাদ দিয়ে। স্ট্যান্ডার্ড ফর্ম্যাটিং Duration ফর্ম্যাট ব্যবহার করে (যেমন, "1800s")। সার্ভারে, activeDuration সেশন interval থেকে exerciseEvents-এ যেকোনও PAUSE/RESUME বা AUTO_PAUSE/AUTO_RESUME ইন্টারভ্যাল বিয়োগ করে গণনা করা হয়।

সারাংশ মেট্রিক

metricsSummary নেস্টেড অবজেক্টে মোট এবং গড় মেট্রিক রয়েছে ব্যায়াম সেশনের পুরো সময়কাল জুড়ে গণনা করা হয়েছে:

  • caloriesKcal: ওয়ার্ক-আউট করার সময় মোট যত অ্যাক্টিভ ক্যালরি খরচ হয়েছে, তা কিলোক্যালরিতে (kcal) পরিমাপ করা হয়।
  • distanceMillimeters: মোট অতিক্রান্ত দূরত্ব, যা মিলিমিটারে পরিমাপ করা হয় যাতে বিভিন্ন ইউনিটের মধ্যে উচ্চ নির্ভুলতা বজায় রাখা যায়।
  • steps: ব্যায়াম করার সময় নেওয়া মোট পদক্ষেপ।
  • averageHeartRateBeatsPerMinute: সেশনের অ্যাক্টিভ মিনিটের সময় ব্যবহারকারীর গড় হার্ট রেট।
  • activeZoneMinutes: ওয়ার্ক-আউট চলাকালীন অর্জিত মোট অ্যাক্টিভ জোন মিনিট।
  • averageSpeedMillimetersPerSecond: প্রতি সেকেন্ডে মিলিমিটারে গড় মুভমেন্ট স্পিড।
  • averagePaceSecondsPerMeter: সেশনের অ্যাক্টিভ মিনিটের সময় গড় গতি, প্রতি মিটারে সেকেন্ড হিসেবে পরিমাপ করা হয়।
  • elevationGainMillimeters: সেশন চলাকালীন মোট উচ্চতা বৃদ্ধি।

ল্যাপ ও স্প্লিট

যেসব ওয়ার্ক-আউটে ল্যাপ (যেমন, ট্র্যাকে দৌড়ানো বা পুলে সাঁতার কাটা) থাকে এবং যেগুলি কাজ করে এমন ডিভাইস থেকে সিঙ্ক করা হয়, সেগুলির ক্ষেত্রে splitSummaries সেশনকে ল্যাপ বা স্প্লিট অনুযায়ী ভাগ করে।

প্রতিটি স্প্লিটে এগুলি থাকে:

  • একটি নির্দিষ্ট startTime এবং endTime।
  • activeDuration সঠিক ল্যাপ টাইম দেখায়।
  • metricsSummary শুধুমাত্র সেই সেগমেন্টের জন্য প্রযোজ্য।
  • বিভাজনের সীমানা নির্ধারণ করার জন্য একটি splitType (যেমন DISTANCE, DURATION, বা MANUAL)।

এক্সারসাইজ ইভেন্ট

সঠিকভাবে অ্যাক্টিভ থাকার সময়সীমা গণনা করতে, exerciseEvents ব্যবহার করে স্টেট ট্রানজিশন (যেমন ম্যানুয়াল বা অটোমেটিক পজ ইভেন্ট) ট্র্যাক করুন।

প্রতিটি ইভেন্টে টাইমস্ট্যাম্প (eventTime) ও ধরন থাকে:

  • START / STOP: ব্যবহারকারী কখন স্পষ্টভাবে রেকর্ড করা শুরু বা বন্ধ করেছেন তার বাউন্ডারি টাইমস্ট্যাম্প দেখায়।
  • PAUSE / RESUME: সেশন কখন ম্যানুয়ালি পজ বা আবার চালু করা হয়েছে তা দেখায়।
  • AUTO_PAUSE / AUTO_RESUME: সেন্সর-চালিত অটো-পজ/আবার চালু করার সুবিধা নির্দেশ করে।

ওয়ার্ক-আউট সেশন লিখুন

ওয়ার্কআউট সেশন তৈরি, আপডেট বা ইমপোর্ট করতে, exercise ডেটা টাইপ কালেকশনে ডেটা পয়েন্ট লিখুন। create dataPoints এন্ডপয়েন্ট ব্যবহার করুন।

REST রিপ্রেজেন্টেশনের উদাহরণ

POST পদ্ধতি ব্যবহার করে কীভাবে ওয়ার্কআউট সেশন লিখতে হয় তা নিম্নলিখিত উদাহরণে দেখানো হয়েছে:

অনুরোধ করুন

POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "platform": "GOOGLE_WEB_API"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageHeartRateBeatsPerMinute": "148",
      "averagePaceSecondsPerMeter": 0.36
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ]
  }
}

রেসপন্স

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "googleWebClientId": "438076457939-example.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "metricsSummary": {
        "caloriesKcal": 380,
        "distanceMillimeters": 5000000,
        "steps": "6200",
        "averagePaceSecondsPerMeter": 0.36,
        "averageHeartRateBeatsPerMinute": "148"
      },
      "exerciseMetadata": {},
      "displayName": "Run",
      "activeDuration": "1800s",
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "updateTime": "2026-04-20T08:35:10.123456Z",
      "createTime": "2026-04-20T08:35:10.123456Z"
    }
  }
}

জিপিএস রুট ও লোকেশন ট্র্যাকিং

API সরাসরি exercise ডেটা পয়েন্টের মধ্যে সেশনের প্রাথমিক সারসংক্ষেপ সেভ করে, তবে লোকেশন ইতিহাস ও জিপিএস রুট কোঅর্ডিনেট আলাদা স্ট্রিম হিসেবে ম্যানেজ করে।

আউটডোর সেশনের জন্য বিস্তারিত রুট ডেটা ডাউনলোড করতে, exportExerciseTcx কাস্টম পদ্ধতি কল করুন। এই এন্ডপয়েন্ট, শিল্পের নির্ধারিত মান Training Center XML (TCX) ফর্ম্যাটে রুট রিটার্ন করে।

জিপিএস রুট এক্সপোর্ট করুন

অনুরোধ করুন

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

রেসপন্স

Content-Type: application/tcx+xml সহ একটি HTTP পেলোড এবং ব্রাউজারকে ফাইল সেভ করার নির্দেশ দেওয়া হেডার।

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Id>2026-04-20T08:00:00Z</Id>
      <Lap StartTime="2026-04-20T08:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>380</Calories>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2026-04-20T08:00:00Z</Time>
            <Position>
              <LatitudeDegrees>37.7749</LatitudeDegrees>
              <LongitudeDegrees>-122.4194</LongitudeDegrees>
            </Position>
            <AltitudeMeters>15.0</AltitudeMeters>
            <DistanceMeters>0.0</DistanceMeters>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

প্রয়োজনীয় সুযোগ ও লোকেশন

জিপিএস রুট ও লোকেশন ট্র্যাকিং ফিচার ব্যবহার করতে, আপনার অ্যাপকে অবশ্যই নিম্নলিখিত OAuth স্কোপের জন্য অনুরোধ করতে হবে:

  • পড়ুন: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • লিখুন: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • পড়ুন: https://www.googleapis.com/auth/googlehealth.location.readonly

নির্দেশিকা

আপনার অ্যাপে ওয়ার্কআউট ট্র্যাকিং ইন্টিগ্রেট করার সময়, এইসব ডিজাইন ও প্রয়োগ সংক্রান্ত নির্দেশিকা অনুসরণ করুন।

অ্যাক্টিভ বনাম মোট সময়সীমা

গতি বা পেস মেট্রিক গণনা করতে, সবসময় activeDuration ব্যবহার করুন, startTime ও endTime-এর মধ্যে পার্থক্য নয়। এটি পজ করা ইন্টারভ্যালকে আপনার মেট্রিককে প্রভাবিত করা থেকে আটকায়।

যেমন, কোনও ব্যবহারকারী সকাল ৮:০০-এ ওয়ার্কআউট শুরু করে ৮:৩৫-এ শেষ করলে, ওয়ার্কআউটের মোট সময়সীমা হল ২,১০০ সেকেন্ড। ব্যবহারকারী যদি ৫ মিনিটের (৩০০ সেকেন্ড) জন্য ওয়ার্কআউট পজ করেন এবং আপনি exerciseEvents-এ PAUSE ও RESUME ইভেন্ট অন্তর্ভুক্ত করেন, তাহলে অ্যাক্টিভ সময়সীমা হল "1800s" (২,১০০ - ৩০০)। API গড় হিসেব করার জন্য অ্যাক্টিভ সময়কাল ব্যবহার করে, মোট দূরত্বকে ২,১০০-এর পরিবর্তে ১,৮০০ সেকেন্ড দিয়ে ভাগ করে।

গতি ও পেস গণনা করা

Google Health API স্পিড ও পেস হিসেব করার জন্য স্ট্যান্ডার্ড ফর্মুলা ব্যবহার করে:

  • স্পিড = distance / time(hour)
  • গতি = time(seconds) / distance

অনুরোধে উল্লেখ করা Accept-Language হেডার দূরত্বের ইউনিট নির্ধারণ করে।

আগেভাগে লোকেশন জানার জন্য অনুরোধ করুন

আপনার অ্যাপ যদি ওয়ার্ক-আউট রুট ম্যাপ করে, তাহলে অ্যাক্টিভিটি ও ফিটনেস স্কোপের পাশাপাশি লোকেশন সংক্রান্ত অনুমতি ও Google Health location স্কোপের জন্য অনুরোধ করুন। জিপিএস ব্যায়াম পর্যালোচনা করার সময় আপনার অ্যাপের কেন লোকেশন স্কোপ প্রয়োজন তা ব্যবহারকারীদের ব্যাখ্যা করুন।

আপনার অ্যাপ লোকেশন স্কোপের (https://www.googleapis.com/auth/googlehealth.location.readonly) অনুরোধ করলে, Google OAuth ব্যবহারকারীকে একটি সম্মতি প্রম্পট দেখায়। আপনার ব্যবহারকারীদের ব্যাখ্যা করুন যে রুট ওভারলে রেন্ডার করতে এবং জিপিএস ট্র্যাক ফাইল (TCX) এক্সপোর্ট করতে এই অনুমতি প্রয়োজন। কোনও ব্যবহারকারী অ্যাক্টিভিটি স্কোপের অনুমতি দিলেও লোকেশন সংক্রান্ত অনুমতি না দিলে, exportExerciseTcx অথরাইজেশন সংক্রান্ত সমস্যা দেখায়, যদিও আপনি এখনও metricsSummary-এ সেশন এগ্রিগেট অ্যাক্সেস করতে পারবেন।

ওয়েবহুক ব্যবহার করে সিঙ্ক করুন

নতুন ওয়ার্কআউট ডেটা উপলভ্য হলে ওয়েবহুক ব্যবহার করে আপনার ব্যাকএন্ডকে বিজ্ঞপ্তি পাঠাতে exercise ডেটা টাইপে সাবস্ক্রাইব করুন। এটি আপনাকে ওয়ার্ক-আউট পরবর্তী অভিজ্ঞতা অটোমেটিক ট্রিগার করতে দেয়।

আপনার সার্ভার কোনও ওয়েবহুক বিজ্ঞপ্তি পেলে, তাতে আপডেট করা ওয়ার্ক-আউটের healthUserId এবং সিভিল টাইম ইন্টারভাল (civilIso8601TimeInterval) থাকে। আপনার সার্ভারকে অবিলম্বে 204 No Content-এর সাথে বিজ্ঞপ্তিটি স্বীকার করতে হবে, অ্যাসিঙ্ক্রোনাসভাবে পেলোড প্রসেস করতে হবে এবং exercise.interval.civil_start_time ফিল্টার ব্যবহার করে রিকনসাইল করা exercise এন্ডপয়েন্ট কোয়েরি করতে হবে (মনে রাখবেন যে exercise শুধুমাত্র civil_start_time-এর মাধ্যমে ফিল্টারিং সমর্থন করে):

GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"

সাবস্ক্রিপশন কীভাবে সেট-আপ করতে হয় সেই সম্পর্কে আরও জানতে, Webhook সাবস্ক্রিপশন দেখুন।

একই ধরনের মেট্রিক বজায় রাখুন

ওয়ার্ক-আউটের সম্পূর্ণ অভিজ্ঞতা প্রদান করতে, exercise সেশন লেখার সময় সারসংক্ষেপ মেট্রিক অন্তর্ভুক্ত করুন এবং বিস্তারিত চার্ট রেন্ডার করার সময় সময়সীমা ফিল্টার ব্যবহার করে শুধু-পড়ার জন্য টেলিমেট্রি এন্ডপয়েন্ট কোয়েরি করুন।

ওয়ার্কআউট সামারি মেট্রিক লিখুন (পাথ লিখুন)

Google Health API-তে সম্পূর্ণ ওয়ার্ক-আউট ইমপোর্ট বা লেখার সময়, ওয়ার্ক-আউটের মোট টেলিমেট্রি মেট্রিক (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute এবং averagePaceSecondsPerMeter) exercise ডেটা পয়েন্টের metricsSummary অবজেক্টের মধ্যে অন্তর্ভুক্ত করুন:

  • POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints

চার্টের জন্য বিস্তারিত ডেটা কোয়েরি করুন (পাথ পড়ুন)

নির্দিষ্ট সেশনের জন্য ওয়ার্কআউট ড্যাশবোর্ড বা চার্ট তৈরি করতে, সেই ওয়ার্কআউটের টাইম উইন্ডোর জন্য রিকনসাইল করা টেলিমেট্রি এন্ডপয়েন্ট কোয়েরি করুন:

  1. civil_start_time ফিল্টার ব্যবহার করে exercise এন্ডপয়েন্ট থেকে ওয়ার্ক-আউট সেশন ফেচ করুন যাতে এটির interval এবং metricsSummary পাওয়া যায়:

    GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"
  2. সেই ফিজিক্যাল টাইম উইন্ডোর জন্য টেলিমেট্রি এন্ডপয়েন্ট কোয়েরি করতে সেশনের interval.startTime এবং interval.endTime ব্যবহার করুন।

  3. exerciseMetadata.hasGps যদি true হয়, তাহলে রুটের স্থানাঙ্ক ডাউনলোড করতে exportExerciseTcx-এ কল করুন।