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

מכשירי 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 מוקרן

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

// Register the permissions launcher using the ProjectedPermissionsResultContract.
private val requestPermissionLauncher: ActivityResultLauncher<List<ProjectedPermissionsRequestParams>> =
    registerForActivityResult(ProjectedPermissionsResultContract()) { results ->
        if (results[Manifest.permission.CAMERA] == true) {
            isPermissionDenied = false
            initializeGlassesFeatures()
        } else {
            // Handle permission denial.
            isPermissionDenied = true
        }
    }
ProjectedMainActivity.kt

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

• צריך לציין אילו הרשאות נדרשות לאפליקציה, כמו Manifest.permission.CAMERA או Manifest.permission.RECORD_AUDIO.
• האפליקציה צריכה לטפל בצורה חלקה בתוצאות של אישור ודחייה בקריאה החוזרת של מרכז ההפעלה.

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

private fun requestHardwarePermissions() {
    val params = ProjectedPermissionsRequestParams(
        permissions = listOf(Manifest.permission.CAMERA),
        rationale = "Camera access is required to overlay digital content on your physical environment."
    )
    requestPermissionLauncher.launch(listOf(params))
}
ProjectedMainActivity.kt

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

• התקשרות אל launch ב-Launcher מפעילה את תהליך בקשת ההרשאה מהמשתמש.

הסבר על תהליך בקשת ההרשאה

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

במהלך תהליך ההרשאות, אלה הפעולות שצפויות באפליקציה ומהמשתמש:

1. במשקפיים: פעילות מופיעה במכשיר החזוי (המשקפיים), עם הוראה למשתמש להסתכל בטלפון כדי להמשיך.

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

3. בטלפון: אם המשתמש מאשר את ההסבר, בטלפון מופיעה תיבת דו-שיח שונה של הרשאת מערכת Android, שבה נאמר למשתמש שהוא מעניק את ההרשאה למשקפיים (לא לטלפון), והמשתמש יכול לאשר או לדחות את ההרשאה באופן רשמי.

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

בקשת הרשאות בזמן ריצה בפעילות בטלפון

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

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

// 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

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

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

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

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

private companion object {
    // REQUEST_CODE_GLASSES_CAMERA is a developer-defined constant.
    const val REQUEST_CODE_GLASSES_CAMERA = 1001
}

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

    // Handle the result of the permission request
    if (requestCode == REQUEST_CODE_GLASSES_CAMERA && deviceId == projectedDeviceId) {
        if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            // Proceed with glasses camera features
        } else {
            // Handle glasses permission denied
        }
    }
}
PermissionsFromPhoneActivity.kt

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

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