راه اندازی API

Commissioning API به برنامه اجازه می دهد تا به یکی از موارد زیر سفارش دهد:

  • پارچه شما و پارچه گوگل.
  • فقط پارچه گوگل.

پشتیبانی از راه اندازی Matter را نشان دهید

اگر از Google Home Mobile SDK برای راه اندازی استفاده می کنید، باید نام بسته برنامه را در Google Home Developer Console اضافه کنید، Matter API های ما را پیاده سازی کنید و نشان دهید که برنامه شما از راه اندازی Matter با مدیریت هدف ACTION_COMMISSION_DEVICE پشتیبانی می کند.

intent-filter زیر را به اعلان application در فایل AndroidManifest.xml خود اضافه کنید:

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

برای مرجع به مانیفست برنامه نمونه ما مراجعه کنید.

راه های راه اندازی دستگاه های 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 از جمله داده‌های بار دریافتی بسازید و با استفاده از setStoreToGoogleFabric ، گزینه سفارش دستگاه را به Google Fabric تنظیم کنید:

    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 را روی یک دستگاه تنظیم کنید، به نحوه استفاده از APIهای راه‌اندازی در حالت چند سرپرست مراجعه کنید.

نقطه ورود راه اندازی موضوع برای جفت سریع یا اسکن کد QR (فقط اندروید)

درخواست راه اندازی با استفاده از جفت سریع یا کد QR در اندروید به دو روش انجام می شود:

برای پارچه های تک

از فیلتر هدف ACTION_START_COMMISSIONING برای ارائه قابلیت راه اندازی کامل برای یک برنامه بدون نیاز به GHA استفاده کنید. هنگام راه اندازی پارچه Google، این شامل اجازه دادن به کاربر برای اختصاص نام به دستگاه می شود.

جریان راه اندازی با استفاده از 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 در انتخابگر برنامه APIs راه اندازی کند. اگر برنامه شما یکی از برنامه های پیشنهادی نیست، در گزینه Choose other app ظاهر می شود.

هنگامی که کاربر برنامه شما را انتخاب کرد، برنامه شما راه اندازی می شود و با هدف ACTION_START_COMMISSIONING به فعالیت انتخابی هدایت می شود.

برای چندین پارچه (چند مدیر)

شما همچنین می توانید از جریان FastPair در سناریوهای چند مدیر استفاده کنید. برای اطلاعات بیشتر، به نحوه استفاده از APIهای راه اندازی در حالت چند مدیر مراجعه کنید.

هدف ورودی را مدیریت کنید

هنگامی که فعالیت شما راه اندازی شد، باید هدف 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 نیست نشان می دهد که کاربر قبلاً کد QR دستگاه را اسکن کرده است یا کلید جفت شدن را وارد کرده است. مقدار محموله null به این معنی نیست که راه اندازی باید متوقف شود.

اعلان‌های کشف سفارشی را سرکوب کنید

نمونه ای از اعلان نیم برگ اندروید
شکل 1: نمونه ای از اعلان نیم برگ اندروید

به‌طور پیش‌فرض، Google Play services در Android از اعلان‌های «نیم برگه» استفاده می‌کنند که نیمه پایینی صفحه دستگاه تلفن همراه را می‌پوشاند تا به کاربران نشانه‌ای فعال مبنی بر اینکه دستگاه‌های قابل سفارش Matter نزدیک هستند، ارائه می‌کند.

برای جلوگیری از وقفه زمانی که برنامه شما در پیش زمینه است، می توانید این اعلان ها را با فراخوانی روش suppressHalfSheetNotification() در Mobile SDK سرکوب کنید. برای اطلاعات بیشتر به مستندات API مراجعه کنید.

اگر برنامه شما بیش از 15 دقیقه در پیش زمینه باشد، سرکوب فعال شده توسط این API به پایان می رسد. برای فعال کردن مجدد suppression پس از یک بازه زمانی، مجدداً suppressHalfSheetNotification() فراخوانی کنید، در غیر این صورت اعلان‌های halfsheet ظاهر می‌شوند.

پیاده‌سازی این API را می‌توانید در Google Home Sample App for Matter پیدا کنید. برای اطلاعات بیشتر به HalfSheetSuppressionObserver.kt مراجعه کنید.

چگونه باید دستگاه های Matter را روی پارچه خود با Google به اشتراک بگذارید؟

Google قویاً توصیه می‌کند که از Commissioning API به‌عنوان وسیله اصلی خود برای اشتراک‌گذاری دستگاهی که قبلاً روی پارچه خودتان با Google Fabric راه‌اندازی کرده‌اید، استفاده کنید. 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 انتخاب کند.

قبلی
عیب یابی
بعدی
چند ادمین