واجهة برمجة التطبيقات 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 الأساسية، باستخدام 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 من خلال Fast Pair أو مسح رمز الاستجابة السريعة ضوئيًا (أجهزة Android فقط)

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

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

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

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