Solicitar permissões de hardware para óculos de áudio e de exibição

Dispositivos XR relevantes

Estas orientações ajudam você a criar experiências para esses tipos de dispositivos XR.

Saiba mais sobre tipos de dispositivos XR →

Saiba mais sobre tipos de dispositivos XR →

Assim como em um smartphone, o acesso a hardware sensível, como a câmera e o microfone em óculos com áudio e óculos com tela virtual, exige o consentimento do usuário. Essas são consideradas permissões específicas para óculos, e o app precisa solicitá-las no momento da execução, mesmo que já tenha as permissões correspondentes no smartphone.

Declarar as permissões no manifesto do app

Antes de solicitar permissões, você precisa declarar elas no manifesto do app usando o elemento <uses-permission>. Essa declaração permanece a mesma, seja para um smartphone ou um recurso específico para óculos, mas ainda é necessário solicitá-la explicitamente para hardware ou funcionalidade específica para óculos.

<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>

Antes de solicitar permissões para óculos

Consulte os princípios e fluxos de trabalho de permissão para garantir que você esteja oferecendo a melhor experiência aos usuários, como verificar se o usuário já concedeu as permissões de execução necessárias para o app e se o app precisa mostrar uma justificativa ao usuário antes de solicitar permissões específicas para óculos.

Cenários de permissões

Há diferentes cenários que você pode encontrar ao solicitar permissões de execução perigosas em óculos de áudio e óculos com tela virtual:

• Solicitar permissões de execução de uma atividade projetada
• Solicitar permissões de execução de uma atividade do smartphone

Consulte as seções a seguir neste guia para mais detalhes sobre cada cenário.

Solicitar e processar permissões de execução de uma atividade projetada

Para solicitar permissões para óculos com áudio e óculos com tela virtual, primeiro use o ActivityResultLauncher com o ProjectedPermissionsResultContract método para registrar o iniciador de permissões. Quando o usuário tiver agido na solicitação de permissão, o callback vai receber um mapa de nomes de permissão para o status concedido.

// 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

Principais pontos sobre o código

• É necessário especificar quais permissões o app exige, como Manifest.permission.CAMERA ou Manifest.permission.RECORD_AUDIO.
• O app precisa processar os resultados concedidos e negados normalmente no callback do iniciador.

Para acionar o fluxo de solicitação de permissão, transmita uma lista de ProjectedPermissionsRequestParams para o método launch do iniciador de permissão registrado. O objeto ProjectedPermissionsRequestParams agrupa as permissões de manifesto solicitadas com uma string rationale personalizada. A string rationale precisa explicar de forma clara e concisa por que o app exige acesso aos recursos de hardware dos óculos (como a câmera ou o microfone).

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

Principais pontos sobre o código

• Chamar launch no iniciador aciona o fluxo de usuários de solicitação de permissão.

Entender o fluxo de usuários de solicitação de permissão

Ao iniciar uma solicitação de permissão usando o ProjectedPermissionsResultContract método, o sistema inicia um fluxo de usuários coordenado nos óculos e no smartphone.

Durante o fluxo de usuários de permissões, veja o que o app e o usuário podem esperar:

1. Nos óculos: uma atividade aparece no dispositivo projetado (óculos), instruindo o usuário a olhar para o smartphone para continuar.

2. No smartphone: simultaneamente, uma atividade é iniciada no dispositivo host (smartphone). Essa tela mostra a string de justificativa fornecida e oferece ao usuário a opção de continuar ou cancelar.

3. No smartphone: se o usuário aceitar a justificativa, uma caixa de diálogo de permissão do sistema Android modificada vai aparecer no smartphone informando que ele está concedendo a permissão para os óculos (não para o smartphone), e o usuário pode conceder ou negar formalmente a permissão.

4. Receber o resultado: depois que o usuário faz a escolha final, as atividades no smartphone e nos óculos são dispensadas. O callback ActivityResultLauncher é invocado com um mapa que contém o status concedido para cada permissão solicitada.

Solicitar permissões de execução em uma atividade do smartphone

Se o app estiver em execução em uma atividade do smartphone, mas exigir permissões para áudio ou óculos com tela virtual (por exemplo, para permitir que um usuário troque um stream de vídeo para a câmera dos óculos para um ponto de vista em primeira pessoa), solicite as permissões usando o método Activity#requestPermissions(permissions, requestCode, deviceId) específico do dispositivo.

Para segmentar áudio e óculos com tela virtual, obtenha o ID do dispositivo apropriado chamando getDeviceId em um contexto de dispositivo projetado. Transmita esse ID ao solicitar permissões da atividade do smartphone, conforme mostrado no exemplo a seguir:

// 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

Processar os resultados da permissão

Depois que o usuário responde à caixa de diálogo de permissão no smartphone, a decisão é entregue ao app invocando o callback onRequestPermissionsResult.

Para processar a resposta, substitua onRequestPermissionsResult na instância Activity que iniciou a solicitação de permissão.

O snippet de código a seguir mostra como processar o callback e verificar se o usuário concedeu as permissões solicitadas:

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

Principais pontos sobre o código

• Use a sobrecarga deviceId com o callback onRequestPermissionsResult para garantir que o status da permissão seja mapeado corretamente para o contexto específico, como os óculos de áudio ou óculos com tela virtual, e não o smartphone host.
• O app precisa processar os resultados concedidos e negados normalmente.