Referência da API Android Haptics

Esta seção apresenta uma introdução às várias APIs de retorno tátil disponíveis no Android. Ele também aborda quando e como verificar se há suporte para o dispositivo necessário para garantir que os efeitos táteis sejam executados da forma pretendida.

Existem várias maneiras de criar efeitos táteis. É importante considerar os princípios de design tátil do Android ao escolher entre eles. A tabela a seguir resume esses atributos de alto nível de cada abordagem:

  • A disponibilidade é particularmente importante ao planejar o substituto de comportamento e precisa ser combinada com a verificação do suporte a dispositivos individuais.
  • O retorno tátil claro proporciona sensações claras e claras que são menos perturbadoras para os usuários.
  • O retorno tátil avançado tem maior expressividade e geralmente requer um hardware com mais recursos.
Plataforma da API Disponibilidade Limpar retorno tátil Retorno tátil avançado
HapticFeedbackConstants (link em inglês) Android 1.5+
(por constante)
VibrationEffect predefinido Android 10 e versões mais recentes
Composição VibrationEffect (em inglês) Android 11 ou mais recente (por constante)
Vibrações de ativação/desativação, one-shot e forma de onda Android 1

Além disso, as APIs de notificação, descritas nesta página, permitem personalizar os efeitos táteis que são reproduzidos para notificações recebidas.

Nesta página, também são descritos outros conceitos que abrangem as plataformas de API:

HapticFeedbackConstants

A classe HapticFeedbackConstants fornece constantes baseadas em ação para permitir que os apps adicionem um retorno tátil consistente em toda a experiência do dispositivo, em vez de que cada app tenha efeitos diferentes para ações comuns.

Compatibilidade e requisitos

O uso do método View.performHapticFeedback com essas constantes não exige nenhuma permissão especial para o app. Ele está sujeito à propriedade View.hapticFeedbackEnabled, que, se definida como false, vai desativar todas as chamadas de feedback tátil na visualização, incluindo as padrão.A configuração relacionada principal da propriedade View.hapticFeedbackEnabled, que, se definida como false, desativa todas as chamadas de retorno tátil na visualização, incluindo as padrão. O método também respeita a configuração do sistema do usuário para ativar o feedback por toque.

A única consideração de compatibilidade é o nível do SDK da constante específica da ação.

Não é necessário fornecer um comportamento substituto ao usar HapticFeedbackConstants.

Uso de HapticsFeedbackConstants

Para ver detalhes sobre o uso de HapticFeedbackConstants, consulte Adicionar retorno tátil aos eventos.

VibrationEffect predefinido

A classe VibrationEffect fornece várias constantes predefinidas, como CLICK, TICK e DOUBLE_CLICK. Esses efeitos podem ser otimizados para o dispositivo.

Compatibilidade e requisitos

A execução de qualquer VibrationEffect exige a permissão VIBRATE no manifesto do app.

Não é necessário fornecer um comportamento de fallback ao usar o VibrationEffect predefinido, já que as constantes que não têm uma implementação otimizada para o dispositivo são revertidas para um substituto padrão da plataforma.

As APIs Vibrator.areEffectsSupported e Vibrator.areAllEffectsSupported servem para determinar se há uma implementação otimizada para dispositivos. Os efeitos predefinidos ainda podem ser usados sem uma implementação otimizada e usam o substituto padrão da plataforma. Consequentemente, essas APIs areEffectsSupported são necessárias apenas se um aplicativo quiser considerar se o efeito está otimizado para o dispositivo ou não.

Os métodos de verificação de efeito podem retornar um destes três valores:

Como o valor UNKNOWN indica que a API de verificação está indisponível, ele normalmente é retornado para todos os efeitos ou para nenhum deles. Esses dispositivos retornam dinamicamente.

Uso de VibrationEffect predefinido

Para detalhes sobre como usar um VibrationEffect predefinido, consulte Usar um VibrationEffect predefinido para gerar retorno tátil.

Composição: VibrationEffect

Uma composição VibrationEffect é um efeito de vibração criado usando a API VibrationEffect.startComposition. Essa API possibilita retorno tátil avançados (link em inglês) criando uma sequência de primitivas com atrasos e intensidades personalizados. No entanto, tome cuidado especial para garantir que o dispositivo tenha suporte aos recursos que estão sendo combinados para evitar uma experiência geral inconsistente.

Compatibilidade e requisitos

A execução de qualquer VibrationEffect exige a permissão VIBRATE no manifesto do app.

Nem todos os dispositivos oferecem suporte a todos os recursos da API de composição, e é importante garantir que os primitivos estejam disponíveis.

Verificar o suporte ao primitivo de vibração

O suporte por primitivo pode ser recuperado usando o método Vibrator.arePrimitivesSupported. Como alternativa, um conjunto de primitivos pode ser verificado em conjunto usando o método Vibrator.areAllPrimitivesSupported. Isso equivale a AND ativar o suporte por primitivo.

Uso de composições VibrationEffect

Para saber mais sobre o uso de composições VibrationEffect, consulte Criar composições de vibração.

Vibrações únicas, únicas e em forma de onda

