Permissão de execução para notificações

O Android 13 (nível 33 da API) e versões mais recentes oferecem suporte a uma permissão de execução para enviar notificações não isentas, incluindo serviços em primeiro plano (FGS), em um app: POST_NOTIFICATIONS. Essa mudança ajuda os usuários a se concentrarem nas notificações mais importantes para eles.

Recomendamos que você destine o app ao Android 13 ou mais recente o quanto antes para fazer uso do maior controle e da maior flexibilidade proporcionados por esse recurso. Se o app continuar a ser destinado ao 12L (nível 32 da API) ou versões anteriores, você não vai poder solicitar permissões no contexto de uso das funcionalidades do app.

Declarar a permissão

Para solicitar a nova permissão de notificações no app, é necessário atualizá-lo para que ele seja destinado ao Android 13 e seguir um processo semelhante ao de solicitação de outras permissões de execução, conforme apresentado nas seções abaixo.

A permissão que você precisa declarar no arquivo de manifesto do app aparece no snippet de código a seguir:

<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application ...>
        ...
    </application>
</manifest>

O uso dos recursos do app depende da escolha do usuário na caixa de diálogo de permissões

Nessa caixa de diálogo, os usuários têm estas ações disponíveis:

Selecionar permitir
Selecionar não permitir
Deslizar para sair da caixa de diálogo sem pressionar nenhum dos botões

As seções abaixo descrevem como o app se comporta de acordo com a ação realizada pelo usuário.

O usuário seleciona "Permitir"

Se o usuário selecionar a opção permitir, o app vai poder fazer o seguinte:

Enviar notificações. Todos os canais de notificação são permitidos.
Enviar notificações relacionadas a serviços em primeiro plano. Essas notificações aparecem na gaveta de notificações.

O usuário seleciona "Não permitir"

Se o usuário selecionar a opção não permitir, o app não vai poder enviar notificações, a menos que esteja qualificado para uma isenção. Todos os canais de notificação ficam bloqueados, exceto alguns papéis específicos. Esse comportamento é semelhante ao que ocorre quando o usuário desativa manualmente todas as notificações do app nas configurações do sistema.

Atenção: caso o app seja destinado ao Android 12L ou versões anteriores e o usuário toque em Não permitir, mesmo que apenas uma vez, a solicitação não vai ser exibida novamente até que uma das seguintes situações ocorra:

O usuário desinstale e reinstale o app.
Você atualize o app para o Android 13 ou versões mais recentes.

O usuário desliza para sair da caixa de diálogo

Se o usuário deslizar para sair da caixa de diálogo, ou seja, não selecionar permitir ou não permitir , o estado da permissão de notificação não vai mudar.

Efeitos em apps recém-instalados

Se um usuário instalar o app em um dispositivo com o Android 13 ou versões mais recentes, as notificações do app vão ser desativadas por padrão. O app precisa aguardar para enviar notificações somente após você solicitar a nova permissão e receber a autorização do usuário.

O momento em que a caixa de diálogo de permissões é exibida depende da versão do SDK de destino do app:

Se o app for destinado ao Android 13 ou a versões mais recentes, ele vai ter controle total sobre o momento em que a caixa de diálogo de permissão é exibida. Use essa oportunidade para explicar aos usuários por que o app precisa dessa permissão, incentivando-os a concedê-la.
Caso o app seja destinado ao 12L (nível 32 da API) ou versões anteriores, o sistema vai exibir a caixa de diálogo de permissão quando o app for iniciado pela primeira vez após você criar um canal de notificação ou quando o app iniciar uma atividade e criar o primeiro canal de notificação. Isso geralmente acontece na inicialização do app. Em apps de atividade única, como a maioria dos apps do Compose, o sistema mostra a caixa de diálogo quando a MainActivity é iniciada.

Efeitos nas atualizações de apps existentes

Para minimizar as interrupções associadas à permissão de notificações, o sistema concede automaticamente essa permissão a todos os apps qualificados quando o usuário atualiza para o Android 13 ou mais recente. Em outras palavras, os apps podem continuar a enviar notificações para os usuários, e a solicitação de permissão de execução não será exibida.

Qualificação para concessão de permissão prévia

Para que o app seja qualificado para receber uma permissão prévia automaticamente, é necessário que ele tenha um canal de notificação existente e que o usuário não desative explicitamente as notificações do app em um dispositivo com o 12L ou versões anteriores.

Caso o usuário tenha desativado as notificações do app em um dispositivo com o 12L ou versões anteriores, essa configuração vai permanecer válida quando o dispositivo for atualizado para o Android 13 ou versões mais recentes.

Isenções

Esta seção apresenta as notificações e os apps em que não ocorre nenhuma mudança de comportamento devido à permissão de notificações. No Android 13 (nível 33 da API) ou versões mais recentes, se o usuário negar a permissão de notificações, ainda vai receber avisos relacionados a serviços em primeiro plano no Gerenciador de tarefas, mas não na gaveta de notificações.

Sessões de mídia

As notificações relacionadas a sessões de mídia estão isentas dessa mudança de comportamento.

Apps configurados para gerenciar chamadas telefônicas

Se o app for configurado para gerenciar chamadas telefônicas, não é necessário ter a POST_NOTIFICATIONS permissão para que ele envie notificações que usem o Notification.CallStyle estilo de notificação.

O sistema considera que o app foi configurado para gerenciar chamadas se ele:

