Documentation de référence de l'API haptique Android

Ce document présente les différentes API de technologies haptiques disponibles dans Android. Il explique comment créer différents effets haptiques et comment vérifier la compatibilité de l'appareil. keywords_public: > Android, technologies haptiques, API, vibreur, HapticFeedbackConstants, VibrationEffect, haptique d'enveloppe, retour haptique, notification, contrôle de l'amplitude

Cette section présente les différentes API haptiques disponibles dans Android. Il explique également quand et comment vérifier la compatibilité des appareils nécessaire pour que vos effets haptiques se déclenchent comme prévu.

Il existe plusieurs façons de créer des effets haptiques. Il est important de tenir compte des principes de conception des effets haptiques Android lorsque vous faites votre choix. Le tableau suivant récapitule ces attributs de haut niveau pour chaque approche :

  • La disponibilité est particulièrement importante lors de la planification du comportement de secours et doit être combinée à la vérification de la compatibilité des appareils individuels.
  • Les retours haptiques clairs sont des sensations nettes et précises qui sont moins désagréables pour les utilisateurs.
  • Les retours haptiques riches sont plus expressifs et nécessitent souvent un matériel plus performant.
Surface d'API Disponibilité Effacer les vibrations Retour haptique enrichi
HapticFeedbackConstants Android 1.5+
(par constante)
Predefined VibrationEffect Android 10 et versions ultérieures
VibrationEffect composition (recommandé) Android 16 et versions ultérieures (T4 2024)
Composition des primitives VibrationEffect Android 11 et versions ultérieures (par constante)
Vibrations "On/Off", "One-shot" et "Forme d'onde" Android 1

De plus, les API de notification décrites sur cette page vous permettent de personnaliser les effets haptiques qui se déclenchent pour les notifications entrantes.

Cette page décrit également d'autres concepts qui s'étendent aux surfaces de l'API :

HapticFeedbackConstants

La classe HapticFeedbackConstants fournit des constantes basées sur des actions pour permettre aux applications d'ajouter un retour haptique cohérent avec l'expérience de l'appareil, plutôt que d'avoir des effets différents pour les actions courantes.

Compatibilité et exigences

L'utilisation de la méthode View.performHapticFeedback avec ces constantes ne nécessite aucune autorisation spéciale pour l'application. Elle est soumise à la propriété View.hapticFeedbackEnabled, qui, si elle est définie sur false, désactive tous les appels de rétroaction haptique sur la vue, y compris ceux par défaut.Le paramètre principal associé est la propriété View.hapticFeedbackEnabled, qui, si elle est définie sur false, désactive tous les appels de rétroaction haptique sur la vue, y compris ceux par défaut. La méthode respecte également le paramètre système de l'utilisateur pour activer le retour haptique.

La seule considération de compatibilité est le niveau SDK de la constante spécifique à l'action.

Il n'est pas nécessaire de fournir un comportement de secours lorsque vous utilisez HapticFeedbackConstants.

Utilisation de HapticsFeedbackConstants

Pour en savoir plus sur l'utilisation de HapticFeedbackConstants, consultez Ajouter un retour haptique aux événements.

Prédéfini : VibrationEffect

La classe VibrationEffect fournit plusieurs constantes prédéfinies telles que CLICK, TICK et DOUBLE_CLICK. Ces effets peuvent être optimisés pour l'appareil.

Compatibilité et exigences

Pour lire un VibrationEffect, l'autorisation VIBRATE est requise dans le fichier manifeste de l'application.

Il n'est pas nécessaire de fournir un comportement de remplacement lorsque vous utilisez des VibrationEffect prédéfinis, car les constantes qui n'ont pas d'implémentation optimisée pour l'appareil reviennent à un remplacement de plate-forme standard.

