Referência da API Android Haptics

Esta seção apresenta as várias APIs hápticas disponíveis no Android. Ele também mostra quando e como verificar se há suporte necessário para garantir que os efeitos táteis sejam reproduzidos como você quer.

Há várias maneiras de criar efeitos hápticos, e é importante considerar os princípios de design do feedback háptico 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 fallback de comportamento e precisa ser combinada com a verificação do suporte de dispositivos individuais.
  • As respostas táteis claras são sensações nítidas e limpas que são menos desagradáveis para os usuários.
  • As respostas táteis avançadas têm mais expressividade e geralmente exigem hardware mais completo.
Superfície da API Disponibilidade Limpar retorno tátil Retorno tátil avançado
HapticFeedbackConstants Android 1.5+
(por constante)
Predefined VibrationEffect Android 10 ou mais recente
Composição 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.

Nesta página, também descrevemos outros conceitos que abrangem as superfícies da API:

HapticFeedbackConstants

A classe HapticFeedbackConstants fornece constantes baseadas em ações para permitir que os apps adicionem feedback 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 permissões especiais 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 principal configuração relacionada é a propriedade View.hapticFeedbackEnabled, que, 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 tátil.

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 de substituição ao usar HapticFeedbackConstants.

Uso de HapticsFeedbackConstants

Para detalhes sobre como usar HapticFeedbackConstants, consulte Adicionar feedback tátil a 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

Para reproduzir qualquer VibrationEffect, é necessário ter a permissão VIBRATE no manifesto do app.

Não é necessário fornecer um comportamento substituto ao usar VibrationEffect predefinidos, já que constantes que não têm uma implementação otimizada para dispositivos voltam a um substituto padrão da plataforma.

As APIs Vibrator.areEffectsSupported e Vibrator.areAllEffectsSupported são usadas para determinar se há uma implementação otimizada para dispositivos. Efeitos predefinidos ainda podem ser usados sem uma implementação otimizada e usam o fallback padrão da plataforma. Consequentemente, essas APIs areEffectsSupported só são necessárias 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 de três valores:

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

Uso de VibrationEffect predefinidos

Para detalhes sobre como usar um VibrationEffect predefinido, consulte Usar um VibrationEffect predefinido para gerar feedback háptico.

Envelope VibrationEffect

As vibrações baseadas em envelope permitem o controle preciso da amplitude e da frequência da vibração ao longo do tempo, definindo uma sequência de pontos de controle. Isso permite que os desenvolvedores criem experiências de feedback háptico mais ricas e detalhadas. Essas vibrações podem ser criadas usando as classes BasicEnvelopeBuilder e WaveformEnvelopeBuilder.

Compatibilidade e requisitos

Para reproduzir efeitos de vibração, o app precisa declarar a permissão VIBRATE no manifesto do app.

Para verificar a compatibilidade com efeitos de envelope, chame Vibrator.areEnvelopeEffectsSupported().

Criador de envelopes básico

Para criar uma experiência tátil suave e perfeita, os efeitos de envelope precisam começar e terminar com uma intensidade de \( 0.0 \). A API faz isso corrigindo a intensidade inicial em zero e gerando uma exceção se a intensidade final não for zero. Essa restrição evita efeitos dinâmicos indesejáveis nas vibrações devido a descontinuidades na amplitude que podem afetar negativamente a percepção háptica do usuário.

Para oferecer uma renderização consistente do efeito de envelope em todos os dispositivos, o framework exige que os dispositivos compatíveis com esse recurso possam processar uma duração mínima de 20 ms entre pontos de controle e pelo menos 16 pontos para efeitos de envelope.

Criador de envelopes de forma de onda

O framework não modifica os valores de frequência e amplitude solicitados fornecidos pelo desenvolvedor. No entanto, a API também corrige a amplitude inicial em zero para criar transições suaves.

Para ajudar você a otimizar os efeitos de envelope de forma de onda do app e oferecer compatibilidade entre dispositivos, o Android fornece APIs para consultar recursos importantes do dispositivo. Esses métodos fornecem informações sobre as limitações do dispositivo, como a duração máxima e mínima da transição entre pontos de controle e o número máximo de pontos de controle compatíveis com um único efeito:

getMaxSize()
Recupera o número máximo de pontos de controle compatíveis com um efeito de envelope.
getMinControlPointDurationMillis()
Recupera a duração mínima compatível, em milissegundos, entre dois pontos de controle em um efeito de envelope.
getMaxControlPointDurationMillis()
Recupera a duração máxima compatível, em milissegundos, entre dois pontos de controle em um efeito de envelope.
getMaxDurationMillis()
Recupera a duração máxima aceita para um efeito de envelope, em milissegundos.

