Commissioning API ב-Android

ממשק ה-API להקצאת הרשאות מאפשר לאפליקציה להקצות הרשאות לאחד מהבאים:

• הבד שלכם והבד של Google.
• רק בד Google.

דרכים להגדרת מכשירים בתקן Matter

אפשר להתחיל את תהליך ההפעלה:

• ישירות באפליקציה
• באמצעות התאמה מהירה ב-Android.

בקשה להפעלת תכונה ישירות באפליקציה

אפשר לבקש הפעלה ישירות באפליקציה באמצעות לחצן באפליקציה, בשתי דרכים:

• לבד אחד
• לכמה סוגי בד

לבדים בודדים

כדי לבקש הזמנה:

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 באמצעות התכונה 'התאמה מהירה' או סריקת קוד QR (Android בלבד)

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

• לבד אחד
• לכמה סוגי בד

לבדים בודדים

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

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

אחרי שהמשתמש בוחר את האפליקציה שלכם, היא מופעלת ומופנית לפעילות שנבחרה עם intent של 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) לא אומר שצריך לבטל את ההפעלה.

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

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

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

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

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

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