Commissioning API ב-Android

ממשק ה-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 באמצעות 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:

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

לבדים בודדים

אפשר להשתמש במסנן ה-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 ולאחזר את מטען הייעוד:

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

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

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

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

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

איך משתפים מכשירי Matter ברשת עם 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.