Se um efeito exceder as limitações do dispositivo, como permitir muitos pontos de controle ou uma duração maior que o máximo, o framework vai ajustar automaticamente o efeito para se adequar aos limites permitidos. Esse processo tenta preservar a intenção e a sensação originais do design o máximo possível.

Uso de Envelope VibrationEffects

Para detalhes sobre como criar efeitos de forma de onda de envelope, consulte criar forma de onda de vibração com envelopes.

Composição VibrationEffect

Uma composição VibrationEffect é um efeito de vibração criado usando a API VibrationEffect.startComposition. Essa API permite hápticos avançados expressivos criando uma sequência de primitivos com atrasos e intensidades personalizados. No entanto, tome cuidado para garantir que o dispositivo seja compatível com os recursos combinados para evitar uma experiência geral inconsistente.

Compatibilidade e requisitos

Para reproduzir qualquer VibrationEffect, é necessário ter a permissão VIBRATE no manifesto do app.

Nem todos os dispositivos são compatíveis com todos os recursos da API Composition. Por isso, é 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 primitivas pode ser verificado usando o método Vibrator.areAllPrimitivesSupported, que é equivalente a AND-ing o suporte por primitiva.

Uso de composições VibrationEffect

Para detalhes sobre como usar composições VibrationEffect, consulte Criar composições de vibração.

Vibrações de liga/desliga, únicas e de forma de onda

A forma mais antiga de vibração compatível com o Android são padrões simples de vibrador ligado/desligado com durações configuráveis. Essas APIs geralmente não estão bem alinhadas com os princípios de design de hápticos porque podem gerar hápticos vibratórios. Evite usá-las, exceto como último recurso.

O caso de uso mais comum para vibrações on-off são as notificações, em que alguma vibração é desejada. As vibrações de forma de onda também permitem que um padrão se repita indefinidamente, como você pode imaginar para um toque.

Um padrão único se refere a vibrar 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 desligado e tempo ligado. Os tempos começam com a duração gasta desligada. Consequentemente, os padrões de forma de onda geralmente começam com um valor zero para indicar que a vibração deve começar imediatamente.
  • Marcações de tempo e amplitudes. Esse tipo de forma de onda tem uma matriz adicional de amplitudes para corresponder a cada figura de tempo, em vez do liga/desliga implícito da primeira forma. No entanto, é importante verificar se o dispositivo é compatível com o controle de amplitude para garantir que o dimensionamento pretendido possa ser alcançado.

Compatibilidade e requisitos

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

Para reproduzir qualquer chamada VibrationEffect ou vibrate de estilo mais antigo, é necessário ter a permissão VIBRATE no manifesto do app.

Ao usar diferentes valores de amplitude em uma forma de onda, recomendamos que o dispositivo seja compatível com o 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 o suporte está presente usando Vibrator.hasAmplitudeControl. Consulte o controle de amplitude para mais detalhes.

Considere com cuidado se o efeito tem qualidade suficiente sem o controle de amplitude. É melhor usar uma vibração on-off projetada explicitamente.

Uso de vibrações intermitentes

Em níveis de SDK mais recentes, 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 de notificação

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

Todas essas formas usam um padrão básico de forma de onda de ativação/desativação, 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 um vibrador?

É possível receber 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 efeito. Portanto, os apps não precisam restringir todos os recursos hápticos a 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 ao toque?

Algumas implementações personalizadas podem exigir a verificação manual para saber 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 zero significa desativado.

Atributos de vibração

Os atributos de vibração (atualmente na forma de AudioAttributes) podem ser fornecidos para ajudar a informar o sistema sobre a finalidade da vibração. Isso é necessário ao iniciar uma vibração quando o app está em segundo plano, já que apenas hápticos de atenção são compatíveis 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. Os indicadores de áudio não afetam as vibrações.

Controle de amplitude

Se um vibrador tiver controle de amplitude, ele poderá emitir vibrações com intensidades variadas. Essa é uma capacidade importante para produzir hápticos avançados, além de permitir o controle do usuário das intensidades hápticas padrão.

Para verificar se há suporte para controle de amplitude, chame Vibrator.hasAmplitudeControl. Se um vibrador não tiver suporte para amplitude, todos os valores de amplitude serão mapeados para desligado/ligado com base em se eles são zero/diferentes de zero. Consequentemente, os aplicativos que usam háptica avançada com amplitudes variadas precisam considerar a desativação se o dispositivo não tiver controle de amplitude.

Suporte a efeitos de envelope

Os vibradores com suporte a efeitos de envelope permitem a criação de vibrações mais dinâmicas e sutis, oferecendo controle mais preciso sobre a intensidade e a nitidez para experiências táteis mais ricas. Use Vibration.areEnvelopeEffectsSupported para determinar se o dispositivo é compatível com esse recurso. Caso contrário, as vibrações baseadas em envelope serão ignoradas.