واجهة برمجة التطبيقات Commissioning API على Android

تتيح واجهة برمجة التطبيقات Commissioning API للتطبيق إمكانية إجراء عملية الإعداد لأحد الخيارَين التاليَين:

• النسيج الخاص بك ونسيج Google
• قماش Google فقط

طُرق إعداد أجهزة Matter

يمكن بدء عملية إيقاف الجهاز باتّباع الخطوات التالية:

• مباشرةً في تطبيقك
• من خلال ميزة "الإقران السريع" على Android

طلب إعداد الجهاز مباشرةً في تطبيقك

يمكن بدء طلب الإعداد مباشرةً في التطبيق من خلال النقر على زر في التطبيق، ويمكن إجراء ذلك بطريقتَين:

• بالنسبة إلى الأقمشة الفردية
• بالنسبة إلى الأقمشة المتعددة

بالنسبة إلى الأقمشة الفردية

لطلب تفويض:

1. ابدأ ActivityResultLauncher في نشاطك. إذا كان المستخدم قد أعدّ الجهاز على شبكة Google، قد تتضمّن النتيجة الاسم الذي خصّصه المستخدم للجهاز عند إعداده.

   private val commissioningLauncher =
     registerForActivityResult(StartIntentSenderForResult()) { result ->
       val resultCode = result.resultCode
       if (resultCode == RESULT_OK) {
           Log.i("CommissioningActivity", "Commissioning success")
     val deviceName =
             CommissioningResult.fromIntentSenderResult(result.resultCode, result.data).deviceName
         } else {
             Log.i("CommissioningActivity", "Commissioning failed")
         }
       }
   

2. أنشئ CommissioningRequest، بما في ذلك بيانات الحمولة المستلَمة، واضبط الخيار على تفعيل الجهاز في بنية Google الأساسية، باستخدام setStoreToGoogleFabric:

   val commissioningRequest = CommissioningRequest.builder()
           .setOnboardingPayload(payload)
           .setStoreToGoogleFabric(true)
     // set all other options that you care about
           .build()
   

   إذا أردت إعداد الجهاز على شبكة Google بالإضافة إلى شبكتك، اضبط خدمة الإعداد باستخدام setCommissioningService في CommissioningRequest.

3. استخدِم مثيل CommissioningClient لبدء عملية الإعداد:

   commissioningClient
     .commissionDevice(commissioningRequest)
     .addOnSuccessListener { result ->
       Log.i("CommissioningActivity", "Commissioning success")
   _commissioningIntentSender.postValue(result)
         }
         .addOnFailureListener { error ->
           Log.i("CommissioningActivity", "Commissioning failed")
     }
   

   حيث يتم تعريف _commissioningIntentSender على النحو التالي:

   private val _commissioningIntentSender = MutableLiveData<IntentSender?>()
       val commissioningIntentSender: LiveData<IntentSender?>
       get() = _commissioningIntentSender
   

4. بعد أن تعرض الدالة CommissioningClient أداة إرسال الهدف، شغِّل أداة الإرسال:

   commissioningIntentSender.observe(this) { sender ->
     if (sender != null) {
       commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build())
     }
   }
   

بالنسبة إلى أقمشة متعدّدة (مشرفون متعدّدون)

إذا كنت بحاجة إلى إعداد عدة شبكات Matter على جهاز، راجِع إعداد عدة مشرفين باستخدام Commissioning API على Android.

نقطة دخول إعداد Matter باستخدام الإقران السريع أو مسح رمز الاستجابة السريعة ضوئيًا (أجهزة Android فقط)

يمكن طلب إعداد الجهاز باستخدام ميزة "الاقتران السريع" أو رمز الاستجابة السريعة على جهاز Android بطريقتَين:

• بالنسبة إلى الأقمشة الفردية
• بالنسبة إلى الأقمشة المتعددة

بالنسبة إلى الأقمشة الفردية

استخدِم فلتر الأهداف ACTION_START_COMMISSIONING لتوفير إمكانية الإعداد الكاملة لتطبيق بدون الحاجة إلى الإذن GHA. عند إعداد الجهاز على شبكة Google، يتضمّن ذلك السماح للمستخدم بتحديد اسم للجهاز.

للإشارة إلى إمكانية إعداد أجهزة Google باستخدام بروتوكول Fabric، أضِف الرمز intent-filter التالي إلى بيان النشاط الذي اخترته ضمن ملف AndroidManifest.xml:

