API تطبیق

راهنمای API برای ایجاد ارتباط با Health Connect.

نمای کلی

رابط برنامه‌نویسی کاربردی تطبیق (Matchmaking API) به برنامه شما اجازه می‌دهد تا برنامه‌ها و دستگاه‌های دیگری را که می‌توانند داده‌های سلامتی را که برنامه شما اجازه خواندن آنها را دارد، بنویسند، کشف کند. این به کاربران کمک می‌کند تا منابع داده مورد علاقه خود را با اصطکاک کمتری به برنامه شما متصل کنند.

صفحه Matchmaking، برنامه‌ها و دستگاه‌های سازگار با Health Connect را پیدا می‌کند. سپس مجوزهای خواندن مورد نیاز برنامه شما را با قابلیت‌های نوشتن آن برنامه‌ها و دستگاه‌ها مطابقت می‌دهد. صفحه، برنامه‌ها و دستگاه‌هایی را نشان می‌دهد که مجوزهای نوشتن را برای حداقل یکی از انواع رکوردهای مشخص شده که برنامه شما مجاز به خواندن آنهاست، اعلام کرده‌اند، اما هنوز اعطا نکرده‌اند.

قبل از اینکه شروع کنی

این راهنما فرض می‌کند که شما قبلاً Health Connect را در برنامه خود پیکربندی کرده‌اید و یک نمونه از HealthConnectClient در دسترس دارید.

تنظیمات بتا

رابط برنامه‌نویسی کاربردی تطبیق (Matchmaking API) از طریق به‌روزرسانی Health Connect که به تدریج در دستگاه‌های تولیدی در حال انتشار است، در دسترس قرار می‌گیرد و انتظار می‌رود تا اوایل ژوئن ۲۰۲۶، ۱۰۰٪ دسترسی به آن فراهم شود. برای آزمایش ویژگی‌های تطبیق قبل از انتشار گسترده این به‌روزرسانی، دستگاه آزمایشی خود را در برنامه بتای اندروید ثبت کنید تا دسترسی زودهنگام داشته باشید.

بررسی در دسترس بودن Health Connect

قبل از تلاش برای استفاده از Health Connect، برنامه شما باید تأیید کند که Health Connect در دستگاه کاربر موجود است. ممکن است Health Connect روی دستگاه کاربر نصب نشده باشد یا غیرفعال باشد.

برای بررسی در دسترس بودن HealthConnectClient.getSdkStatus() استفاده کنید. اگر Health Connect در دسترس نبود، از کاربر بخواهید Health Connect را از فروشگاه Google Play نصب یا به‌روزرسانی کند.

بررسی در دسترس بودن ویژگی‌ها

برای تعیین اینکه آیا دستگاه کاربر از قابلیت مچ‌میکینگ در Health Connect پشتیبانی می‌کند یا خیر، در دسترس بودن FEATURE_MATCHMAKING را بررسی کنید:

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

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

پیاده‌سازی

جریان تطبیق با استفاده از MatchmakingRequest راه‌اندازی می‌شود. این درخواست مشخص می‌کند که برنامه شما چه نوع رکوردهایی را می‌خواهد جمع‌آوری کند و به شما امکان می‌دهد منابع داده خاصی مانند برنامه‌ها یا دستگاه‌ها را شامل یا حذف کنید:

• recordTypes : مجموعه‌ای از کلاس‌های Record مانند StepsRecord::class . اگر خالی باشد، جریان تمام انواع رکوردی را که برنامه شما مجوزهای خواندن آنها را دارد، در نظر می‌گیرد.
• includedDataSources : مجموعه‌ای از اشیاء DataOrigin که منحصراً باید شامل شوند.
• excludedDataSources : مجموعه‌ای از اشیاء DataOrigin که باید حذف شوند.

برای ادغام API تطبیق (Matchmaking API) در برنامه خود، این مراحل را دنبال کنید.

بررسی کنید که آیا امکان جفت‌یابی وجود دارد یا خیر

قبل از نمایش نقطه ورود matchmaking، از checkIfMatchmakingIsPossible() برای تعیین وجود برنامه‌ها یا دستگاه‌های منطبق مرتبط با انواع رکورد درخواستی استفاده کنید:

suspend fun checkMatchmakingPossible(healthConnectClient: HealthConnectClient) {
    val request = MatchmakingRequest(recordTypes = setOf(StepsRecord::class))
    val response = healthConnectClient.checkIfMatchmakingIsPossible(request)

    if (response.isMatchmakingPossible) {
        // Relevant apps or devices found. Show entry point to launch flow.
    } else {
        // Handle case where no new data sources are available
    }
}

توصیه می‌کنیم به طور مداوم بررسی کنید که آیا امکان تطبیق وجود دارد یا خیر. کاربران ممکن است بعداً برنامه‌های اضافی نصب کنند یا دستگاه‌هایی را با انواع داده‌های سازگار با یکدیگر متصل کنند. یک رویکرد رایج این است که هر بار که برنامه شما شروع می‌شود، بررسی کنید. اگر مقدار true را برگرداند، یک نقطه ورود برای شروع جریان تطبیق نشان دهید.

جریان Matchmaking را راه‌اندازی کنید

اگر امکان تطبیق وجود دارد، از createMatchmakingIntent() برای دریافت یک Intent جهت راه‌اندازی جریان Health Connect استفاده کنید، سپس آن را با استفاده از API نتیجه فعالیت (Activity Result API) راه‌اندازی کنید:

// Create the matchmaking launcher
val matchmakingLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // Matchmaking finished successfully.
        // User successfully granted at least one permission.
    } else {
        // User canceled flow or didn't grant permissions.
    }
}

fun launchMatchmaking(healthConnectClient: HealthConnectClient) {
    val request = MatchmakingRequest(recordTypes = setOf(StepsRecord::class))
    val intent = healthConnectClient.createMatchmakingIntent(request)
    matchmakingLauncher.launch(intent)
}

با اجرای این هدف، Health Connect صفحه‌ای را نمایش می‌دهد که در آن کاربران می‌توانند برنامه‌ها و دستگاه‌های سازگار را مشاهده کنند و انتخاب کنند که آیا می‌توانند آنها را برای اشتراک‌گذاری داده‌ها با برنامه شما متصل کنند یا خیر.