Les API Vibrator.areEffectsSupported et Vibrator.areAllEffectsSupported permettent de déterminer s'il existe une implémentation optimisée pour l'appareil. Les effets prédéfinis peuvent toujours être utilisés sans implémentation optimisée et utilisent le remplacement de plate-forme standard. Par conséquent, ces API areEffectsSupported ne sont nécessaires que si une application souhaite prendre en compte le fait que l'effet est optimisé ou non pour l'appareil.

Les méthodes de vérification des effets peuvent renvoyer l'une des trois valeurs suivantes :

Étant donné que la valeur UNKNOWN indique que l'API de vérification n'est pas disponible, elle est généralement renvoyée pour tous les effets ou aucun d'entre eux. Ces appareils sont compatibles avec le basculement dynamique.

Utilisation de VibrationEffect prédéfini

Pour savoir comment utiliser un VibrationEffect prédéfini, consultez Utiliser un VibrationEffect prédéfini pour générer un retour haptique.

Envelope VibrationEffect

Les vibrations basées sur l'enveloppe permettent de contrôler précisément l'amplitude et la fréquence des vibrations au fil du temps en définissant une séquence de points de contrôle. Les développeurs peuvent ainsi créer des expériences de rétroaction haptique plus riches et plus nuancées. Ces vibrations peuvent être créées à l'aide des classes BasicEnvelopeBuilder et WaveformEnvelopeBuilder.

Compatibilité et exigences

Pour lire des effets de vibration, votre application doit déclarer l'autorisation VIBRATE dans le fichier manifeste d'application.

Pour vérifier si les effets d'enveloppe sont pris en charge, appelez Vibrator.areEnvelopeEffectsSupported().

Outil de création d'enveloppes de base

Pour créer une expérience haptique fluide et homogène, les effets d'enveloppe doivent commencer et se terminer avec une intensité de \( 0.0 \). L'API applique cette règle en fixant l'intensité de départ à zéro et en générant une exception si l'intensité de fin n'est pas nulle. Cette contrainte empêche les effets dynamiques indésirables dans les vibrations en raison des discontinuités dans l'amplitude, qui peuvent avoir un impact négatif sur la perception haptique de l'utilisateur.

Pour que l'effet d'enveloppe soit rendu de manière cohérente sur tous les appareils, le framework exige que les appareils compatibles avec cette fonctionnalité puissent gérer une durée minimale de 20 ms entre les points de contrôle et au moins 16 points pour les effets d'enveloppe.

Outil de création d'enveloppes de forme d'onde

Le framework ne modifie pas les valeurs de fréquence et d'amplitude demandées fournies par le développeur. Toutefois, l'API fixe également l'amplitude de départ à zéro pour créer des transitions fluides.

Pour vous aider à optimiser les effets d'enveloppe de forme d'onde de votre application et assurer la compatibilité entre les appareils, Android fournit des API permettant d'interroger les fonctionnalités importantes des appareils. Ces méthodes fournissent des informations sur les limites de l'appareil, telles que la durée de transition maximale et minimale entre les points de contrôle, ainsi que le nombre maximal de points de contrôle acceptés pour un seul effet :

getMaxSize()
Récupère le nombre maximal de points de contrôle acceptés pour un effet d'enveloppe.
getMinControlPointDurationMillis()
Récupère la durée minimale acceptée, en millisecondes, entre deux points de contrôle dans un effet d'enveloppe.
getMaxControlPointDurationMillis()
Récupère la durée maximale acceptée, en millisecondes, entre deux points de contrôle dans un effet d'enveloppe.
getMaxDurationMillis()
Récupère la durée maximale acceptée pour un effet d'enveloppe, en millisecondes.

Si un effet dépasse les limites de l'appareil (par exemple, en autorisant un nombre trop important de points de contrôle ou une durée supérieure à la durée maximale), le framework ajuste automatiquement l'effet pour qu'il respecte les limites autorisées. Ce processus d'ajustement tente de préserver autant que possible l'intention et l'esprit du design d'origine.

Utilisation des Envelope VibrationEffects

Pour savoir comment créer des effets de forme d'onde d'enveloppe, consultez Créer une forme d'onde de vibration avec des enveloppes.

