طلب أذونات الأجهزة لنظارات الصوت والنظارات الذكية

أجهزة 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>

قبل طلب أذونات النظارات

راجِع مبادئ الأذونات وسير العمل للتأكّد من تقديم أفضل تجربة للمستخدمين، مثل التحقّق مما إذا كان المستخدم قد منح أذونات التشغيل التي يتطلّبها تطبيقك وما إذا كان تطبيقك بحاجة إلى عرض سبب للمستخدم قبل طلب أذونات خاصة بالنظارات.

سيناريوهات الأذونات

هناك سيناريوهات مختلفة قد تواجهها عند طلب أذونات التشغيل الخطيرة على نظارات الصوت ونظارات بشاشة عرض:

• طلب أذونات التشغيل من نشاط مُسقَط
• طلب أذونات التشغيل من نشاط على الهاتف

راجِع الأقسام التالية في هذا الدليل للحصول على تفاصيل حول كل سيناريو.

طلب أذونات التشغيل من نشاط مُسقَط

لطلب أذونات التشغيل الخاصة بالنظارات الصوتية أو نظارات العرض من نشاط مُسقَط، استخدِم طريقة ProjectedActivityCompat.requestPermissions.

يؤدي استدعاء هذه الطريقة إلى بدء مسار مستخدم منسَّق على كل من النظارات والهاتف المضيف.

1. على النظارات: يفتح النظام نشاطًا مصاحبًا معروضًا على النظارات، ويطلب من المستخدم التحقّق من هاتفه للردّ على طلب الحصول على الإذن.
2. على الهاتف: يظهر مربّع حوار أذونات نظام Android على شاشة الهاتف. يشير مربّع الحوار بوضوح إلى أنّ المستخدم يمنح الإذن للنظارات بدلاً من الهاتف نفسه. ويمكن للمستخدم عندئذٍ الموافقة على الطلب أو رفضه.

يوضّح المثال التالي كيفية طلب أذونات النظارات من نشاط مُسقَط:

@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 العادية. تستهدف هذه الطريقة بشكل صريح أذونات وقت التشغيل الخاصة بالنظارات الصوتية ونظارات العرض بدلاً من الهاتف المضيف.

التعامل مع نتائج الأذونات

بعد أن يردّ المستخدم على مربّع حوار الأذونات على الهاتف، يتم إرسال قراره إلى تطبيقك من خلال استدعاء onRequestPermissionsResult.

يغلق النظام تلقائيًا النشاط المصاحب المعروض. على نظارات الصوت، يحدث ذلك بعد انتهاء تشغيل التنبيه الصوتي. على النظارات التي تعرض المعلومات، يحدث ذلك بعد أن يردّ المستخدم على جميع مربّعات حوار الأذونات.

للتعامل مع الردّ، عليك تجاوز onRequestPermissionsResult() ضمن مثيل Activity الذي بدأ طلب الحصول على إذن.

يوضّح مقتطف الرمز البرمجي التالي كيفية التعامل مع دالة الرجوع والتحقّق مما إذا كان المستخدم قد منح الأذونات المطلوبة:

@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 مع onRequestPermissionsResult لضمان ربط حالة الإذن بالسياق المحدّد بشكل صحيح، مثل النظارات الصوتية أو نظارات العرض بدلاً من الهاتف المضيف.
• يجب أن يتعامل تطبيقك مع نتائج منح الإذن ورفضه بشكل سليم.

طلب أذونات التشغيل في نشاط على الهاتف

إذا كان تطبيقك قيد التشغيل في نشاط على الهاتف ولكنه يتطلب أذونات للصوت أو النظارات بشاشة عرض، على سبيل المثال، للسماح للمستخدم بتبديل فيديو مضمّن إلى كاميرا النظارات للحصول على منظور الشخص الأول، اطلب الأذونات باستخدام الطريقة 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. مرِّر هذا المعرّف مع طلبك إلى الطريقة requestPermissions.

التعامل مع نتائج الأذونات

بعد أن يردّ المستخدم على مربّع حوار الأذونات على الهاتف، يتم إرسال قراره إلى تطبيقك من خلال استدعاء onRequestPermissionsResult.

للتعامل مع الاستجابة، يمكنك إلغاء onRequestPermissionsResult ضمن مثيل Activity الذي بدأ طلب الحصول على الإذن.

يوضّح مقتطف الرمز التالي كيفية التعامل مع دالة الاستدعاء والتحقّق مما إذا كان المستخدم قد منح الأذونات المطلوبة:

@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 مع وظيفة معاودة الاتصال onRequestPermissionsResult لضمان ربط حالة الإذن بالسياق المحدّد بشكل صحيح، مثل النظارات الصوتية أو نظارات العرض بدلاً من الهاتف المضيف.
• يجب أن يتعامل تطبيقك مع النتائج الممنوحة والمرفوضة بسلاسة.