Declara a MANAGE_OWN_CALLS permissão.
Implementa a interface ConnectionService.
Chama registerPhoneAccount() para se cadastrar com a operadora de celular do dispositivo.

Testar o app

É possível avaliar como a permissão de notificações afeta o app quando ele é usado pela primeira vez em um dispositivo com Android 13 ou mais recente. Os conjuntos de comandos do Android Debug Bridge (ADB) a seguir permitem simular as sequências mais comuns de escolhas de usuário e upgrades de dispositivos sem precisar redefinir o dispositivo de teste:

O app foi instalado recentemente em um dispositivo com o Android 13 ou mais recente:

adb shell pm revoke PACKAGE_NAME android.permission.POST_NOTIFICATIONS
adb shell pm clear-permission-flags PACKAGE_NAME \
  android.permission.POST_NOTIFICATIONS user-set
adb shell pm clear-permission-flags PACKAGE_NAME \
  android.permission.POST_NOTIFICATIONS user-fixed

O usuário mantém as notificações ativadas quando o app é instalado em um dispositivo com o 12L ou versões anteriores e, em seguida, o dispositivo é atualizado para o Android 13 ou mais recente:

adb shell pm grant PACKAGE_NAME android.permission.POST_NOTIFICATIONS
adb shell pm set-permission-flags PACKAGE_NAME \
  android.permission.POST_NOTIFICATIONS user-set
adb shell pm clear-permission-flags PACKAGE_NAME \
  android.permission.POST_NOTIFICATIONS user-fixed

O usuário desativa manualmente as notificações quando o app é instalado em um dispositivo com o 12L ou versões anteriores e, em seguida, o dispositivo é atualizado para o Android 13 ou mais recente:

adb shell pm revoke PACKAGE_NAME android.permission.POST_NOTIFICATIONS
adb shell pm set-permission-flags PACKAGE_NAME \
  android.permission.POST_NOTIFICATIONS user-set
adb shell pm clear-permission-flags PACKAGE_NAME \
  android.permission.POST_NOTIFICATIONS user-fixed

Práticas recomendadas

Esta seção descreve várias maneiras de usar a nova permissão de notificação de forma mais eficaz no app.

Atualizar a versão do SDK de destino do app

Para oferecer mais flexibilidade ao app com relação ao momento em que a caixa de diálogo de permissões vai ser exibida, atualize o app para que ele seja destinado ao Android 13 ou mais recente.

Esperar para exibir a solicitação de permissão de notificação

Antes de solicitar permissões aos usuários, permita que eles conheçam melhor o app.

Novos usuários podem querer experimentar o app e entender por conta própria os benefícios de cada solicitação de notificação. É possível acionar uma solicitação de permissões com base em uma ação do usuário. A lista abaixo mostra vários exemplos de bons momentos para exibir a solicitação de permissão de notificação:

O usuário toca no ícone de "sino de notificações" de alerta.
O usuário decide seguir uma nova conta em uma mídia social.
O usuário faz um pedido de entrega de comida.

A Figura 1 apresenta um fluxo de trabalho recomendado para solicitar a permissão de notificação. A menos que shouldShowRequestPermissionRationale() retorne true, o app não precisa exibir a tela do meio, com o texto "Receber notificação". No Compose, é possível encontrar a Activity por acessando LocalContext.current e convertendo-a em uma Activity.

Como alternativa, é possível definir uma solicitação que será exibida depois de um tempo de uso, para que o usuário possa conhecer o app melhor. Por exemplo, você pode aguardar até a terceira ou quarta vez que o usuário iniciar o app.

Depois de fazer login, o usuário vai ver um
convite para receber atualizações sobre viagens. Depois que o usuário pressionar
o botão "Aceitar", o app solicita a nova permissão, o que faz com que a caixa de diálogo
do sistema seja exibida — **Figura 1.** Fluxo de trabalho recomendado para solicitar a permissão de notificação, orientado pelas ações do usuário Só será necessário usar a tela do meio se `shouldShowRequestPermissionRationale()` retornar `true`.

Solicitar a permissão no Compose

Para solicitar a permissão na interface do Compose, use a rememberLauncherForActivityResult() API com o ActivityResultContracts.RequestPermission() contrato.

O snippet a seguir mostra como solicitar a permissão de notificação em resposta a uma interação do usuário:

Kotlin

val context = LocalContext.current
val permissionLauncher = rememberLauncherForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted ->
    if (isGranted) {
        // Permission granted, you can now send notifications.
    } else {
        // Permission denied, handle accordingly.
    }
}

// ... in your UI ...
Button(onClick = {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        permissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
    }
}) {
    Text("Enable Notifications")
}

Solicitar a permissão no contexto

Solicite permissões de notificação no contexto correto de modo que fique explicitamente claro para qual função as notificações vão ser usadas e por que o usuário precisaria as ativar. Por exemplo, um app de e-mails pode incluir opções para enviar notificações a cada novo e-mail ou apenas de e-mails em que o usuário é o único destinatário.

Use essa oportunidade para apresentar suas intenções de forma transparente. Assim, os usuários vão estar mais propensos a conceder a permissão de notificação ao app.

Conferir se o app pode enviar notificações

Antes de enviar uma notificação, confirme se o usuário ativou as notificações do app. Para fazer isso, chame areNotificationsEnabled().

Usar a permissão de forma responsável

Depois de receber a permissão para enviar notificações, use-a de forma responsável. Os usuários vão ver o número de notificações diárias enviadas pelo app e vão poder revogar a permissão a qualquer momento.