Composition de VibrationEffect

À partir d'Android 16 (4e trimestre 2026), VibrationEffect.Builder est l'API recommandée pour composer des effets haptiques riches et expressifs en séquençant plusieurs éléments haptiques le long d'une timeline conçue. Il remplace VibrationEffect.Composition en proposant une planification ancrée dans la timeline, une encapsulation atomique, une compatibilité avec les événements mixtes (combinant les préréglages et les enveloppes) et un retour automatique intégré.

Composants de base

L'outil de création vous permet de séquencer les éléments haptiques suivants :

  • VibrationEffect.Preset : sensations haptiques prédéfinies représentant des impulsions courtes courantes, telles que PRESET_CLICK, PRESET_TICK et PRESET_LOW_TICK. Les préréglages remplacent les primitives courtes de l'API VibrationEffect.Composition. Pour les effets plus longs, continus ou progressifs (auparavant gérés par les primitives de montée, de descente et autres), utilisez plutôt des enveloppes (PWLE). Les préréglages peuvent être mis à l'échelle de 0.0f à 1.0f à l'aide de Preset.create(presetId, scale).
  • VibrationEffect.Envelope : enveloppes linéaires par morceaux (PWLE) créées à l'aide de BasicEnvelopeBuilder (avec intensité et netteté) ou WaveformEnvelopeBuilder (avec fréquence et amplitude). Les enveloppes sont construites à l'aide de Envelope.create(builder).
  • VibrationEffect.Event : événements de la chronologie récupérés à partir d'un VibrationEffect existant à l'aide de getEvents(). Vous pouvez les ajouter avec un décalage de la timeline à l'aide de addEvents(startTimeShiftMillis, events).

Planification et validation de la chronologie

Chaque élément est ajouté au générateur avec un startTimeMillis représentant le décalage temporel (en millisecondes) par rapport au début de la composition :

  • Validation au moment de la compilation : les éléments doivent être ajoutés dans l'ordre croissant de leur heure de début. Le générateur effectue une validation au mieux au moment de la compilation en vérifiant la durée minimale (par exemple, 1 ms pour les préréglages ou les durées connues pour les enveloppes). Si un chevauchement est détecté au moment de la compilation, une erreur IllegalArgumentException est générée.
  • Alignement du timing de lecture : le framework fournit un support de timing au mieux pendant la lecture. Si un événement précédent est toujours en cours d'exécution à l'heure de début du prochain événement planifié, le framework décale automatiquement l'événement suivant au premier créneau disponible. Cela empêche les événements de se chevaucher lors de la lecture physique tout en garantissant qu'aucun événement haptique n'est supprimé.

Effets répétitifs

Un effet de répétition peut être ajouté à la composition à l'aide de setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). Une fois qu'un effet de répétition est configuré, aucun élément supplémentaire ne peut être ajouté au générateur.

Assistance de remplacement

La prise en charge de la redirection automatique au niveau du framework est activée par défaut pour les vibrations créées par VibrationEffect.Builder :

  • Remplacement transparent de la plate-forme : si un appareil n'est pas compatible avec un Preset ou un Envelope de base demandé, le framework remplace automatiquement l'élément non compatible par une vibration compatible appropriée au moment de l'exécution, dans la mesure du possible. Votre application n'a pas besoin de vérifier manuellement les capacités de l'appareil (telles que isPresetSupported) avant de lire les compositions créées avec VibrationEffect.Builder.
  • Exception pour WaveformEnvelopeBuilder : les effets d'enveloppe créés par WaveformEnvelopeBuilder (qui spécifient des fréquences physiques absolues en Hertz et des amplitudes en G) ne sont pas compatibles avec le remplacement automatique. Étant donné que les PWLE avancés s'appuient sur des courbes de fréquence matérielles spécifiques (FOAM), les remplacer automatiquement compromettrait l'intention de conception. Si l'appareil n'est pas compatible avec les effets PWLE ou les fréquences demandées, ces vibrations ne seront pas émises. Pour une compatibilité universelle, préférez BasicEnvelopeBuilder.

