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

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

• نسيجك ونسيج Google
• النسيج من Google فقط

طُرق تفعيل أجهزة Matter

يمكن بدء عملية التفعيل:

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

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

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

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

للأقمشة الفردية

لطلب تفعيل الميزة:

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

   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 Fabric باستخدام setStoreToGoogleFabric:

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

   إذا أردت تفويض الجهاز لنظام Google Fabric بالإضافة إلى نظامك، اضبط خدمة التفويض باستخدام 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 على جهاز، راجِع إعداد واجهة برمجة التطبيقات "متعدد المشرفين لإعداد الأجهزة" على Android.

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

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

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

للأقمشة الفردية

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

للإشارة إلى توفّر ميزة تفعيل 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 نية.

لشبكات متعددة (متعدد المشرفين)

يمكنك أيضًا استخدام عملية FastPair في سيناريوهات متعددة المشرفين. لمزيد من المعلومات، يُرجى الاطّلاع على واجهة برمجة التطبيقات "متعدد المشرفين" لإعداد الأجهزة على 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
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
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 Fabric، وهي الطريقة المفضّلة عند توفّرها. باستخدام Share API، يجب اتّباع المزيد من الخطوات من قِبل المستخدم النهائي. على سبيل المثال، يجب أن يكون لدى المستخدم النهائي GHA مثبّتًا، ويجب أن يعرف كيفية اختيار GHA أثناء العملية لضمان النجاح.

لاستخدام واجهة برمجة التطبيقات Commissioning API، عليك فتح نافذة التفويض والاتّصال بواجهة برمجة التطبيقات Commissioning API، كما هو موضّح في كيفية استخدام واجهة برمجة التطبيقات Commissioning API كمفوّض ثانوي في Matter.

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

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