Como adicionar permissões de execução ao app em Kotlin

1. Boas-vindas

Introdução

As permissões do app são usadas para conceder acesso a dados e funcionalidades além daqueles fornecidos pelo sandbox do app. Elas podem melhorar a funcionalidade do app permitindo que ele acesse a Internet, a localização do dispositivo, a câmera e muito mais.

Para usar esses recursos, é necessário solicitar permissões do usuário. Esse codelab apresenta as etapas necessárias para adicionar permissões de execução e conferir se elas foram concedidas ou não.

Pré-requisitos

A versão mais recente do Android Studio.

O que você já precisa saber

Kotlin, conforme ensinado no Treinamento do Kotlin (link em inglês).
Conhecimentos básicos de desenvolvimento para Android, conforme ensinado em Como desenvolver apps Android com Kotlin (link em inglês).

O que você aprenderá

Como adicionar permissões ao manifesto do Android.
Como solicitar permissões.
Como processar permissões concedidas ou recusadas.
Como conferir se uma permissão foi concedida.

O que você criará

Você criará um app que solicita uma permissão de câmera. A parte de permissão do app será implementada, mas não a parte da câmera.

2. Criar um projeto do Android Studio

Inicie um novo projeto no Android Studio.
Escolha Empty Activity.

Nomeie o projeto como Codelab de permissões e defina a linguagem como Kotlin.

3. Configurar o código

Adicione as versões mais recentes das seguintes dependências ao arquivo build.gradle do app. Isso permite usar a biblioteca Activity, que vamos abordar mais adiante no codelab.

implementation "androidx.activity:activity-ktx:1.2.2"
implementation "androidx.fragment:fragment-ktx:1.3.2"

Defina a opção de criação viewBinding como verdadeira no bloco do Android para ativar a ViewBinding.

android {
   ...
   buildFeatures {
       viewBinding true
   }
}

Em seguida, pressione o botão de martelo verde para criar. Isso vai gerar uma classe de vinculação chamada ActivityMainBinding, que você vai usar mais tarde para ViewBinding.

Navegue até o arquivo activity_main.xml e substitua o código pelo seguinte.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:app="http://schemas.android.com/apk/res-auto"
   xmlns:tools="http://schemas.android.com/tools"
   android:id="@+id/main_layout"
   android:layout_width="match_parent"
   android:layout_height="match_parent"
   tools:context=".MainActivity">

   <Button
       android:id="@+id/button"
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:text="Request Permissions"
       android:onClick="onClickRequestPermission"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintEnd_toEndOf="parent"
       app:layout_constraintStart_toStartOf="parent"
       app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Adicione as seguintes strings ao arquivo strings.xml.

<string name="app_name">Permissions Codelab</string>
<string name="permission_required">Camera access is required to display the camera preview.</string>
<string name="ok">OK</string>
<string name="permission_granted">Permission is granted. You can use the camera now.</string>

Em MainActivity.kt, acima do método onCreate(), defina variáveis para o layout e a ViewBinding.

private lateinit var layout: View
private lateinit var binding: ActivityMainBinding

Substitua o código no método onCreate() pelo mostrado abaixo. Esse código inicializa a vinculação, cria um val para representar a visualização, depois a define como raiz da vinculação e define o layout como o mainLayout da vinculação.

override fun onCreate(savedInstanceState: Bundle?) {
   super.onCreate(savedInstanceState)
   binding = ActivityMainBinding.inflate(layoutInflater)
   val view = binding.root
   layout = binding.mainLayout
   setContentView(view)
}

Na parte inferior do arquivo, na classe MainActivity, adicione uma função de extensão para mostrar snackbars durante todo o codelab.

fun View.showSnackbar(
   view: View,
   msg: String,
   length: Int,
   actionMessage: CharSequence?,
   action: (View) -> Unit
) {
   val snackbar = Snackbar.make(view, msg, length)
   if (actionMessage != null) {
       snackbar.setAction(actionMessage) {
           action(this)
       }.show()
   } else {
       snackbar.show()
   }
}

4. Adicionar permissão ao manifesto

A primeira coisa que você precisa fazer é declarar que a permissão será usada no Android manifest utilizando a tag <uses-permission>.

