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)
  }

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

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

val permissionsReadyState =
homeManager.hasPermissions().collect { state ->
    when (state) {
      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")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

אם הבדיקה מחזירה PermissionsState של NOT_GRANTED או PERMISSIONS_STATE_UNAVAILABLE, זה אומר שלמשתמש או לאפליקציה אין גישה למבנה. אם הבדיקה מחזירה PermissionsState of 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 שהונפק כשהמשתמש העניק את ההסכמה הראשונית, ותבטל את הגישה לכל מופע של האפליקציה שבה המשתמש השתמש בכל הפלטפורמות (טלפונים) והמבנים.

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

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

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

הרשאות OkGoogle

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

הנחיות אם משתמש מבטל הרשאות מלאות

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

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