درخواست اجازه سخت‌افزار برای عینک‌های صوتی و عینک‌های نمایشگر

دستگاه‌های 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>

پیش‌از درخواست اجازه عینک

اصول و گردش‌های کار اجازه را مرور کنید تا مطمئن شوید بهترین تجربه را برای کاربران خود فراهم می‌کنید، مثلاً بررسی کنید که آیا کاربر قبلاً اجازه‌های زمان اجرا را که برنامه شما نیاز دارد اعطا کرده است یا نه و آیا برنامه شما باید قبل‌از درخواست اجازه‌های ویژه عینک، دلیل آن را به کاربر نشان دهد یا نه.

سناریوهای اجازه

هنگام درخواست اجازه‌های زمان اجرای خطرناک در عینک‌های صوتی و نمایشگر، ممکن است با سناریوهای مختلفی مواجه شوید:

• درخواست اجازه‌های زمان اجرا از فعالیت پیش‌بینی‌شده
• درخواست اجازه‌های زمان اجرا از فعالیت تلفن

برای جزئیات مربوط به هر سناریو، بخش‌های زیر را در این راهنما ببینید.

درخواست و مدیریت اجازه‌های زمان اجرا از فعالیت پیش‌بینی‌شده

برای درخواست اجازه برای عینک‌های صوتی و عینک‌های نمایشگر، ابتدا از روش ActivityResultLauncher با ProjectedPermissionsResultContract برای ثبت اجازه راه‌انداز استفاده کنید. وقتی کاربر به درخواست اجازه عمل کرد، بازخوانی نقشه‌ای از نام‌های اجازه به وضعیت اعطاشده آن‌ها دریافت می‌کند.

// 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 در راه‌انداز باعث راه‌اندازی جریان درخواست اجازه کاربر می‌شود.

آشنایی با جریان کاربر درخواست اجازه

وقتی درخواست اجازه را بااستفاده از روش ProjectedPermissionsResultContract راه‌اندازی می‌کنید، سیستم جریان کاربر هماهنگی را در عینک و تلفن شروع می‌کند.

درطول جریان کاربری اجازه‌ها، برنامه شما و کاربر می‌توانند انتظار داشته باشند که:

1. در عینک: فعالیتی در دستگاه پخش (عینک) ظاهر می‌شود و به کاربر دستور می‌دهد برای ادامه دادن به تلفنش نگاه کند.

2. در تلفن: هم‌زمان، فعالیتی در دستگاه میزبان (تلفن) راه‌اندازی می‌شود. این صفحه رشته منطقی‌ای را که ارائه کرده‌اید نمایش می‌دهد و به کاربر گزینه ادامه دادن یا لغو کردن را می‌دهد.

3. در تلفن: اگر کاربر دلیل منطقی را بپذیرد، کادر گفتگوی اجازه سیستم Android اصلاح‌شده‌ای در تلفن ظاهر می‌شود که به کاربر می‌گوید اجازه را برای عینک (نه تلفن) اعطا می‌کند و کاربر می‌تواند اجازه را به‌طور رسمی اعطا یا رد کند.

4. دریافت نتیجه: پس‌از اینکه کاربر انتخاب نهایی خود را انجام داد، فعالیت‌ها در تلفن و عینک بسته می‌شود. سپس 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 با پاسخ‌گوی onRequestPermissionsResult استفاده کنید تا مطمئن شوید وضعیت مجوز به‌درستی به بافت خاصی، مثل عینک‌های صوتی یا نمایشگر، به‌جای تلفن میزبان، تخصیص داده شده است.
• برنامه شما باید نتایج اعطاشده و ردشده را به‌خوبی مدیریت کند.