ממשק API להרשאות

לפני שמשתמשים באחד מממשקי ה-API של Home, צריכה להיות לאפליקציה הרשאה לגשת למכשירים בבית של המשתמש, שנקראים ב-API המבנה. באמצעות Permissions API, המשתמשים יכולים להשתמש בחשבון Google שלהם כדי להעניק לאפליקציות Home APIs גישה למכשירים בבית.

שילוב של Permissions API

לפני שממשיכים, חשוב לוודא שפעלתם לפי ההוראות במאמר איך מפעילים את דף הבית. מופע ה-homeManager מהשלב הזה ישמש בכל הדוגמאות של ההרשאות שבהמשך.

קודם כול צריך לרשום ActivityResultCaller ב-SDK. לדוגמה, כך האפליקציה לדוגמה מטפלת בכך:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

בדיקת ההרשאות

לפני ששולחים בקשות להרשאות, מומלץ לבדוק אם משתמש האפליקציה כבר הביע הסכמה. כדי לעשות זאת, צריך לבצע קריאה ל-method‏ hasPermissions() של מופע הבית כדי לקבל Flow של ערכים של PermissionsState:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

אם הבדיקה מחזירה PermissionsState של NOT_GRANTED או PERMISSIONS_STATE_UNAVAILABLE, צריך לבקש הרשאות. אם הבדיקה מחזירה PermissionsState של GRANTED אבל קריאה חוזרת ל-structures() לא מחזירה מבנים, סימן שהמשתמש ביטל את הגישה לאפליקציה דרך דף ההגדרות של Google Home app (GHA), וצריך לבקש הרשאות. אחרת, למשתמש כבר אמורה להיות גישה.

בקשת הרשאות

צריך להעניק לאפליקציה הרשאה כדי שתהיה לה גישה למבנים ולמכשירים במבנה נתון.

אם המשתמש עדיין לא העניק הרשאות, משתמשים ב-method‏ requestPermissions() של המכונה הראשית כדי להפעיל את ממשק המשתמש של ההרשאות ולעבד את התוצאה:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

כדי שאפשר יהיה להפעיל את ממשק המשתמש של ההרשאות בצורה תקינה, צריך כבר להגדיר את OAuth לאפליקציה.

מתן הרשאות

עכשיו אמורה להיות לך אפשרות להפעיל את האפליקציה ולבקש מהמשתמש להעניק הרשאות. סוג המשתמשים שיכולים להעניק הרשאה וסוגים של מכשירים שאפשר להעניק להם הרשאות ישתנו בהתאם לכך שרשמתם את האפליקציה ב-Google Home Developer Console.

כדי לפרסם אפליקציה באמצעות ממשקי ה-API של Home, נדרש רישום Developer Console. אין צורך לבדוק את ממשקי ה-API של Home ולהשתמש בהם.

אם אפליקציה לא רשומה ב-Developer Console, היא תהיה במצב לא מאומת. מומלץ להשתמש באפשרות הזו כדי לבדוק את השימוש בממשקי ה-API של Home:

• רק משתמשים שנרשמו כמשתמשי בדיקה במסוף OAuth יכולים להקצות הרשאות לאפליקציה. יש מגבלה של 100 משתמשי בדיקה לאפליקציה לא מאומתת.

• לאפליקציה לא מאומתת תהיה גישה למכשירים מכל סוגי המכשירים שנתמכים על ידי OAuth ל-Home APIs (רשימת סוגי המכשירים מופיעה ב-Developer Console). כל המכשירים במבנה יקבלו גישה.

אם אפליקציה רשומה ב-Developer Console וניתנה לה גישה לסוג מכשיר אחד או יותר, והושלם אימות המותג ל-OAuth, היא תהיה במצב מאומת. המצב הזה נדרש כדי להשיק אפליקציה בסביבת הייצור:

• מגבלות על משתמשי בדיקה לא חלות יותר. כל משתמש יכול להעניק הרשאה לאפליקציה.
• המשתמש יכול להעניק הרשאה רק לסוגי המכשירים שאושרו ב-Developer Console.

עכשיו, אחרי שהגדרתם את OAuth, הקריאה של האפליקציה ל-requestPermissions() מפעילה את תיבת הדו-שיח הבאה:

1. המשתמש מתבקש לבחור את חשבון Google שבו הוא רוצה להשתמש.
2. המשתמש מתבקש לבחור את המבנה שאליו הוא רוצה להעניק לאפליקציה גישה.
   1. באפליקציה לא מאומתת, כל סוגי המכשירים שנתמכים ב-Home APIs זמינים לאפליקציה.
   2. באפליקציה מאומתת, המשתמש יכול להעניק הרשאה רק לסוגי המכשירים שאושרו ב-Developer Console.
   3. לגבי סוגי מכשירים רגישים שיש לאפליקציה גישה לניהול שלהם, המשתמש יכול להגביל את הגישה לפי מכשיר. לדוגמה, אם למשתמש יש שלוש נעילות, הוא יכול להעניק גישה רק לאחת מהן.

אחרי שמאשרים את ההרשאה, האפליקציה יכולה להשתמש ב-Home APIs כדי לקרוא את המצב של המכשירים במבנה ולשלוט בהם. אם המשתמש לא נותן לאפליקציה הרשאה לגשת למכשיר מסוים או למכשיר רגיש, האפליקציה לא תוכל להשתמש בממשקי ה-API של Home כדי לגשת למכשיר, לשלוט בו או לבצע אוטומציה שלו.

שינוי ההרשאות

כדי להעניק הרשאה לגשת למכשירים במבנה אחר, אפשר להפעיל את בורר החשבונות כדי לאפשר למשתמש לבחור את חשבון Google ואת המבנה שאליו הוא רוצה לעבור. במהלך התהליך הזה, המסך של בקשת ההסכמה יוצג שוב למשתמש, גם אם הוא הביע הסכמה בעבר.

כדי לעשות זאת, צריך לבצע קריאה חוזרת ל-requestPermissions() עם הדגל forceLaunch מוגדר ל-true:

homeManager.requestPermissions(forceLaunch=true)

ביטול הרשאות

משתמשים יכולים לבטל גישה שניתנה להם בעבר:

1. דרך הדף 'החשבונות שלי ב-Google' > נתונים ופרטיות > אפליקציות ושירותים של צד שלישי. הפעולה הזו תבטל את אסימון ה-OAuth שהונפק כשהתקבלה ההסכמה הראשונית, ותבטל את הגישה לכל מופע של האפליקציה שהמשתמש השתמש בו בכל המכשירים (טלפונים) והמבנים.

2. בדף GHA > הגדרות > אפליקציות מקושרות. לחיצה על settings ב-GHA תעביר אתכם לדף הגדרות. לאחר מכן, לוחצים על המשבצת אפליקציות מקושרות כדי לעבור לדף שנראה דומה למסך ההסכמה. בדף הזה המשתמש יכול להסיר את הגישה לאפליקציה. הוא יכול להשתמש באותו דף כדי לשנות את סוגי המכשירים או מכשירים רגישים ספציפיים שיש להם גישה לאפליקציה.

3. דרך הדף 'אפליקציות מקושרות' ישירות באינטרנט.

הרשאות OkGoogle

הפקודה okGoogle היא פקודת ברמת המבנה, וניתן להשתמש בה כדי להפוך כל מכשיר במבנה לאוטומטי. עם זאת, יכול להיות שאפליקציה עם Home APIs לא תהיה לה גישה לכל המכשירים. בטבלה הבאה מוסבר איך מתבצעת אכיפת ההרשאות במקרים כאלה.