A forma mais antiga de vibração com suporte no Android são padrões simples de ativação e desativação da vibração com durações configuráveis. Em geral, essas APIs não estão bem alinhadas aos princípios de design tátil porque podem gerar retorno tátil. Evite essas APIs, exceto como último recurso.

O caso de uso mais comum para vibrações ativadas são as notificações, em que, não importa o quê, um pouco de vibração é desejado. As vibrações em forma de onda também permitem exclusivamente que um padrão se repita indefinidamente, como você pode imaginar para um toque.

Um padrão único refere-se a vibrar uma vez por N milissegundos.

Há dois tipos de padrões de forma de onda:

  • Somente tempo. Esse tipo de forma de onda é uma descrição de durações alternadas e de durações gastas. O tempo começa com a duração gasta desativada. Por isso, os padrões de forma de onda geralmente começam com um valor zero para indicar que vão começar a vibrar imediatamente.
  • Tempos e amplitudes. Esse tipo de onda tem uma matriz adicional de amplitudes para corresponder a cada figura de tempo, em vez da ativação implícita da primeira forma. No entanto, é importante verificar se o dispositivo oferece suporte ao controle de amplitude para garantir que o escalonamento pretendido possa ser alcançado.

Compatibilidade e requisitos

Como as vibrações ativadas são a forma mais antiga de vibração, elas são aceitas em praticamente todos os dispositivos com uma vibração, conforme descrito mais adiante nesta página.

A reprodução de chamadas VibrationEffect ou de estilo mais antigo vibrate exige a permissão VIBRATE no manifesto do app.

Ao usar valores de amplitude diferentes em uma forma de onda, é altamente recomendável que o dispositivo ofereça suporte ao controle de amplitude.

Verificar o suporte ao controle de amplitude

Valores de amplitude diferentes de zero são arredondados para 100% em dispositivos sem controle de amplitude. Por isso, é importante verificar se há suporte usando Vibrator.hasAmplitudeControl. Consulte o controle de amplitude para mais detalhes.

Considere cuidadosamente se o efeito tem qualidade suficiente sem controle de amplitude. Pode ser melhor voltar para uma vibração ativada ou desativada explicitamente.

Uso de vibrações ativadas e desativadas

Nos níveis mais recentes do SDK, todos os modos de vibração foram consolidados em uma única classe VibrationEffect expressiva, em que essas vibrações simples são criadas usando VibrationEffect.createOneshot ou VibrationEffect.createWaveform.

APIs Notification

Ao personalizar as notificações do app, é possível usar uma das APIs abaixo para associar um padrão a cada canal de notificação:

Todas essas formas assumem um padrão de forma de onda de ativação básico, conforme descrito anteriormente, em que a primeira entrada é o atraso antes de ativar o vibrador.

Conceitos gerais

Vários conceitos se aplicam às superfícies de API detalhadas acima.

O dispositivo tem uma vibração?

Você pode conseguir uma classe Vibrator não nula de context.getSystemService(Vibrator.class). Se o dispositivo não tiver um vibrador, as chamadas para as APIs de vibração não terão nenhum efeito, portanto, os apps não vão precisar limitar o retorno tátil em uma condição. No entanto, se necessário, um aplicativo pode chamar hasVibrator() para determinar se esse é um vibrador real (true) ou um stub (false).

O usuário desativou o retorno tátil?

Algumas implementações personalizadas podem exigir a verificação manual se o usuário desativou totalmente a configuração Feedback de toque do Android. Nesse caso, os efeitos do feedback de toque precisam ser suprimidos. Essa configuração pode ser consultada usando a chave HAPTIC_FEEDBACK_ENABLED, em que um valor de zero significa desativado.

Atributos de vibração

Atributos de vibração (atualmente na forma de AudioAttributes) podem ser fornecidos para ajudar a informar ao sistema a finalidade da vibração. Isso é necessário ao iniciar uma vibração quando o app está em segundo plano, já que apenas o retorno tátil de atenção tem suporte ao uso em segundo plano.

A criação do AudioAttributes é abordada na documentação da classe e precisa ser considerada vibração em vez de som.

Como guia, na maioria dos casos, o tipo de conteúdo é CONTENT_TYPE_SONIFICATION, e o uso pode ser valores como USAGE_ASSISTANCE_SONIFICATION para feedback de toque em primeiro plano ou USAGE_ALARM para um alarme em segundo plano. As sinalizações de áudio não afetam as vibrações.

Controle de amplitude

Se uma vibração tiver controle de amplitude, ela poderá tocar vibrações com intensidades variadas. Esse é um recurso importante para produzir retorno tátil avançado, além de permitir ao usuário o controle das intensidades táteis padrão.

Verifique o suporte ao controle de amplitude chamando Vibrator.hasAmplitudeControl. Se uma vibração não oferecer suporte à amplitude, todos os valores de amplitude serão mapeados como desativados/ativados com base no fato de serem zero/diferente de zero. Consequentemente, os aplicativos que usam retorno tátil avançado com amplitudes variadas precisam considerar a desativação delas se o dispositivo não tiver controle de amplitude.