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 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 בתוכן המועמס לא אומר שצריך לבטל את ההפעלה.

השבתת התראות על מוצרים שאפשר להרוויח עליהן עמלות

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

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

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

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

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