O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Solicitar permissões do app

Cada app para Android é executado em um sandbox com acesso limitado. Se um app precisar usar recursos ou informações fora do próprio sandbox, ele precisará solicitar a permissão adequada. Você declara que seu app precisa de uma permissão listando-a no manifesto do app. Depois disso, é necessário solicitar que o usuário aprove cada permissão no momento da execução (no Android 6.0 e versões mais recentes).

Os princípios básicos são os seguintes:

  • Solicite permissões no contexto, quando o usuário começar a interagir com o recurso que requer a permissão.
  • Não bloqueie o usuário. Sempre ofereça a opção de cancelar um fluxo de IU educacional relacionado a permissões.
  • Se o usuário negar ou revogar uma permissão necessária para um recurso, faça uma degradação suave para que ele possa continuar usando o app, possivelmente desativando o recurso que requer a permissão.
  • Não presuma nenhum comportamento do sistema.

Nesta página, você verá o processo passo a passo para adicionar permissões ao app e solicitar essas permissões no tempo de execução conforme necessário.

Adicionar permissões ao manifesto

Em todas as versões do Android, para declarar que seu app precisa de uma permissão, insira um elemento <uses-permission> no manifesto como filho do elemento <manifest> de alto nível.

Por exemplo, um app que precisa acessar a Internet teria a seguinte linha no manifesto:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.example.snazzyapp">

    <uses-permission android:name="android.permission.INTERNET"/>
    <!-- other permissions go here -->

    <application ...>
        ...
    </application>
</manifest>

O comportamento do sistema após a declaração de uma permissão depende da importância dela. Algumas permissões são consideradas "normais", então o sistema as concede na instalação. Outras permissões são consideradas "perigosas", então o usuário precisa conceder acesso ao app de forma explícita. Para mais informações sobre os diferentes tipos de permissão, consulte Níveis de proteção.

Verificar permissões

Caso seu app precise de uma permissão perigosa, é necessário verificar se ele tem essa permissão todas as vezes que realizar uma ação que precise dela. No Android 6.0 (API de nível 23) e versões mais recentes, os usuários podem revogar permissões perigosas de qualquer app a qualquer momento.

Determinar se o app já recebeu a permissão

Para verificar se o usuário já concedeu uma permissão específica ao app, transmita essa permissão para o método ContextCompat.checkSelfPermission(). Esse método retorna PERMISSION_GRANTED ou PERMISSION_DENIED, dependendo se o app tem ou não a permissão.

Explicar porque seu app precisa da permissão

Se o método ContextCompat.checkSelfPermission() retornar PERMISSION_DENIED, chame shouldShowRequestPermissionRationale(). Se esse método retornar true, mostre uma IU educacional para o usuário. Nessa IU, descreva o motivo pelo qual o recurso que o usuário quer ativar precisa de uma permissão específica.

Solicitar permissões

Depois que o usuário visualizar uma IU educacional ou o valor de retorno shouldShowRequestPermissionRationale() indicar que você não precisa mostrar uma IU educacional dessa vez, solicite a permissão. Os usuários veem uma caixa de diálogo de permissão do sistema, na qual podem escolher se querem conceder uma permissão específica ao app.

Normalmente, você gerencia um código de solicitação como parte da solicitação de permissão e inclui esse código na lógica de callback de permissão. Outra opção é usar o contrato RequestPermission, incluído em uma biblioteca AndroidX, em que você permite que o sistema gerencie o código de solicitação de permissão para você. Como o uso do contrato RequestPermission simplifica sua lógica, é recomendável usá-lo quando possível.

Permitir que o sistema gerencie o código de solicitação de permissão

Para permitir que o sistema gerencie o código de solicitação associado a uma solicitação de permissões, adicione uma dependência na biblioteca androidx.activity no arquivo build.gradle do módulo. Use a versão 1.2.0 ou mais recente da biblioteca.

Em seguida, você pode usar uma das seguintes classes:

As etapas a seguir mostram como usar o contrato RequestPermission. O processo é quase o mesmo para o contrato RequestMultiplePermissions.

  1. Na lógica de inicialização da atividade ou do fragmento, transmita uma implementação de ActivityResultCallback para uma chamada para registerForActivityResult(). O ActivityResultCallback define como o app processa a resposta do usuário à solicitação de permissão.

    Mantenha uma referência ao valor de retorno de registerForActivityResult(), que é do tipo ActivityResultLauncher.

  2. Para exibir a caixa de diálogo de permissões do sistema quando necessário, chame o método launch() na instância de ActivityResultLauncher que você salvou na etapa anterior.

    Depois que launch() for chamado, a caixa de diálogo de permissões do sistema será exibida. Quando o usuário faz uma escolha, o sistema invoca de maneira assíncrona a implementação de ActivityResultCallback, que você definiu na etapa anterior.

    Observação: seu app não pode personalizar a caixa de diálogo exibida quando você chama launch(). Para oferecer mais informações ou contexto ao usuário, mude a IU do seu app para que seja mais fácil entender o motivo pelo qual um recurso do app precisa de uma permissão específica. Por exemplo, você pode mudar o texto no botão que ativa o recurso.

    Além disso, o texto na caixa de diálogo de permissão do sistema faz referência ao grupo de permissões associado à permissão solicitada. Esse grupo de permissões foi projetado para facilitar o uso do sistema, e seu app não pode depender de permissões estarem dentro ou fora de um grupo de permissões específico.

