Commissioning API ב-Android

ממשק ה-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, כולל נתוני מטען הייעודי (payload) שהתקבלו, ומגדירים את האפשרות להוסיף את המכשיר לרשת של 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 או סריקת קוד QR (Android בלבד)

יש שתי דרכים לבקש הפעלה באמצעות התאמה מהירה או קוד QR ב-Android:

לבדים בודדים

כדי לספק לאפליקציה יכולת מלאה להפעלה ראשונית בלי צורך ב-GHA, צריך להשתמש במסנן ה-Intent‏ ACTION_START_COMMISSIONING. כשמפעילים מכשיר ברשת Google, זה כולל את האפשרות לאפשר למשתמש להקצות שם למכשיר.

הפעלת Flow באמצעות 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 משמש להכללת האפליקציה ברשימת האפליקציות המוצעות בבורר האפליקציות של ממשקי ה-API להקצאת הרשאות. אם האפליקציה לא מופיעה בין האפליקציות המוצעות, היא מופיעה באפשרות בחירת אפליקציה אחרת.Matter

אחרי שהמשתמש בוחר את האפליקציה שלכם, היא מופעלת ומופנית לפעילות שנבחרה עם כוונת ACTION_START_COMMISSIONING.

לכמה בדים (כמה אדמינים)

אפשר להשתמש בתהליך FastPair גם בתרחישים שבהם יש כמה אדמינים. מידע נוסף זמין במאמר בנושא ניהול כמה אדמינים ב-Commissioning API ב-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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

ערך מטען ייעודי (payload) שאינו null מציין שהמשתמש כבר סרק את קוד ה-QR של המכשיר או הזין את מפתח ההתאמה. ערך של null במטען ייעודי (payload) לא אומר שצריך לבטל את ההפעלה.

הפסקה של התראות על גילוי מוצרים שניתן לקבל עליהם עמלה

דוגמה להודעה בחצי מסך ב-Android
תרשים 1: דוגמה להתראה בחצי גיליון ב-Android

כברירת מחדל, Google Play services ב-Android משתמש בהתראות מסוג 'חצי דף' שמכסות את החצי התחתון של המסך במכשיר נייד, כדי לספק למשתמשים אינדיקציה פרואקטיבית לכך שמכשירים שניתן לקבל עליהם עמלה נמצאים בקרבת מקום.Matter

כדי למנוע הפרעות בזמן שהאפליקציה פועלת בחזית, אפשר להשבית את ההתראות האלה באמצעות קריאה לשיטה suppressHalfSheetNotification(). מידע נוסף זמין במסמכי העזרה של ה-API.

ההשתקה שמופעלת על ידי ה-API הזה מסתיימת אם האפליקציה פועלת בחזית למשך יותר מ-15 דקות. כדי להפעיל מחדש את ההשתקה אחרי זמן קצוב לתפוגה, צריך להתקשר שוב אל suppressHalfSheetNotification(), אחרת יתחילו להופיע התראות של חצי גיליון.

איך משתפים מכשירי Matter ברשת עם Google?

‫Google ממליצה מאוד להשתמש ב-Commissioning API כדרך העיקרית לשיתוף מכשיר שכבר הגדרתם ב-fabric שלכם עם ה-fabric של 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.