راه اندازی API در اندروید

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

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

راه‌های راه‌اندازی دستگاه‌های Matter

فرآیند راه‌اندازی می‌تواند آغاز شود:

درخواست راه‌اندازی را مستقیماً در برنامه خود ثبت کنید

درخواست راه‌اندازی مستقیم در برنامه می‌تواند توسط یک دکمه در برنامه فعال شود و به دو روش قابل انجام است:

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

برای درخواست راه اندازی:

  1. یک ActivityResultLauncher در activity خود مقداردهی اولیه کنید. اگر کاربر دستگاه را روی 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 شامل داده‌های payload دریافتی بسازید و گزینه‌ی راه‌اندازی دستگاه را با استفاده از setStoreToGoogleFabric به Google fabric تنظیم کنید:

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

    اگر می‌خواهید دستگاه را علاوه بر فابریک خودتان، به فابریک گوگل نیز متصل کنید، سرویس راه‌اندازی خود را با 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 فرستنده‌ی intent را برگرداند، فرستنده را اجرا کنید:

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

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

اگر نیاز به راه‌اندازی چندین فابریک Matter روی یک دستگاه دارید، برای راه‌اندازی API در اندروید به Multi-admin مراجعه کنید.

نقطه ورود راه‌اندازی برای اسکن Fast Pair یا QR-code (فقط اندروید)

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

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

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

جریان راه‌اندازی با استفاده از ACTION_START_COMMISSIONING
شکل ۱ : جریان راه‌اندازی با استفاده از ACTION_START_COMMISSIONING

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

زمانی که کاربر برنامه شما را انتخاب کرد، برنامه شما اجرا شده و با یک هدف ACTION_START_COMMISSIONING به اکتیویتی انتخاب شده هدایت می‌شود.

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

همچنین می‌توانید از جریان FastPair در سناریوهای چند ادمینی استفاده کنید. برای اطلاعات بیشتر، به Multi-admin for Commissioning API on Android مراجعه کنید.

مدیریت هدف ورودی

پس از اجرای اکتیویتی شما، باید هدف ACTION_START_COMMISSIONING موجود را بررسی کرده و payload را بازیابی کند:

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)
}

مقدار payload که null نباشد، نشان می‌دهد که کاربر قبلاً یا کد QR دستگاه را اسکن کرده یا کلید جفت‌سازی را وارد کرده است. مقدار payload null به این معنی نیست که راه‌اندازی باید لغو شود.

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

نمونه‌ای از اعلان نیم‌صفحه‌ای اندروید
شکل ۱: نمونه‌ای از اعلان نیم‌صفحه‌ای اندروید

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

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

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

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

گوگل اکیداً توصیه می‌کند که از API راه‌اندازی (Commissioning API) به عنوان ابزار اصلی خود برای اشتراک‌گذاری دستگاهی که قبلاً روی فابریک خودتان راه‌اندازی کرده‌اید با فابریک گوگل استفاده کنید. API اشتراک‌گذاری محدودیت‌های خود را دارد و باید برای موارد استفاده دیگر رزرو شود.

چرا باید از API راه‌اندازی به جای API اشتراک‌گذاری استفاده کنید؟

API راه‌اندازی به شما امکان می‌دهد تا اشتراک‌گذاری یک دستگاه را مستقیماً با Google fabric آغاز کنید، که در صورت امکان، روش ترجیحی است. با استفاده از API اشتراک‌گذاری، مراحل بیشتری برای کاربر نهایی مورد نیاز است. به عنوان مثال، کاربر نهایی باید GHA نصب کرده باشد و باید بداند که در طول فرآیند، GHA انتخاب کند تا موفقیت‌آمیز باشد.

برای استفاده از API راه‌اندازی، باید پنجره راه‌اندازی را باز کنید و API راه‌اندازی را فراخوانی کنید، همانطور که در نحوه استفاده از API راه‌اندازی به عنوان کمیسر ثانویه امور توضیح داده شده است.

چه زمانی باید از Share API استفاده کنید؟

شما می‌توانید از API اشتراک‌گذاری استفاده کنید تا به کاربر نهایی اجازه دهید یک برنامه واجد شرایط را برای اشتراک‌گذاری عمومی یک دستگاه با سایر اکوسیستم‌های Matter انتخاب کند.