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

تتيح واجهة Commissioning API للتطبيق إعداد أيّ مما يلي:

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

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

يمكن بدء عملية التشغيل من خلال:

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

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

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

لطلب التشغيل:

  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 Fabric، باستخدام 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 على جهاز، يُرجى الرجوع إلى واجهة برمجة التطبيقات Multi-admin for Commissioning على Android.

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

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

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

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

عملية التشغيل باستخدام ACTION_START_COMMISSIONING
الشكل 1: عملية التشغيل باستخدام ACTION_START_COMMISSIONING

للإشارة إلى إتاحة عملية الإعداد في شبكة 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 API. إذا لم يكن تطبيقك من بين التطبيقات المقترَحة، سيظهر في خيار اختيار تطبيق آخر.

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

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

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

تستخدم ميزة "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.