Commissioning API ב-Android

Commissioning API מאפשר לאפליקציה להעביר עמלות ל-:

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

סימון תמיכה בהפעלת Matter

אם אתם משתמשים ב-Google Home Mobile SDK כדי לקבל עמלות, עליכם להוסיף את שם חבילת האפליקציה ב-Google Home Developer Console, להטמיע את ממשקי ה-API של Matter ולציין שהאפליקציה תומכת בקבלת עמלות Matter על ידי טיפול בכוונה ACTION_COMMISSION_DEVICE.

מוסיפים את intent-filter הבא להצהרה application בקובץ AndroidManifest.xml:

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

לקבלת עזרה, אפשר לעיין במניפסט לדוגמה של אפליקציה.

דרכים לקבלת עמלות על מכשירים בתקן 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 Fabric וגם ל-fabric משלכם, צריך להגדיר את שירות ההקצאה באמצעות 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:

• לבדים בודדים
• בבדיקה של כמה בדים

לבדים בודדים

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

אחרי שהמשתמש בוחר את האפליקציה, היא מופעלת ומופנית לפעילות שנבחרה באמצעות כוונה (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)
}

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

השבתת התראות על מודעות Discovery שאפשר לקבל עליהן עמלות

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

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

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

הטמעה של ה-API הזה מופיעה ב-Google Home Sample App for Matter. מידע נוסף זמין במאמר HalfSheetSuppressionObserver.kt.

איך משתפים עם 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 API, כפי שמתואר במאמר איך משתמשים ב-Commissioning API בתור גורם מזמין משני ב-Matter.

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

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