Utilisation de VibrationEffect.Builder

Pour obtenir des exemples de code sur la composition d'effets avec VibrationEffect.Builder, consultez Créer des compositions ancrées dans le code temporel avec VibrationEffect.Builder.

Composition des primitives VibrationEffect

Une composition de primitives VibrationEffect est un effet de vibration créé à l'aide de l'API VibrationEffect.startComposition. Cette API vous permet de créer une séquence de primitives.

Compatibilité et exigences

Pour lire un VibrationEffect, l'autorisation VIBRATE est requise dans le fichier manifeste de l'application.

Vérifier la compatibilité des primitives

Par conséquent, lorsque vous utilisez l'API VibrationEffect.Composition, vous devez vérifier la compatibilité par primitive à l'aide de Vibrator.arePrimitivesSupported ou Vibrator.areAllPrimitivesSupported avant de lire.

La compatibilité par primitive peut être récupérée à l'aide de la méthode Vibrator.arePrimitivesSupported. Vous pouvez également vérifier un ensemble de primitives à l'aide de la méthode Vibrator.areAllPrimitivesSupported. Cela équivaut à AND la prise en charge par primitive.

Utilisation des compositions de primitives VibrationEffect

Pour en savoir plus sur l'utilisation des compositions de primitives VibrationEffect, consultez Créer des compositions de primitives de vibration.

Vibrations marche/arrêt, ponctuelles et en forme d'onde

La forme de vibration la plus ancienne prise en charge sur Android est constituée de simples schémas de vibration avec des durées configurables. Ces API ne sont généralement pas bien alignées sur les principes de conception haptique, car elles peuvent générer des retours haptiques bourdonnants. Évitez-les, sauf en dernier recours.

Le cas d'utilisation le plus courant pour les vibrations marche/arrêt est celui des notifications, où une vibration est souhaitée quoi qu'il arrive. Les vibrations de forme d'onde permettent également à un motif de se répéter indéfiniment, comme vous pouvez l'imaginer pour une sonnerie.

Un schéma one-shot fait référence à une vibration unique de N millisecondes.

Il existe deux types de formes d'onde :

  • Codes temporels uniquement : Ce type de forme d'onde décrit les durées d'arrêt et de marche alternées. Les timings commencent par la durée de la période de désactivation. Par conséquent, les formes d'onde commencent souvent par une valeur nulle pour indiquer le début immédiat de la vibration.
  • Durées et amplitudes Ce type de forme d'onde comporte un tableau d'amplitudes supplémentaire à associer à chaque chiffre de timing, au lieu de l'activation/désactivation implicite de la première forme. Toutefois, il est important de vérifier que l'appareil est compatible avec le contrôle de l'amplitude pour s'assurer que la mise à l'échelle souhaitée peut être obtenue.

Compatibilité et exigences

Les vibrations marche/arrêt étant la forme de vibration la plus ancienne, elles sont prises en charge sur pratiquement tous les appareils dotés d'un vibreur, comme décrit plus loin sur cette page.

Pour lire des appels VibrationEffect ou vibrate (ancien style), l'autorisation VIBRATE est requise dans le fichier manifeste d'application.

Lorsque vous utilisez différentes valeurs d'amplitude dans une forme d'onde, nous vous recommandons vivement de vérifier que l'appareil est compatible avec le contrôle de l'amplitude.

Vérifier la prise en charge du contrôle de l'amplitude

Les valeurs d'amplitude non nulles sont arrondies à 100% sur les appareils sans contrôle d'amplitude. Il est donc important de vérifier si la prise en charge est présente à l'aide de Vibrator.hasAmplitudeControl. Pour en savoir plus, consultez la section Contrôle de l'amplitude.

