Permissions API ב-Android

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

תהליך ההרשאה מאפשר למשתמש ליצור מבנה ולהקצות לו כתובת רחוב אם עדיין לא הוגדרה לו כתובת, בלי להשתמש ב-Google Home app (GHA).

שילוב של Permissions API

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

קודם צריך לרשום 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 של GRANTED אבל קריאה עוקבת ל-structures() לא מחזירה מבנים, המשתמש ביטל את הגישה לאפליקציה דרך דף ההגדרות של GHA, או שלמשתמש אין את הגישה הנדרשת.

שליחת בקשה להרשאות

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

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

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 לאפליקציה.

ממשק המשתמש להסכמה להרשאות מוצג בלוקאל שהוגדר באמצעות HomeClient.setLocale(), או בלוקאל של האפליקציה או המכשיר כברירת מחדל אם לא הוגדר לוקאל. כדי להציג את מסך ההסכמה בשפה מסוימת, צריך להפעיל את setLocale() במופע של HomeClient לפני שמפעילים את requestPermissions(). מידע נוסף זמין במאמר הגדרת הלוקאל של האפליקציה.

מתן הרשאות

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

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

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

• רק משתמשים שרשומים כמשתמשי בדיקה במסוף 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 API כדי לקרוא את המצב של המכשירים במבנה ולשלוט בהם. אם המשתמש לא נותן לאפליקציה הרשאה לסוג מסוים של מכשיר או למכשיר רגיש, האפליקציה לא תוכל להשתמש בממשקי ה-API של Home כדי לגשת למכשיר, לשלוט בו או להפוך אותו לאוטומטי.

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

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

כדי לעשות זאת, צריך לשלוח שוב קריאה ל-requestPermissions() עם הערך ForcePermissionFlow.FORCE_LAUNCH ב-forcePermissionFlow:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

שינוי ההרשאות באמצעות בחירה אוטומטית של תבנית (structure hinting)

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

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

• ‫structureId – המזהה הספציפי של המבנה שייבחר מראש בתיבת הדו-שיח של ההרשאות. כדי לקבל את המזהה, בודקים את מאפייני המבנה של המבנה שמעדכנים.
• ‫allowedStructureIds – רשימה של מזהי מבנים. אם תספקו את הפרמטר הזה, תיבת הדו-שיח של ההרשאות תסנן את המבנים הזמינים ותציג רק את אלה שברשימה. ברוב המקרים אפשר להשאיר את השדה הזה ריק, אלא אם רוצים לוודא שהמשתמש נשאר ברשימת המבנים שכבר ניתנה לו גישה אליהם.
• ‫allowStructureChange – קובעת אם המשתמש יכול לשנות את המבנה שנבחר מראש. כדאי להגדיר את המדיניות הזו לערך true אם לפחות אחת מהמדיניות allowedStructureIds ו-structureId מוגדרת ברוב המקרים, כדי לתמוך בהתנהגות טבעית של המשתמש.

מעבירים את האובייקט הזה כפרמטר אופציונלי בקריאה ל-requestPermissions(), כאשר forcePermissionFlow מוגדר ל-ForcePermissionFlow.FORCE_LAUNCH:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

למשתמש יוצג מסך ההסכמה שכבר מסונן למבנה שצוין באובייקט ConsentScreenOptions.

המשתמשים יכולים להחליף בין מבנים באמצעות בחירה אוטומטית של תבנית (structure hinting)

אם למשתמש יש כמה מבנים באפליקציה ואתם רוצים לבחור מראש אחד מהם, אבל עדיין לאפשר לו לעבור בין המבנים הזמינים, אתם יכולים להפעיל שינויים במבנה באמצעות הדגל allowStructureChange ולספק רשימה של מבנים ב-allowedStructureIds:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

ביטול ההרשאות

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

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

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

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

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

מחיקה וייצוא של נתוני משתמשים

הפלטפורמה מנהלת באופן אוטומטי את מחיקת הנתונים בקצה העורפי כשמשתמש מוחק את חשבון Google שלו או עוזב מבנה:

• אם המשתמש שנמחק הוא הבעלים היחיד של מבנה, הפלטפורמה מוחקת את המבנה ואת המכשירים שמשויכים אליו.
• אם יש בעלים אחרים במבנה המשותף, המבנה והמכשירים המשותפים שלו יישארו אצל שאר החברים. הפלטפורמה מסירה את החברות של המשתמש שעזב ומבטלת את הקישור של כל מכשירי Cloud-to-cloud של צד שלישי שמחוברים רק באמצעות פרטי הכניסה של המשתמש הזה.
• מחיקת החשבון מסירה באופן מיידי וסופי את נתוני המבנה והרשאות האפליקציה של המשתמש. גם אם המשתמש ישחזר את חשבון Google שלו, המבנים וההרשאות שלו לא ישוחזרו.

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

איך רואים את סוגי המכשירים שהמשתמש נתן להם הרשאות

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

כדי לבדוק אם משתמש נתן הרשאת גישה לסוג מכשיר רגיש או מוגבל, משתמשים בפונקציה consentedDeviceTypes() ברמת המבנה:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

הרשאות ל-OkGoogle

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

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

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

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

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