<intent-filter>
  <action android:name="com.google.android.gms.home.matter.ACTION_START_COMMISSIONING" />
  <category android:name="android.intent.category.DEFAULT" />
 </intent-filter>

يُستخدَم intent-filter لتضمين تطبيقك في قائمة التطبيقات المقترَحة Matter في أداة اختيار التطبيقات ضمن واجهات برمجة التطبيقات الخاصة بعملية الإعداد. إذا لم يكن تطبيقك من بين التطبيقات المقترَحة، سيظهر في الخيار اختيار تطبيق آخر.

بعد أن يختار المستخدم تطبيقك، يتم تشغيله وتوجيهه إلى النشاط المحدّد باستخدام ACTION_START_COMMISSIONING intent.

بالنسبة إلى أقمشة متعدّدة (مشرفون متعدّدون)

يمكنك أيضًا استخدام مسار FastPair في سيناريوهات تتضمّن عدة مشرفين. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد عدة مشرفين لواجهة برمجة التطبيقات Commissioning API على Android.

التعامل مع النية الواردة

بعد إطلاق نشاطك، يجب أن يبحث عن الغرض ACTION_START_COMMISSIONING الحالي ويسترد الحمولة:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

val payload = if (Matter.ACTION_START_COMMISSIONING.equals(intent.getAction())) {
      intent.getStringExtra(Matter.EXTRA_ONBOARDING_PAYLOAD)
    } else {
      null
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

تشير قيمة الحمولة التي ليست null إلى أنّ المستخدم قد سبق له إما مسح رمز الاستجابة السريعة الخاص بالجهاز ضوئيًا أو إدخال مفتاح الإقران. لا يعني ظهور قيمة حمولة null أنّه يجب إيقاف عملية الإعداد.

إيقاف إشعارات الاستكشاف المؤهّلة للحصول على عمولة

يستخدم Google Play services في Android تلقائيًا إشعارات "نصف الشاشة" التي تغطي النصف السفلي من شاشة الجهاز الجوّال لتزويد المستخدمين بمؤشر استباقي على توفّر أجهزة Matter قريبة يمكنهم الاستفادة من العروض الترويجية عليها.

لتجنُّب المقاطعات أثناء تشغيل تطبيقك في المقدّمة، يمكنك إيقاف هذه الإشعارات من خلال استدعاء طريقة suppressHalfSheetNotification(). راجِع مستندات واجهة برمجة التطبيقات للحصول على مزيد من المعلومات.

تنتهي مهلة الإيقاف المؤقت الذي تتيحه واجهة برمجة التطبيقات هذه إذا كان تطبيقك في المقدّمة لمدة تزيد عن 15 دقيقة. لإعادة تفعيل ميزة حظر الإشعارات بعد انتهاء المهلة، اتّصِل بالرقم suppressHalfSheetNotification() مرة أخرى، وإلا ستبدأ الإشعارات الصغيرة في الظهور.

كيف يمكن مشاركة أجهزة Matter على شبكتك مع Google؟

تنصحك Google بشدة باستخدام Commissioning API كوسيلة أساسية لمشاركة جهاز سبق لك إعداده على شبكتك الخاصة مع شبكة Google، لأنّ Share API لها قيود ويجب استخدامها في حالات أخرى.

لماذا يجب استخدام Commissioning API بدلاً من Share API؟

تتيح لك واجهة برمجة التطبيقات Commissioning API بدء مشاركة جهاز مباشرةً مع بنية Google الأساسية، وهي الطريقة المفضّلة عند توفّرها. باستخدام Share API، يجب أن يتّخذ المستخدم النهائي خطوات إضافية. على سبيل المثال، يجب أن يكون لدى المستخدم النهائي تطبيق GHA مثبّتًا، ويجب أن يعرف كيفية اختيار GHA أثناء العملية لضمان نجاحها.

لاستخدام Commissioning API، عليك فتح نافذة الإعداد واستدعاء Commissioning API، كما هو موضّح في كيفية استخدام Commissioning API كأداة إعداد ثانوية لأجهزة Matter.

متى يجب استخدام Share API؟

يمكنك استخدام Share API للسماح للمستخدم النهائي باختيار تطبيق مؤهَّل لمشاركة جهاز بشكل عام مع أنظمة Matter المتكاملة الأخرى.