Commissioning API ב-Android

‫Commissioning API מאפשר לאפליקציה להגדיר:

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

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

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

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

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

כדי לבקש הפעלה ישירות באפליקציה, אפשר ללחוץ על כפתור באפליקציה. יש שתי דרכים לעשות את זה:

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

לבדים בודדים

כדי לבקש הפעלה:

1. מאתחלים ActivityResultLauncher בפעילות. אם המשתמש הפעיל את המכשיר ב-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) שהתקבלו, ומגדירים את האפשרות להקצות את המכשיר ל-Google fabric באמצעות 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 מחזיר את שולח ה-Intent, מפעילים את השולח:

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

לכמה מארגים (כמה אדמינים)

אם אתם צריכים להגדיר כמה מארגים של Matter במכשיר, עיינו במאמר ניהול של כמה אדמינים ב-Commissioning API ב-Android.

נקודת כניסה להפעלה של Matter להתאמה מהירה או לסריקת קוד QR (ב-Android בלבד)

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

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

לבדים בודדים

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

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

אחרי שהמשתמש בוחר את האפליקציה, היא מופעלת ומופנית לפעילות שנבחרה באמצעות Intent מסוג ACTION_START_COMMISSIONING.

לכמה מארגים (כמה אדמינים)

אפשר להשתמש בתהליך ההתאמה המהירה גם בתרחישים עם כמה אדמינים. מידע נוסף זמין במאמר Multi-admin for Commissioning API on Android.

טיפול ב-Intent הנכנס

אחרי שהפעילות מופעלת, היא צריכה לבדוק אם קיים Intent מסוג 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 של המכשיר או הזין את מפתח ההתאמה. ערך מטען ייעודי (payload) של null לא אומר שצריך לבטל את ההפעלה.

הסתרת התראות על גילוי מוצרים שאפשר להרוויח מהם עמלות

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

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

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

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

‫Google ממליצה מאוד להשתמש ב-Commissioning API כאמצעי העיקרי לשיתוף מכשיר שכבר הגדרתם ב-fabric שלכם עם ה-fabric של Google. ל-Share API יש מגבלות, וצריך להשתמש בו רק במקרים אחרים.

למה כדאי להשתמש ב-Commissioning API במקום ב-Share API?

‫Commissioning API מאפשר להפעיל שיתוף של מכשיר ישירות עם Google fabric, וזו השיטה המועדפת כשהיא אפשרית. כשמשתמשים ב-Share API, משתמש הקצה צריך לבצע יותר שלבים. לדוגמה, משתמש הקצה חייב להתקין את GHA ולבחור באפשרות GHA במהלך התהליך כדי להבטיח שההגדרה תצליח.

כדי להשתמש ב-Commissioning API, צריך לפתוח את חלון ה-Commissioning ולקרוא ל-Commissioning API, כמו שמתואר במאמר איך משתמשים ב-Commissioning API בתור ה-Matter commissioner המשני.

מתי כדאי להשתמש ב-Share API?

אתם יכולים להשתמש ב-Share API כדי לאפשר למשתמש הקצה לבחור אפליקציה מתאימה לשיתוף מכשיר באופן כללי עם סביבות אחרות של Matter.