要求 AI 眼鏡的硬體權限

適用 XR 裝置

這份指南可協助您為這類 XR 裝置打造體驗。

瞭解 XR 裝置類型 →

AI 眼鏡

瞭解 XR 裝置類型 →

與手機相同，存取 AI 眼鏡的相機和麥克風等敏感硬體時，必須取得使用者的明確同意。這些是眼鏡專屬權限，應用程式必須在執行階段要求這些權限，即使應用程式已在手機上取得對應權限，也必須這麼做。

這份指南可協助您：

• 在應用程式資訊清單中宣告權限
• 要求權限
• 瞭解權限使用者流程

在應用程式資訊清單中宣告權限

要求權限之前，您必須先在應用程式的資訊清單檔案中宣告權限，方法是使用 <uses-permission> 元素。無論權限是適用於手機或 AI 眼鏡專屬功能，這項聲明都相同，但您仍須明確要求眼鏡專屬硬體或功能權限。

<manifest ...>
    <!-- Only declare permissions that your app actually needs. In this example,
    we declare permissions for the microphone. -->
    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
    <application ...>
        ...
    </application>
</manifest>

要求權限

如要要求 AI 眼鏡的權限，請使用 ProjectedPermissionsResultContract() 方法搭配 ActivityResultLauncher。您需要指定應用程式所需的權限，例如 Manifest.permission.CAMERA 或 Manifest.permission.RECORD_AUDIO。請提供清楚簡潔的理由，說明應用程式為何需要這些權限。系統會向使用者顯示這項理由，協助他們做出明智的決定。

class SampleGlassesActivity : ComponentActivity() {

  // Register the permissions launcher
    private val requestPermissionLauncher: ActivityResultLauncher<List<ProjectedPermissionsRequestParams>> =
        registerForActivityResult(ProjectedPermissionsResultContract()) { results ->
            // Check the result for the specific RECORD_AUDIO permission
            if (results[Manifest.permission.RECORD_AUDIO] == true) {
                onPermissionGranted()
            } else {
                onPermissionDenied()
            }
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Audio permission is critical for the displayless AI glasses experience
        checkAndRequestAudioPermission()

        setContent {
            GlimmerTheme {
                DisplayGlassesUi()
            }
        }
    }

    // Checks for the required RECORD_AUDIO permission and requests it if necessary.

    private fun checkAndRequestAudioPermission() {
        val permission = Manifest.permission.RECORD_AUDIO
        val permissionStatus = ContextCompat.checkSelfPermission(this, permission)

        if (permissionStatus == PackageManager.PERMISSION_GRANTED) {
            // Permission is already granted
            onPermissionGranted()
        } else {
            // Permission is not granted, request it
            requestAudioPermission()
        }
    }

    private fun requestAudioPermission() {
        val params = ProjectedPermissionsRequestParams(
                        permissions = listOf(Manifest.permission.RECORD_AUDIO),
            // The rationale should explain why this permission is needed.
            // For displayless AI glasses, it's often the main input mechanism.
            rationale = "Microphone access is essential for voice commands and features on these AI glasses."
        )
        requestPermissionLauncher.launch(listOf(params))
    }

    private fun onPermissionGranted() {
        // Implement the logic for when the permission is granted

    }

    private fun onPermissionDenied() {
        // Implement the logic for when the permission is denied.
        // On displayless AI glasses, if the app requires voice/mic it should exit the activity if the critical permission is denied.
        finish()
    }
}

程式碼重點

• 我們使用 ProjectedPermissionsResultContract() 方法建立 ActivityResultLauncher。回呼會收到權限名稱對應授予狀態的地圖。
• requestAudioPermission() 函式會建構 ProjectedPermissionsRequestParams 物件。這個物件會將我們需要的權限清單和使用者可見的理由綁在一起。
• 在啟動器上呼叫 launch() 會觸發權限要求使用者流程。
• 應用程式應在啟動器的回呼中，妥善處理授權和拒絕結果。

瞭解權限要求使用者流程

使用 ProjectedPermissionsResultContract() 方法啟動權限要求時，系統會在 AI 眼鏡和手機上啟動協調式使用者流程。

重要事項： 您應從 AI 眼鏡上顯示的 Activity 呼叫 ProjectedPermissionsResultContract 方法。請勿在眼鏡上執行的程式碼中使用標準 Android 權限 API (例如 requestPermissions() 和 ActivityResultLauncher<String>)。這麼做會嘗試在眼鏡上啟動無法互動的權限對話方塊，導致使用者流程中斷。

如果應用程式已在手機上顯示 Activity，請使用 Activity#requestPermissions(permissions, requestCode, deviceId)，其中 deviceId 是透過在 ProjectedContext.createProjectedDeviceContext() 傳回的 Context 上呼叫 getDeviceId() 方法取得。

在權限使用者流程中，應用程式和使用者可能會遇到下列情況：

1. 在 AI 眼鏡上：投影裝置 (眼鏡) 會顯示活動，指示使用者查看手機以繼續操作。

   預覽版： 目前使用者無法聽到系統提供的指示和理由。如要向使用者提供語音說明，建議使用文字轉語音 (TTS)。例如：

   tts?.speak("Please review the permission request on your host device",
   TextToSpeech.QUEUE_ADD,
   null,
   "permission_request")
   

2. 在手機上：活動會同時在主機裝置 (手機) 上啟動。這個畫面會顯示您提供的理由字串，並讓使用者選擇繼續或取消。

3. 在手機上：如果使用者接受理由，手機上會顯示修改後的 Android 系統權限對話方塊，告知使用者授予權限的對象是 AI 眼鏡裝置 (而非手機)，使用者可以正式授予或拒絕權限。

4. 接收結果：使用者做出最終選擇後，手機和 AI 眼鏡上的活動都會關閉。接著，系統會叫用 ActivityResultLauncher 回呼，並傳送對應，其中包含每個要求權限的授予狀態。