Vous devez déterminer avec soin si votre effet est de qualité suffisante sans contrôle de l'amplitude. Il peut être préférable de revenir à une vibration marche/arrêt explicitement conçue.

Utilisation des vibrations activées/désactivées

Dans les niveaux de SDK plus récents, tous les modes de vibration ont été regroupés dans une seule classe expressive VibrationEffect, où ces vibrations simples sont créées à l'aide de VibrationEffect.createOneShot ou VibrationEffect.createWaveform.

API de notifications

Lorsque vous personnalisez les notifications de votre application, vous pouvez utiliser l'une des API suivantes pour associer un modèle à chaque canal de notification :

Toutes ces formes suivent un schéma de forme d'onde de base marche/arrêt, comme décrit précédemment, où la première entrée correspond au délai avant l'activation du vibreur.

Concepts généraux

Plusieurs concepts s'appliquent aux surfaces d'API détaillées ci-dessus.

L'appareil est-il équipé d'un vibreur ?

Vous pouvez obtenir une classe Vibrator non nulle à partir de context.getSystemService(Vibrator.class). Si l'appareil ne dispose pas de vibrateur, les appels aux API de vibration n'ont aucun effet. Les applications n'ont donc pas besoin de limiter toutes leurs fonctions haptiques à une condition. Toutefois, si nécessaire, une application peut appeler hasVibrator() pour déterminer s'il s'agit d'un véritable vibreur (true) ou d'un stub (false).

L'utilisateur a-t-il désactivé le retour haptique ?

Certaines implémentations personnalisées peuvent nécessiter de vérifier manuellement si l'utilisateur a complètement désactivé le paramètre Retour tactile d'Android. Dans ce cas, les effets de retour tactile doivent être supprimés. Ce paramètre peut être interrogé à l'aide de la clé HAPTIC_FEEDBACK_ENABLED, où une valeur de zéro signifie qu'il est désactivé.

Attributs de vibration

Des attributs de vibration (actuellement sous la forme AudioAttributes) peuvent être fournis pour informer le système de l'objectif de la vibration. Cela est nécessaire lorsque vous lancez une vibration lorsque votre application est en arrière-plan, car seules les vibrations attentionnelles sont prises en charge pour l'utilisation en arrière-plan.

La création de AudioAttributes est abordée dans la documentation de sa classe. Il faut la considérer comme une vibration plutôt que comme un son.

En règle générale, le type de contenu est CONTENT_TYPE_SONIFICATION et l'utilisation peut être des valeurs telles que USAGE_ASSISTANCE_SONIFICATION pour le retour haptique au premier plan ou USAGE_ALARM pour une alarme en arrière-plan. Les indicateurs audio n'ont aucune incidence sur les vibrations.

Contrôle de l'amplitude

Si un vibreur est doté d'un contrôle d'amplitude, il peut émettre des vibrations d'intensités variables. Il s'agit d'une fonctionnalité importante pour produire des retours haptiques riches, et qui permet potentiellement aux utilisateurs de contrôler les intensités haptiques par défaut.

Pour vérifier si le contrôle de l'amplitude est pris en charge, appelez Vibrator.hasAmplitudeControl. Si un vibreur n'est pas compatible avec l'amplitude, toutes les valeurs d'amplitude seront mappées sur "désactivé" ou "activé" selon qu'elles sont nulles ou non nulles. Par conséquent, les applications utilisant des retours haptiques riches avec des amplitudes variables doivent envisager de les désactiver si l'appareil ne dispose pas de contrôle de l'amplitude.

Prise en charge des effets d'enveloppe

Les moteurs de vibration avec prise en charge des effets d'enveloppe permettent de créer des vibrations plus dynamiques et nuancées, offrant un contrôle plus précis de l'intensité et de la netteté pour des expériences haptiques plus riches. Utilisez Vibration.areEnvelopeEffectsSupported pour déterminer si votre appareil est compatible avec cette fonctionnalité. Si ce n'est pas le cas, les vibrations basées sur l'enveloppe sont ignorées.