Referência da API Android Haptics

Esta seção apresenta as várias APIs de retorno tátil disponíveis no Android. Ele também aborda 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 diferentes de criar efeitos de retorno tátil, e é importante considerar os princípios de design do retorno 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 fallback de comportamento e precisa ser combinada com a verificação do suporte individual do dispositivo.
  • As respostas táteis claras são sensações nítidas e limpas que são menos desagradáveis para os usuários.
  • As hápticas avançadas têm mais expressividade e geralmente exigem hardware mais rico em recursos.
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 (recomendado) Android 16 ou mais recente (4º trimestre de 2026)
Composição de primitivas VibrationEffect Android 11 ou mais recente (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 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 permissões especiais para o app. Ele está sujeito à propriedade View.hapticFeedbackEnabled, que, se definida como false, desativa todas as chamadas de retorno 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 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 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 de substituição ao usar VibrationEffect predefinidos, já que as constantes que não têm uma implementação otimizada para dispositivos voltam a uma substituição de plataforma padrão.

As APIs Vibrator.areEffectsSupported e Vibrator.areAllEffectsSupported são usadas 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 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 predefinido

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 retorno tátil 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 se há suporte para efeitos de envelope, chame Vibrator.areEnvelopeEffectsSupported().

Criador de envelopes básico

Para criar uma experiência tátil suave e integrada, 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 processem 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 aceitos para 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 compatível com 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 a máxima, o framework vai ajustar automaticamente o efeito para se adequar aos limites permitidos. Esse processo de ajuste 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

A partir do Android 16 (4º trimestre de 2026), VibrationEffect.Builder será a API preferida para compor efeitos hápticos expressivos e avançados sequenciando vários elementos hápticos ao longo de uma linha do tempo projetada. Ele substitui VibrationEffect.Composition ao oferecer programação ancorada na linha do tempo, encapsulamento atômico, suporte a eventos mistos (combinando predefinições e envelopes) e fallback automático integrado.

Elementos básicos

O criador permite sequenciar os seguintes elementos hápticos:

  • VibrationEffect.Preset: sensações táteis predefinidas que representam pulsos curtos comuns, como PRESET_CLICK, PRESET_TICK e PRESET_LOW_TICK. As predefinições substituem as primitivas curtas da API VibrationEffect.Composition. Para efeitos mais longos, contínuos ou crescentes (antes processados por aumento, diminuição e outras primitivas), use envelopes (PWLE). Os presets podem ser dimensionados de 0.0f a 1.0f usando Preset.create(presetId, scale).
  • VibrationEffect.Envelope: envelopes lineares por partes (PWLEs) criados usando BasicEnvelopeBuilder (com intensidade e nitidez) ou WaveformEnvelopeBuilder (com frequência e amplitude). Os envelopes são criados usando Envelope.create(builder).
  • VibrationEffect.Event: eventos da linha do tempo recuperados de um VibrationEffect usando getEvents(). Eles podem ser adicionados com um deslocamento de linha do tempo usando addEvents(startTimeShiftMillis, events).

Programação e validação de cronogramas

Cada elemento é adicionado ao builder com um startTimeMillis que representa o ajuste de tempo (em milissegundos) desde o início da composição:

  • Validação no momento da build:os elementos precisam ser adicionados em ordem estritamente crescente dos horários de início. O builder realiza a validação de melhor esforço no tempo de build, verificando a duração mínima (como 1 ms para predefinições ou durações conhecidas para envelopes). Se uma sobreposição for detectada durante o tempo de build, um IllegalArgumentException será gerado.
  • Alinhamento de tempo de reprodução:o framework oferece o melhor suporte possível de tempo durante a reprodução. Se um evento anterior ainda estiver em execução quando chegar a hora de início do próximo evento programado, o framework vai transferir automaticamente o evento subsequente para o próximo horário disponível. Isso evita que os eventos se sobreponham na reprodução física e garante que nenhum evento háptico seja descartado.

Efeitos repetidos

Um efeito de repetição pode ser adicionado à composição usando setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). Depois que um efeito repetido é configurado, não é possível adicionar mais elementos ao criador de apps.

Suporte de substituição

O suporte de substituição automática no nível do framework é ativado por padrão para vibrações criadas por VibrationEffect.Builder:

  • Substituição transparente de plataforma:se um dispositivo não for compatível com um Preset ou Envelope básico solicitado, o framework vai substituir automaticamente o elemento sem suporte por uma vibração adequada compatível no tempo de execução da melhor maneira possível. O app não precisa verificar manualmente os recursos do dispositivo (como isPresetSupported) antes de tocar composições criadas com VibrationEffect.Builder.
  • Exceção para WaveformEnvelopeBuilder:os efeitos de envelope criados por WaveformEnvelopeBuilder (que especificam frequências físicas absolutas em Hertz e amplitudes em Gs) não têm suporte de substituição automática. Como as PWLEs avançadas dependem de curvas de frequência de hardware específicas (FOAM), a substituição automática comprometeria a intenção de design. Se o dispositivo não for compatível com efeitos PWLE ou com as frequências solicitadas, essas vibrações não serão reproduzidas. Para compatibilidade universal, prefira BasicEnvelopeBuilder.

Uso de VibrationEffect.Builder

Para ver exemplos de código sobre como criar efeitos com VibrationEffect.Builder, consulte Criar composições ancoradas na linha do tempo com VibrationEffect.Builder.

Composição de primitivos VibrationEffect

Uma composição de primitivos VibrationEffect é um efeito de vibração criado usando a API VibrationEffect.startComposition. Com essa API, é possível criar uma sequência de primitivos.

Compatibilidade e requisitos

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

Verificar o suporte a primitivas

Portanto, ao usar a API VibrationEffect.Composition, verifique o suporte por primitiva usando Vibrator.arePrimitivesSupported ou Vibrator.areAllPrimitivesSupported antes de jogar.

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 de primitivas VibrationEffect

Para detalhes sobre como usar composições de primitivos VibrationEffect, consulte Criar composições de primitivos 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 vibração ligados/desligados com durações configuráveis. Essas APIs geralmente não estão bem alinhadas com os princípios de design de retorno tátil porque podem gerar retorno tátil vibratório. 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, não importa o 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 gasto desligado e 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 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, você pode usar uma das seguintes APIs para associar um padrão a cada canal de notificação:

Todas essas formas seguem um padrão de forma de onda on-off básico, conforme descrito anteriormente, em que a primeira entrada é o atraso antes de ligar 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 deixar todos os recursos hápticos 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 o retorno 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 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 háptica atencional é 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.

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á tocar vibrações com intensidades variadas. Essa é uma capacidade importante para produzir retorno tátil avançado, além de permitir o controle do usuário das intensidades de retorno tátil padrão.

Para verificar se há suporte para controle de amplitude, chame Vibrator.hasAmplitudeControl. Se um vibrador não tiver suporte à amplitude, todos os valores de amplitude serão mapeados como desligados ou ligados, dependendo se são zero ou diferentes de zero. Consequentemente, os aplicativos que usam retorno tátil avançado 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 intensidade e 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.