O snippet de código a seguir mostra como lidar com a resposta de permissões:

Kotlin

// Register the permissions callback, which handles the user's response to the
// system permissions dialog. Save the return value, an instance of
// ActivityResultLauncher. You can use either a val, as shown in this snippet,
// or a lateinit var in your onAttach() or onCreate() method.
val requestPermissionLauncher =
    registerForActivityResult(RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Permission is granted. Continue the action or workflow in your
            // app.
        } else {
            // Explain to the user that the feature is unavailable because the
            // features requires a permission that the user has denied. At the
            // same time, respect the user's decision. Don't link to system
            // settings in an effort to convince the user to change their
            // decision.
        }
    }

Java

// Register the permissions callback, which handles the user's response to the
// system permissions dialog. Save the return value, an instance of
// ActivityResultLauncher, as an instance variable.
private ActivityResultLauncher<String> requestPermissionLauncher =
    registerForActivityResult(new RequestPermission(), isGranted -> {
        if (isGranted) {
            // Permission is granted. Continue the action or workflow in your
            // app.
        } else {
            // Explain to the user that the feature is unavailable because the
            // features requires a permission that the user has denied. At the
            // same time, respect the user's decision. Don't link to system
            // settings in an effort to convince the user to change their
            // decision.
        }
    });

E este snippet de código demonstra o processo recomendado para verificar se há uma permissão e solicitar uma permissão do usuário quando necessário:

Kotlin

when {
    ContextCompat.checkSelfPermission(
            CONTEXT,
            Manifest.permission.REQUESTED_PERMISSION
            ) == PackageManager.PERMISSION_GRANTED -> {
        // You can use the API that requires the permission.
    }
    shouldShowRequestPermissionRationale(...) -> {
        // In an educational UI, explain to the user why your app requires this
        // permission for a specific feature to behave as expected. In this UI,
        // include a "cancel" or "no thanks" button that allows the user to
        // continue using your app without granting the permission.
        showInContextUI(...)
    }
    else -> {
        // You can directly ask for the permission.
        // The registered ActivityResultCallback gets the result of this request.
        requestPermissionLauncher.launch(
                Manifest.permission.REQUESTED_PERMISSION)
    }
}

Java

if (ContextCompat.checkSelfPermission(
        CONTEXT, Manifest.permission.REQUESTED_PERMISSION) ==
        PackageManager.PERMISSION_GRANTED) {
    // You can use the API that requires the permission.
    performAction(...);
} else if (shouldShowRequestPermissionRationale(...)) {
    // In an educational UI, explain to the user why your app requires this
    // permission for a specific feature to behave as expected. In this UI,
    // include a "cancel" or "no thanks" button that allows the user to
    // continue using your app without granting the permission.
    showInContextUI(...);
} else {
    // You can directly ask for the permission.
    // The registered ActivityResultCallback gets the result of this request.
    requestPermissionLauncher.launch(
            Manifest.permission.REQUESTED_PERMISSION);
}

Gerenciar o código de solicitação de permissão

Como alternativa para permitir que o sistema gerencie o código de solicitação de permissão, você mesmo pode gerenciá-lo. Para isso, inclua o código da solicitação em uma chamada para requestPermissions().

O snippet de código a seguir demonstra como solicitar uma permissão usando um código de solicitação:

Kotlin

when {
    ContextCompat.checkSelfPermission(
            CONTEXT,
            Manifest.permission.REQUESTED_PERMISSION
            ) == PackageManager.PERMISSION_GRANTED -> {
        // You can use the API that requires the permission.
        performAction(...)
    }
    shouldShowRequestPermissionRationale(...) -> {
        // In an educational UI, explain to the user why your app requires this
        // permission for a specific feature to behave as expected. In this UI,
        // include a "cancel" or "no thanks" button that allows the user to
        // continue using your app without granting the permission.
        showInContextUI(...)
    }
    else -> {
        // You can directly ask for the permission.
        requestPermissions(CONTEXT,
                arrayOf(Manifest.permission.REQUESTED_PERMISSION),
                REQUEST_CODE)
    }
}

Java

if (ContextCompat.checkSelfPermission(
        CONTEXT, Manifest.permission.REQUESTED_PERMISSION) ==
        PackageManager.PERMISSION_GRANTED) {
    // You can use the API that requires the permission.
    performAction(...);
} else if (shouldShowRequestPermissionRationale(...)) {
    // In an educational UI, explain to the user why your app requires this
    // permission for a specific feature to behave as expected. In this UI,
    // include a "cancel" or "no thanks" button that allows the user to
    // continue using your app without granting the permission.
    showInContextUI(...);
} else {
    // You can directly ask for the permission.
    requestPermissions(CONTEXT,
            new String[] { Manifest.permission.REQUESTED_PERMISSION },
            REQUEST_CODE);
}

