واجهة برمجة التطبيقات 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.

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

يمكنك أيضًا استخدام مسار 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 الأخرى.