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