Xamarin.Essentials:Permissões
A classe Permissions fornece a capacidade de marcar e solicitar permissões de runtime.
Introdução
Para começar a usar essa API, leia o guia de introdução para Xamarin.Essentials para garantir que a biblioteca esteja instalada e configurada corretamente em seus projetos.
Essa API usa permissões de runtime no Android. Verifique se Xamarin.Essentials está totalmente inicializado e se o tratamento de permissões está configurado em seu aplicativo.
No projeto do MainLauncher
Android ou em qualquer Activity
que seja iniciado Xamarin.Essentials , deve ser inicializado no OnCreate
método :
protected override void OnCreate(Bundle savedInstanceState)
{
//...
base.OnCreate(savedInstanceState);
Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code, it may also be called: bundle
//...
}
Para lidar com permissões de runtime no Android, Xamarin.Essentials deve receber qualquer OnRequestPermissionsResult
. Adicione o seguinte código a todas as classes Activity
:
public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Android.Content.PM.Permission[] grantResults)
{
Xamarin.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
}
Usando permissões
Adicione uma referência a Xamarin.Essentials em sua classe:
using Xamarin.Essentials;
Verificando permissões
Para marcar o status atual de uma permissão, use o CheckStatusAsync
método juntamente com a permissão específica para obter o status.
var status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();
Um PermissionException
será gerado se a permissão necessária não for declarada.
É melhor marcar o status da permissão antes de solicitá-la. Cada sistema operacional retornará um estado padrão diferente se o usuário nunca tiver sido solicitado. O iOS retorna Unknown
, enquanto outros retornam Denied
. Se o status forGranted
, não será necessário fazer outras chamadas. No iOS, se o status forDenied
, você deverá solicitar que o usuário altere a permissão nas configurações e, no Android, poderá chamar ShouldShowRationale
para detectar se o usuário já negou a permissão no passado.
Solicitando permissões
Para solicitar uma permissão dos usuários, use o RequestAsync
método junto com a permissão específica para solicitar. Se o usuário concedeu permissão anteriormente e não a revogou, esse método retornará Granted
imediatamente e não exibirá uma caixa de diálogo.
var status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();
Um PermissionException
será gerado se a permissão necessária não for declarada.
Observe que, em algumas plataformas, uma solicitação de permissão só pode ser ativada uma única vez. Outros prompts devem ser tratados pelo desenvolvedor para marcar se uma permissão estiver no Denied
estado e pedir ao usuário para ativá-la manualmente.
Status da permissão
Ao usar CheckStatusAsync
ou RequestAsync
será retornado um PermissionStatus
que pode ser usado para determinar as próximas etapas:
- Desconhecido – a permissão está em um estado desconhecido
- Negado - O usuário negou a solicitação de permissão
- Desabilitado – o recurso está desabilitado no dispositivo
- Concedido - O usuário concedeu permissão ou é concedido automaticamente
- Restrito – em um estado restrito
Explicar por que a permissão é necessária
É uma prática recomendada explicar por que seu aplicativo precisa de uma permissão específica. No iOS, você deve especificar uma cadeia de caracteres que é exibida para o usuário. O Android não tem essa capacidade e também usa como padrão a permissão status para Desabilitado. Isso limita a capacidade de saber se o usuário negou a permissão ou se é a primeira vez que o usuário solicita. O ShouldShowRationale
método pode ser usado para determinar se uma interface do usuário educacional deve ser exibida. Se o método retornar true
, isso ocorre porque o usuário negou ou desabilitou a permissão no passado. Outras plataformas sempre retornarão false
ao chamar esse método.
Permissões disponíveis
Xamarin.Essentials tenta abstrair o máximo possível de permissões. No entanto, cada sistema operacional tem um conjunto diferente de permissões de runtime. Além disso, há diferenças ao fornecer uma única API para algumas permissões. Aqui está um guia para as permissões disponíveis no momento:
Guia de ícones:
- – com suporte
- - Sem suporte/obrigatório
Permissão | Android | iOS | UWP | watchOS | tvOS | Tizen |
---|---|---|---|---|---|---|
CalendarRead | ||||||
CalendarWrite | ||||||
Câmera | ||||||
ContactsRead | com | |||||
ContactsWrite | com | |||||
Flashlight | ||||||
LocationWhenInUse | para | |||||
LocationAlways | para | |||||
Mídia | para | |||||
Microfone | para | |||||
Telefone | para | |||||
Fotos | para | |||||
Lembretes | para | |||||
Sensores | para | |||||
Sms | para | |||||
Fala | para | |||||
StorageRead | ||||||
StorageWrite |
Se uma permissão for marcada como ela sempre retornará Granted
quando for verificada ou solicitada.
Uso geral
O código a seguir apresenta o padrão de uso geral para determinar se uma permissão foi concedida e solicitá-la se não tiver sido concedida. Esse código usa recursos que estão disponíveis com Xamarin.Essentials a versão 1.6.0 ou posterior.
public async Task<PermissionStatus> CheckAndRequestLocationPermission()
{
var status = await Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>();
if (status == PermissionStatus.Granted)
return status;
if (status == PermissionStatus.Denied && DeviceInfo.Platform == DevicePlatform.iOS)
{
// Prompt the user to turn on in settings
// On iOS once a permission has been denied it may not be requested again from the application
return status;
}
if (Permissions.ShouldShowRationale<Permissions.LocationWhenInUse>())
{
// Prompt the user with additional information as to why the permission is needed
}
status = await Permissions.RequestAsync<Permissions.LocationWhenInUse>();
return status;
}
Cada tipo de permissão pode ter uma instância dele criada para que os métodos possam ser chamados diretamente.
public async Task GetLocationAsync()
{
var status = await CheckAndRequestPermissionAsync(new Permissions.LocationWhenInUse());
if (status != PermissionStatus.Granted)
{
// Notify user permission was denied
return;
}
var location = await Geolocation.GetLocationAsync();
}
public async Task<PermissionStatus> CheckAndRequestPermissionAsync<T>(T permission)
where T : BasePermission
{
var status = await permission.CheckStatusAsync();
if (status != PermissionStatus.Granted)
{
status = await permission.RequestAsync();
}
return status;
}
Estendendo permissões
A API de Permissões foi criada para ser flexível e extensível para aplicativos que exigem validação ou permissões adicionais que não estão incluídas no Xamarin.Essentials. Crie uma nova classe que herda e BasePermission
implemente os métodos abstratos necessários.
public class MyPermission : BasePermission
{
// This method checks if current status of the permission
public override Task<PermissionStatus> CheckStatusAsync()
{
throw new System.NotImplementedException();
}
// This method is optional and a PermissionException is often thrown if a permission is not declared
public override void EnsureDeclared()
{
throw new System.NotImplementedException();
}
// Requests the user to accept or deny a permission
public override Task<PermissionStatus> RequestAsync()
{
throw new System.NotImplementedException();
}
}
Ao implementar uma permissão em uma plataforma específica, a BasePlatformPermission
classe pode ser herdada. Isso fornece métodos auxiliares de plataforma adicionais para marcar automaticamente as declarações. Isso pode ajudar ao criar permissões personalizadas que fazem agrupamentos. Por exemplo, você pode solicitar acesso de Leitura e Gravação ao armazenamento no Android usando a permissão personalizada a seguir.
public class ReadWriteStoragePermission : Xamarin.Essentials.Permissions.BasePlatformPermission
{
public override (string androidPermission, bool isRuntime)[] RequiredPermissions => new List<(string androidPermission, bool isRuntime)>
{
(Android.Manifest.Permission.ReadExternalStorage, true),
(Android.Manifest.Permission.WriteExternalStorage, true)
}.ToArray();
}
Em seguida, você pode chamar sua nova permissão do projeto android.
await Permissions.RequestAsync<ReadWriteStoragePermission>();
Se você quisesse chamar essa API do código compartilhado, poderia criar uma interface e usar um serviço de dependência para registrar e obter a implementação.
public interface IReadWritePermission
{
Task<PermissionStatus> CheckStatusAsync();
Task<PermissionStatus> RequestAsync();
}
Em seguida, implemente a interface em seu projeto de plataforma:
public class ReadWriteStoragePermission : Xamarin.Essentials.Permissions.BasePlatformPermission, IReadWritePermission
{
public override (string androidPermission, bool isRuntime)[] RequiredPermissions => new List<(string androidPermission, bool isRuntime)>
{
(Android.Manifest.Permission.ReadExternalStorage, true),
(Android.Manifest.Permission.WriteExternalStorage, true)
}.ToArray();
}
Em seguida, você pode registrar a implementação específica:
DependencyService.Register<IReadWritePermission, ReadWriteStoragePermission>();
Em seguida, no projeto compartilhado, você pode resolve e usá-lo:
var readWritePermission = DependencyService.Get<IReadWritePermission>();
var status = await readWritePermission.CheckStatusAsync();
if (status != PermissionStatus.Granted)
{
status = await readWritePermission.RequestAsync();
}
Particularidades de implementação da plataforma
As permissões devem ter os atributos correspondentes definidos no arquivo de manifesto do Android. O padrão de permissão status Negado.
Leia mais sobre a documentação Permissões no Xamarin.Android .
API
Vídeo relacionados
Encontre mais vídeos sobre o Xamarin no Channel 9 e no YouTube.