Permissions API ב-Android

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

שילוב Permissions API

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

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

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

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

לפני שמבקשים הרשאות, מומלץ לבדוק אם המשתמש באפליקציה כבר הביע הסכמה. כדי לעשות זאת, קוראים לשיטה hasPermissions() של מופע Home כדי לקבל 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), ואתם צריכים לבקש הרשאות. אם לא, למשתמש כבר אמורה להיות גישה.

בקשת הרשאות

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

אם המשתמש עדיין לא העניק הרשאות, צריך להשתמש בשיטה 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.

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

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

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

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

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

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

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

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

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

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

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

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

homeManager.requestPermissions(forceLaunch=true)

ביטול הרשאות

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

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

   יכול להיות שהמשתמש יופנה באמצעות קישור עומק לדף המשנה אפליקציות ושירותים של צד שלישי באמצעות סכימת כתובות האתר הבאה:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

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

הרשאות OkGoogle

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