Matchmaking API

دليل استخدام واجهة برمجة التطبيقات Health Connect Matchmaking API

نظرة عامة

تتيح واجهة برمجة التطبيقات Matchmaking لتطبيقك اكتشاف تطبيقات وأجهزة أخرى يمكنها كتابة بيانات صحية يملك تطبيقك الإذن بقراءتها. يساعد ذلك المستخدمين في ربط مصادر البيانات المفضّلة لديهم بتطبيقك بسهولة أكبر.

تعثر شاشة "المطابقة" على التطبيقات والأجهزة المتوافقة مع Health Connect. بعد ذلك، تتم مقارنة أذونات القراءة المطلوبة في تطبيقك بإمكانات الكتابة في هذه التطبيقات والأجهزة. تعرض الشاشة التطبيقات والأجهزة التي أعلنت عن أذونات الكتابة لنوع سجل واحد على الأقل من أنواع السجلات المحدّدة التي يُسمح لتطبيقك بقراءتها، ولكن لم يتم منح هذه الأذونات بعد.

قبل البدء

يفترض هذا الدليل أنّك قد ضبطت Health Connect في تطبيقك ولديك مثيل من HealthConnectClient.

إعداد الإصدار التجريبي

تتوفّر واجهة برمجة التطبيقات Matchmaking API من خلال تحديث لتطبيق Health Connect يتم طرحه تدريجيًا على الأجهزة المتاحة للاستخدام، ومن المتوقّع أن تتوفّر بنسبة% 100 بحلول أوائل يونيو 2026. لاختبار ميزات المطابقة قبل أن يصبح هذا التحديث متاحًا على نطاق واسع، سجِّل جهازك التجريبي في برنامج Android التجريبي للاستفادة من إمكانية الوصول المبكر.

التحقّق من توفّر تطبيق Health Connect

قبل محاولة استخدام Health Connect، يجب أن يتأكّد تطبيقك من توفُّر Health Connect على جهاز المستخدم. قد لا يكون تطبيق Health Connect مثبَّتًا على جهاز المستخدم، أو قد يكون غير مفعَّل.

استخدِم HealthConnectClient.getSdkStatus() للتحقّق من التوفّر. إذا لم يكن تطبيق 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 المطلوب استبعادها.

اتّبِع الخطوات التالية لدمج Matchmaking API في تطبيقك.

التحقّق من إمكانية إجراء عملية البحث عن لاعبين

قبل عرض نقطة دخول خاصة بميزة "البحث عن شركاء"، استخدِم 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، اعرض نقطة دخول لتشغيل مسار البحث عن لاعبين.

بدء عملية المطابقة

إذا كان من الممكن إجراء عملية الربط، استخدِم createMatchmakingIntent() للحصول على Intent لتشغيل مسار Health Connect، ثم شغِّله باستخدام واجهة برمجة التطبيقات Activity Result:

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

من خلال تشغيل هذا intent، يعرض تطبيق Health Connect شاشة يمكن للمستخدمين من خلالها الاطّلاع على التطبيقات والأجهزة المتوافقة واختيار ربطها لمشاركة البيانات مع تطبيقك.