تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

واجهة برمجة التطبيقات قيد التشغيل

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

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

الإشارة إلى توفُّر الدعم لإعداد الطلبات في Matter

إذا كنت تستخدِم Google Home Mobile SDK لإنشاء العمولات، عليك إضافة اسم حزمة التطبيق في Google Home Developer Console، وتنفيذ واجهات برمجة التطبيقات Matter ، والإشارة إلى أنّ تطبيقك يتيح Matter إنشاء العمولات من خلال معالجة طلب ACTION_COMMISSION_DEVICE.

أضِف العنصر intent-filter التالي إلى بيان application ضمن ملف AndroidManifest.xml:

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

يمكنك الاطّلاع على نموذج بيان التطبيق للرجوع إليه.

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

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

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

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

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

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

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

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

اضبط 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")
      }
    }

أنشئ ملفًا من نوع 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.

استخدِم مثيل 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

بعد أن يعرض العنصر CommissioningClient مُرسِل الطلب، يمكنك تشغيل المُرسِل:

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

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

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

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

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

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

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

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

عملية الإعداد باستخدام ACTION_START_COMMISSIONING — **الشكل 1**: عملية الإعداد باستخدام `ACTION_START_COMMISSIONING`

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

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

بعد بدء نشاطك، من المفترض أن يبحث عن نية 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 أنّه يجب إيقاف عملية الإعداد.

إيقاف إشعارات "الاكتشاف" التي يمكن تحقيق الربح منها

*الشكل 1: مثال على إشعار بنصف الشاشة على Android*

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

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

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

يمكن العثور على تنفيذ لواجهة برمجة التطبيقات هذه في Google Home Sample App for Matter. يُرجى الاطّلاع على HalfSheetSuppressionObserver.kt لمزيد من المعلومات.

كيف يمكن مشاركة أجهزة 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 المتكاملة الأخرى.

تحديد المشاكل وحلّها

مشرفون متعددون