Algumas vezes, a permissão solicitada terá outros requisitos. Nesse caso, só será possível usar um app de câmera se o dispositivo tiver uma. Por isso, também é necessário adicionar a tag <uses-feature> ao manifesto.

No arquivo AndroidManifest.xml, adicione a permissão para a câmera acima da tag <application>.

<uses-permission android:name="android.permission.CAMERA" />

5. Criar tela de início de permissões

Em MainActivity.kt, crie uma val chamada requestPermissionLauncher e copie o código a seguir nela. Essas informações serão detalhadas mais abaixo.

private val requestPermissionLauncher =
   registerForActivityResult(
       ActivityResultContracts.RequestPermission()
   ) { isGranted: Boolean ->
       if (isGranted) {
           Log.i("Permission: ", "Granted")
       } else {
           Log.i("Permission: ", "Denied")
       }
   }

Defina requestPermissionLauncher igual a registerForActivityResult e transmita ActivityResultContracts.RequestPermission().

private val requestPermissionLauncher =
   registerForActivityResult(
       ActivityResultContracts.RequestPermission())

Adicione um callback para processar o caso em que a permissão é concedida ou não. Nesse caso, registramos o resultado.

{ isGranted: Boolean ->
       if (isGranted) {
           Log.i("Permission: ", "Granted")
       } else {
           Log.i("Permission: ", "Denied")
       }
}

6. Solicitar permissão

Crie uma função chamada onClickRequestPermission(view: View) e copie o código a seguir nela. O que acontece nessa função será detalhado nos próximos marcadores.

fun onClickRequestPermission(view: View) {
   when {
       ContextCompat.checkSelfPermission(
           this,
           Manifest.permission.CAMERA
       ) == PackageManager.PERMISSION_GRANTED -> {
           layout.showSnackbar(
               view,
               getString(R.string.permission_granted),
               Snackbar.LENGTH_INDEFINITE,
               null
           ) {}
       }

       ActivityCompat.shouldShowRequestPermissionRationale(
           this,
           Manifest.permission.CAMERA
       ) -> {
           layout.showSnackbar(
               view,
               getString(R.string.permission_required),
               Snackbar.LENGTH_INDEFINITE,
               getString(R.string.ok)
           ) {
               requestPermissionLauncher.launch(
                   Manifest.permission.CAMERA
               )
           }
       }

       else -> {
           requestPermissionLauncher.launch(
               Manifest.permission.CAMERA
           )
       }
   }
}

Configure uma instrução when para abranger os três casos: se a permissão já foi concedida, se o app considera que precisa mostrar a justificativa para a solicitação da permissão e se ela ainda não foi solicitada.

when {
   ContextCompat.checkSelfPermission(
       this,
       Manifest.permission.CAMERA
   ) == PackageManager.PERMISSION_GRANTED -> {

   }

   ActivityCompat.shouldShowRequestPermissionRationale(
       this,
       Manifest.permission.CAMERA
   ) -> {

   }

   else -> {

   }
}

Caso a permissão já tenha sido concedida, exiba um snackbar informando isso.

ContextCompat.checkSelfPermission(
   this,
   Manifest.permission.CAMERA
) == PackageManager.PERMISSION_GRANTED -> {
   layout.showSnackbar(
       view,
       getString(R.string.permission_granted),
       Snackbar.LENGTH_INDEFINITE,
       null
   ) {}
}

Se a instrução shouldShowRequestPermissionRationale() retornar verdadeiro, exiba uma IU que descreva com mais detalhes por que o recurso precisa da permissão específica e que também ofereça ao usuário uma forma de aceitar/recusar a permissão da IU.

ActivityCompat.shouldShowRequestPermissionRationale(
   this,
   Manifest.permission.CAMERA
) -> {
   layout.showSnackbar(
       view,
       getString(R.string.permission_required),
       Snackbar.LENGTH_INDEFINITE,
       getString(R.string.ok)
   ) {
       requestPermissionLauncher.launch(
           Manifest.permission.CAMERA
       )
   }
}

Caso contrário, solicite a permissão.

else -> {
   requestPermissionLauncher.launch(
       Manifest.permission.CAMERA
   )
}

7. Resumo

Pronto! Este codelab apresenta uma forma de adicionar permissões de execução e pode ser usado para permissões de localização, rede, mídia e muito mais.

Para ver o código final e saber mais, confira a documentação.