Cette section présente les différentes API haptiques disponibles dans Android. Il explique également quand et comment vérifier la compatibilité des appareils pour vous assurer que vos effets haptiques sont lus 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 | Technologies haptiques avancées |
|---|---|---|---|
| HapticFeedbackConstants | Android 1.5 ou version ultérieure (par constante) |
||
| Predefined VibrationEffect | Android 10 ou version ultérieure | ||
| Composition VibrationEffect | Android 11 et versions ultérieures (par constante) | ||
| Vibrations ponctuelles, avec forme d'onde ou d'activation/désactivation | 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 :
- L'appareil est-il équipé d'un vibreur ?
- Le contrôle de l'amplitude permet d'obtenir des effets haptiques plus fluides et plus riches, mais n'est pas pris en charge par tous les appareils.
VibrationAttributes()vous aide à classer les vibrations en fonction de leur utilisation, ce qui permet d'appliquer les paramètres utilisateur appropriés et d'éviter ainsi les surprises pour l'utilisateur.
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 chaque application ait 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.
VibrationEffect prédéfini
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, vous devez disposer de l'autorisation VIBRATE 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 les appareils 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 si 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 :
VIBRATION_EFFECT_SUPPORT_YESindique que l'appareil est optimisé pour cet effet.VIBRATION_EFFECT_SUPPORT_NOindique que l'appareil n'est pas compatible de manière optimale, mais qu'il utilise tout de même la plate-forme de secours.VIBRATION_EFFECT_SUPPORT_UNKNOWNindique que le système ne sait pas si l'implémentation est optimisée ou non.
É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 rétrocompatibles de manière 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 retour 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 de l'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 d'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.
Créateur d'enveloppe 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 pris en charge 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, s'il autorise un nombre trop important de points de contrôle ou une durée supérieure à la durée maximale), le framework l'ajuste automatiquement pour qu'il respecte les limites autorisées. Ce processus d'ajustement tente de préserver autant que possible l'intention et l'esprit d'origine de la conception.
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
Une composition VibrationEffect est un effet de vibration créé à l'aide de l'API VibrationEffect.startComposition. Cette API permet de créer des retours haptiques riches en créant une séquence de primitives avec des délais et des intensités personnalisés. Toutefois, veillez tout particulièrement à ce que l'appareil soit compatible avec les fonctionnalités combinées pour éviter une expérience globale incohérente.
Compatibilité et exigences
Pour lire un VibrationEffect, vous devez disposer de l'autorisation VIBRATE dans le fichier manifeste de l'application.
Tous les appareils ne sont pas compatibles avec toutes les fonctionnalités de l'API Composition. Il est donc important de s'assurer que les primitives sont disponibles.
Vérifier la compatibilité des primitives de vibration
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 en utilisant la méthode Vibrator.areAllPrimitivesSupported. Cela équivaut à AND la prise en charge par primitive.
Utilisation des compositions VibrationEffect
Pour en savoir plus sur l'utilisation des compositions VibrationEffect, consultez Créer des compositions de vibrations.
Vibrations marche/arrêt, ponctuelles et de 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 ponctuel 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 fonctionnement. Les durées commencent par la durée de désactivation. Par conséquent, les formes d'onde commencent souvent par une valeur nulle pour indiquer de commencer à vibrer immédiatement.
- Durées et amplitudes : Ce type de forme d'onde comporte un tableau d'amplitudes supplémentaire à associer à chaque valeur de timing, plutôt que le tableau implicite d'activation/désactivation 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 réalisée.
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 des appels vibrate (ancien style), l'autorisation VIBRATE est requise dans le fichier manifeste de l'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 :
- AndroidX
- Android
Toutes ces formes adoptent un motif de forme d'onde de base "on-off", 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 au toucher ?
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 aider le système à comprendre l'objectif de la vibration. Cette autorisation est requise 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 convient de 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 dispose d'un contrôle de l'amplitude, il peut émettre des vibrations d'intensité variable. 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é"/"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 d'un contrôle de l'amplitude.
Prise en charge des effets d'enveloppe
Les vibreurs 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.