בקשת הרשאות חומרה למשקפי אודיו ולמשקפי תצוגה

מכשירי XR רלוונטיים

ההנחיות האלה יעזרו לכם ליצור חוויות למכשירי XR מהסוגים הבאים.

מידע ולמידה על סוגי מכשירי XR ←

מידע ולמידה על סוגי מכשירי XR ←

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

הצהרה על ההרשאות במניפסט של האפליקציה

לפני שאתם מבקשים הרשאות, אתם צריכים להצהיר עליהן בקובץ המניפסט של האפליקציה באמצעות הרכיב <uses-permission>. ההצהרה הזו נשארת זהה בין אם ההרשאה היא לטלפון או לתכונה ספציפית למשקפיים, אבל עדיין צריך לבקש אותה באופן מפורש בשביל חומרה או פונקציונליות ספציפיות למשקפיים.

<manifest ...>
    <!-- Only declare permissions that your app actually needs. In this example,
    we declare permissions for the camera. -->
    <uses-permission android:name="android.permission.CAMERA"/>
    <application ...>
        ...
    </application>
</manifest>

לפני שמבקשים הרשאות למשקפיים

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

תרחישים של הרשאות

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

• בקשת הרשאות בתחילת ההפעלה מ-Activity מוקרן
• בקשת הרשאות בתחילת ההפעלה מ-Activity בטלפון

בקטעים הבאים במדריך הזה מפורטים פרטים על כל תרחיש.

בקשת הרשאות בתחילת ההפעלה מ-Activity מוקרן

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

הפעלת השיטה הזו מפעילה מסלול המשתמש מתואם גם במשקפיים וגם בטלפון המארח.

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

בדוגמה הבאה אפשר לראות איך לבקש הרשאות למשקפיים מ-Activity מוקרן:

@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
private fun requestCameraPermission() {
    lifecycleScope.launch {
        try {
            ProjectedActivityCompat.requestPermissions(
                this@PermissionsFromProjectedActivity,
                arrayOf(Manifest.permission.CAMERA),
                // CAMERA_PERMISSION_REQUEST_CODE is a developer defined constant
                CAMERA_PERMISSION_REQUEST_CODE,
            )
        } catch (e: IllegalStateException) {
            // Thrown when the projected system service can't be bound.
            Log.e(TAG, "Camera permission request failed: projected service unavailable.", e)
        }
    }
}
PermissionsFromProjectedActivity.kt

מידע חשוב על הקוד

• משתמשים ב-ProjectedActivityCompat.requestPermissions במקום ב-ActivityCompat הרגיל. השיטה הזו מטרגטת באופן מפורש את ההרשאות בתחילת ההפעלה של האודיו והמשקפיים עם התצוגה הפנימית, ולא את הטלפון המארח.

טיפול בתוצאות של בקשת ההרשאה

אחרי שהמשתמש מגיב לתיבת הדו-שיח של ההרשאה בטלפון, ההחלטה שלו מועברת לאפליקציה על ידי הפעלת הקריאה החוזרת (callback) של onRequestPermissionsResult.

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

כדי לטפל בתגובה, צריך לשנות את onRequestPermissionsResult() בתוך המופע של Activity שהפעיל את בקשת ההרשאה.

בקטע הקוד הבא אפשר לראות איך לטפל בקריאה החוזרת (callback) ולוודא שהמשתמש העניק את ההרשאות המבוקשות:

@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<String>,
    grantResults: IntArray,
    deviceId: Int,
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults, deviceId)
    if (requestCode != CAMERA_PERMISSION_REQUEST_CODE) return

    val isCameraGranted =
        grantResults.getOrNull(permissions.indexOf(Manifest.permission.CAMERA)) ==
            PackageManager.PERMISSION_GRANTED

    if (isCameraGranted) {
        initializeCameraFeatures()
    } else {
        onCameraPermissionDenied()
    }
}
PermissionsFromProjectedActivity.kt

מידע חשוב על הקוד

• כדי לוודא שסטטוס ההרשאה ממופה בצורה נכונה להקשר הספציפי, כמו האודיו או המשקפיים עם התצוגה הפנימית במקום הטלפון המארח, צריך להשתמש בעומס היתר של deviceId עם פונקציית ה-callback‏ onRequestPermissionsResult.
• האפליקציה צריכה לטפל בצורה חלקה גם בתוצאות של אישור וגם בתוצאות של דחייה.

בקשת הרשאות בתחילת ההפעלה בפעילות בטלפון

אם האפליקציה פועלת ב-Activity בטלפון אבל נדרשות הרשאות לאודיו או למשקפיים עם תצוגה פנימית – לדוגמה, כדי לאפשר למשתמש להעביר שידור וידאו למצלמה של המשקפיים לתצוגה מגוף ראשון – צריך לבקש את ההרשאות באמצעות השיטה Activity#requestPermissions(permissions, requestCode, deviceId) הספציפית למכשיר:

// Request the projected permission from phone activity
requestPermissions(
    arrayOf(Manifest.permission.CAMERA),
    // REQUEST_CODE_GLASSES_CAMERA is a developer-defined constant
    REQUEST_CODE_GLASSES_CAMERA,
    projectedDeviceId
)
PermissionsFromPhoneActivity.kt

מידע חשוב על הקוד

• כדי לטרגט אודיו ומשקפיים עם תצוגה פנימית, צריך לקבל את מזהה המכשיר המתאים מהקשר מוקרן שיצרתם באמצעות createProjectedDeviceContext. מעבירים את המזהה הזה בקריאה ל-method‏ requestPermissions.

טיפול בתוצאות של בקשת ההרשאה

אחרי שהמשתמש מגיב לתיבת הדו-שיח של ההרשאה בטלפון, ההחלטה שלו מועברת לאפליקציה על ידי הפעלת הקריאה החוזרת (callback) של onRequestPermissionsResult.

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

בקטע הקוד הבא אפשר לראות איך לטפל בקריאה החוזרת (callback) ולוודא שהמשתמש העניק את ההרשאות המבוקשות:

@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<String>,
    grantResults: IntArray,
    deviceId: Int,
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults, deviceId)
    if (requestCode != CAMERA_PERMISSION_REQUEST_CODE) return

    val isCameraGranted =
        grantResults.getOrNull(permissions.indexOf(Manifest.permission.CAMERA)) ==
            PackageManager.PERMISSION_GRANTED

    if (isCameraGranted) {
        initializeCameraFeatures()
    } else {
        onCameraPermissionDenied()
    }
}
PermissionsFromProjectedActivity.kt

מידע חשוב על הקוד

• כדי לוודא שסטטוס ההרשאה ממופה בצורה נכונה להקשר הספציפי, כמו האודיו או המשקפיים עם התצוגה הפנימית ולא הטלפון המארח, צריך להשתמש בעומס היתר של deviceId עם פונקציית ה-callback‏ onRequestPermissionsResult.
• האפליקציה צריכה לטפל בצורה חלקה גם בתוצאות של אישור וגם בתוצאות של דחייה.