Depois que o usuário responder à caixa de diálogo de permissões do sistema, o sistema invocará a implementação do app de onRequestPermissionsResult(). O sistema passa a resposta do usuário para a caixa de diálogo de permissão, bem como o código de solicitação definido, conforme mostrado no snippet de código seguir:

Kotlin

override fun onRequestPermissionsResult(requestCode: Int,
        permissions: Array<String>, grantResults: IntArray) {
    when (requestCode) {
        PERMISSION_REQUEST_CODE -> {
            // If request is cancelled, the result arrays are empty.
            if ((grantResults.isNotEmpty() &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED)) {
                // Permission is granted. Continue the action or workflow
                // in your app.
            } else {
                // Explain to the user that the feature is unavailable because
                // the features requires a permission that the user has denied.
                // At the same time, respect the user's decision. Don't link to
                // system settings in an effort to convince the user to change
                // their decision.
            }
            return
        }

        // Add other 'when' lines to check for other
        // permissions this app might request.
        else -> {
            // Ignore all other requests.
        }
    }
}

Java

@Override
public void onRequestPermissionsResults(int requestCode, String[] permissions,
        int[] grantResults) {
    switch (requestCode) {
        case PERMISSION_REQUEST_CODE:
            // If request is cancelled, the result arrays are empty.
            if (grantResults.length > 0 &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                // Permission is granted. Continue the action or workflow
                // in your app.
            }  else {
                // Explain to the user that the feature is unavailable because
                // the features requires a permission that the user has denied.
                // At the same time, respect the user's decision. Don't link to
                // system settings in an effort to convince the user to change
                // their decision.
            }
            return;
        }
        // Other 'case' lines to check for other
        // permissions this app might request.
    }
}

Processar negação de permissão

Se o usuário negar uma solicitação de permissão, seu app precisará ajudar a entender as implicações de negar essa permissão. Mais especificamente, seu app precisa informar os usuários sobre os recursos que não funcionam devido à ausência da permissão. Ao fazer isso, lembre-se das seguintes práticas recomendadas:

  • Direcione a atenção do usuário. Destaque uma parte específica da IU do app em que a funcionalidade será limitada porque o app não tem a permissão necessária. Veja alguns exemplos do que você pode fazer:

    • Mostrar uma mensagem em que os resultados ou dados do recurso seriam exibidos.
    • Exibir um botão diferente que contenha um ícone e uma cor de erro.
  • Seja específico. Não exiba uma mensagem genérica. Em vez disso, mencione quais recursos não estão disponíveis porque o app não tem a permissão necessária.

  • Não bloqueie a interface do usuário. Em outras palavras, não exiba uma mensagem de aviso em tela cheia que impeça o usuário de continuar usando o app.

Ao mesmo tempo, o app precisa respeitar a decisão do usuário de negar uma permissão. A partir do Android 11 (API de nível 30), se o usuário tocar mais de uma vez em Negar para uma permissão específica durante a vida útil da instalação do app em um dispositivo, a caixa de diálogo de permissões do sistema não será exibida se o app solicitar a permissão novamente. A ação do usuário implica "não perguntar novamente". Em versões mais antigas, os usuários tinham acesso à caixa de diálogo de permissões do sistema toda vez que o app solicitava uma permissão, a menos que uma caixa de seleção "não perguntar novamente" tivesse sido selecionada.

Em determinadas situações, a permissão pode ser negada automaticamente, sem que o usuário realize nenhuma ação. Da mesma forma, uma permissão também pode ser concedida de forma automática. É importante não presumir nada sobre o comportamento automático. Sempre que seu app precisar acessar uma funcionalidade que exija uma permissão, verifique se ele ainda tem essa permissão.

Para oferecer a melhor experiência do usuário ao pedir permissões do app, consulte também as Práticas recomendadas de permissões do app.

Pedir para se tornar o gerenciador padrão, se necessário

Alguns apps dependem do acesso a informações confidenciais do usuário relacionadas a registros de chamadas e mensagens SMS. Se você quiser solicitar permissões especificamente para registros de chamadas e mensagens SMS e publicar seu app na Play Store, precisará solicitar que o usuário configure seu app como o gerenciador padrão de uma função principal do sistema antes de solicitar permissões no momento da execução.

Para ver mais informações sobre gerenciadores padrão, incluindo orientações sobre como mostrar uma solicitação de gerenciador padrão para o usuário, consulte o guia sobre permissões usadas somente em gerenciadores padrão.

Declarar permissões por nível de API

Para declarar uma permissão apenas em dispositivos compatíveis com permissões no tempo de execução, ou seja, dispositivos com Android 6.0 (API de nível 23) ou versões mais recentes, inclua a tag uses-permission-sdk-23, em vez de uses-permission.

Ao usar uma dessas tags, você poderá definir o atributo maxSdkVersion para especificar que, em dispositivos com uma versão mais nova, uma permissão específica não será necessária.

Outros recursos

Para mais informações sobre permissões, leia estes artigos:

Para saber mais sobre solicitação de permissões, faça o download destes apps de amostra:

  • Amostra do Android RuntimePermissionsBasic Java Kotlin