واجهة برمجة التطبيقات 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، يمكنك إضافة 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 المقترَحة في أداة اختيار التطبيقات في Commissioning APIs. إذا لم يكن تطبيقك أحد التطبيقات المقترَحة، سيظهر في خيار اختيار تطبيق آخر.

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

للشبكات المتعدّدة (إدارة متعدّدة)

يمكنك أيضًا استخدام عملية "الإقران السريع" في سيناريوهات الإدارة المتعدّدة. لمزيد من المعلومات، يُرجى الرجوع إلى مقالة الإدارة المتعدّدة لواجهة برمجة التطبيقات 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 الأخرى.