Referência da API Android Haptics

Esta seção apresenta as várias APIs de haptics disponíveis no Android. Ele também aborda quando e como verificar o suporte necessário para garantir que os efeitos hápticos sejam reproduzidos como você pretende.

Há várias maneiras diferentes de criar efeitos hápticos, e é importante considerar os princípios de design de háptica 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 comportamento de fallback e precisa ser combinada com a verificação do suporte individual do dispositivo.
  • Os haptics claros são sensações nítidas e limpas que são menos perturbadoras para os usuários.
  • Os haptics avançados têm maior expressividade e muitas vezes exigem hardware com mais recursos.
Superfície da API Disponibilidade Limpar retorno tátil Retorno tátil avançado
HapticFeedbackConstants Android 1.5+
(por constante)
VibrationEffect predefinido Android 10 ou mais recente
Composição de VibrationEffect Android 11 e versões mais recentes (por constante)
Vibrações de ativação/desativação, one-shot e de forma de onda Android 1

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

Também são descritos nesta página outros conceitos que abrangem as plataformas da API:

HapticFeedbackConstants

A classe HapticFeedbackConstants fornece constantes baseadas em ações para permitir que os apps adicionem um retorno tátil consistente em toda a experiência do dispositivo, em vez de cada app ter 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, desativa todas as chamadas de feedback tátil na visualização, incluindo as padrão.A configuração principal relacionada à propriedade View.hapticFeedbackEnabled, se definida como false, desativa todas as chamadas de feedback 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 de toque.

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

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

Uso de HapticsFeedbackConstants

Para saber mais sobre o uso de HapticFeedbackConstants, consulte Adicionar feedback tátil a eventos.

VibrationEffect predefinido

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

Compatibilidade e requisitos

A reprodução de qualquer VibrationEffect requer a permissão VIBRATE no manifesto do app.

Não é necessário fornecer um comportamento substituto ao usar VibrationEffect predefinido, porque as constantes que não têm uma implementação otimizada para dispositivos revertem 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 a substituição padrão da plataforma. Consequentemente, essas APIs areEffectsSupported só são necessárias se um app quiser considerar se o efeito é otimizado para o dispositivo ou não.

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

Como o valor UNKNOWN indica que a API de verificação não está disponível, ela normalmente é retornada para todos os efeitos ou nenhum deles. Esses dispositivos usam o fallback dinâmico.

Uso de VibrationEffect predefinido

Para saber mais sobre o uso de um VibrationEffect predefinido, consulte Usar um VibrationEffect predefinido para gerar feedback tátil.

Composição VibrationEffect

Uma composição VibrationEffect é um efeito de vibração criado usando a API VibrationEffect.startComposition. Essa API permite háptica rica expressiva, criando uma sequência de primitivas com atrasos e intensidades personalizados. No entanto, tome cuidado especial para garantir que o dispositivo ofereça suporte aos recursos que estão sendo combinados para evitar uma experiência geral inconsistente.

Compatibilidade e requisitos

A reprodução de qualquer VibrationEffect requer 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 as primitivas estejam disponíveis.

Verificar o suporte a primitivas de vibração

O suporte por primitiva 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 é equivalente a AND-ar 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 de ativação/desativação, únicas e de 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 com durações configuráveis. Essas APIs geralmente não estão bem alinhadas com os princípios de design de haptics porque podem gerar haptics barulhentos. Evite usá-las, a menos que seja o último recurso.

O caso de uso mais comum para vibrações intermitentes são notificações, em que, não importa o que aconteça, alguma vibração é desejada. As vibrações de forma de onda também permitem que um padrão seja repetido indefinidamente, como em um toque de telefone.

Um padrão de disparo único vibra uma vez por N milissegundos.

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

  • Somente marcações de tempo. Esse tipo de forma de onda é uma descrição de durações alternadas de tempo de inatividade e de atividade. Os tempos começam com a duração gasta. Consequentemente, os padrões de forma de onda geralmente começam com um valor zero para indicar que a vibração começa imediatamente.
  • Tempos e amplitudes. Esse tipo de forma de onda tem uma matriz adicional de amplitudes para corresponder a cada figura de tempo, em vez do ativado-desativado implícito da primeira forma. No entanto, é importante verificar se o dispositivo oferece suporte ao controle de amplitude para garantir que a escala desejada seja alcançada.

Compatibilidade e requisitos

Como as vibrações alternadas são a forma mais antiga de vibração, elas são compatíveis com quase todos os dispositivos com um vibrador, conforme descrito mais adiante nesta página.

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

Ao usar diferentes valores de amplitude em uma forma de onda, recomendamos que o dispositivo ofereça suporte a 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. Portanto, é importante verificar se o suporte está presente usando Vibrator.hasAmplitudeControl. Consulte o controle de amplitude para mais detalhes.

Considere cuidadosamente se o efeito tem qualidade suficiente sem controle de amplitude. Talvez seja melhor usar uma vibração ativada/desativada projetada explicitamente.

Uso de vibrações de ativação e desativação

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

APIs de notificação

Ao personalizar as notificações do app, você pode usar uma das seguintes APIs para associar um padrão a cada canal de notificação:

Todas essas formas têm um padrão de forma de onda ativa/desativa básico, como descrito anteriormente, em que a primeira entrada é o atraso antes de ativar o vibrador.

Conceitos gerais

Vários conceitos se aplicam às plataformas de API detalhadas acima.

O dispositivo tem um vibrador?

É possível acessar uma classe Vibrator não nula em context.getSystemService(Vibrator.class). Se o dispositivo não tiver um vibrador, as chamadas para as APIs de vibração não terão efeito. Portanto, os apps não precisam bloquear todas as vibrações em uma condição. No entanto, se necessário, um aplicativo pode chamar hasVibrator() para determinar se é um vibrador real (true) ou um stub (false).

O usuário desativou a resposta tátil?

Algumas implementações personalizadas podem exigir a verificação manual se o usuário desativou completamente a configuração Feedback tátil do Android. Nesse caso, os efeitos de feedback tátil 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 o sistema sobre o propósito da vibração. Isso é necessário ao iniciar uma vibração quando o app está em segundo plano, já que apenas a haptics de atenção é compatível com o uso em segundo plano.

A criação de AudioAttributes é abordada na documentação da classe e deve ser considerada como 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 tátil em primeiro plano ou USAGE_ALARM para um alarme em segundo plano. As flags de áudio não afetam as vibrações.

Controle de amplitude

Se um vibrador tiver controle de amplitude, ele poderá reproduzir vibrações com intensidades variáveis. Esse é um recurso importante para produzir hápticas ricas, além de permitir que o usuário controle as intensidades de háptica padrão.

O suporte ao controle de amplitude pode ser verificado chamando Vibrator.hasAmplitudeControl. Se um vibrador não tiver suporte à amplitude, todos os valores de amplitude serão mapeados para "desativado/ativado" com base em se eles são zero/não zero. Consequentemente, os aplicativos que usam haptics avançados com amplitudes variáveis devem considerar desativá-los se o dispositivo não tiver controle de amplitude.