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

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