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

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

قبل از درخواست مجوز عینک

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

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

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

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

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

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

برای درخواست مجوز برای عینک‌های صوتی و عینک‌های نمایشی، ابتدا از 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. در تلفن : اگر کاربر منطق را بپذیرد، یک پنجره‌ی مجوز سیستم اندروید اصلاح‌شده روی تلفن ظاهر می‌شود که به کاربر می‌گوید مجوز برای عینک (نه تلفن) صادر شده است و کاربر می‌تواند رسماً مجوز را اعطا یا رد کند.

4. دریافت نتیجه : پس از اینکه کاربر انتخاب نهایی خود را انجام داد، فعالیت‌های روی گوشی و عینک رد می‌شوند. سپس تابع فراخوانی ActivityResultLauncher شما با نقشه‌ای حاوی وضعیت اعطا شده برای هر مجوز درخواستی فراخوانی می‌شود.

درخواست مجوزهای زمان اجرا در یک فعالیت تلفنی

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