Cette section présente les différentes API haptiques disponibles sur Android. Il explique également quand et comment vérifier la compatibilité des appareils pour vous assurer que vos effets haptiques sont diffusés comme vous le souhaitez.
Il existe plusieurs façons de créer des effets haptiques. Il est important de prendre en compte les principes de conception des retours haptiques Android lorsque vous choisissez parmi eux. Le tableau suivant récapitule ces attributs de haut niveau de chaque approche:
- La disponibilité est particulièrement importante lors de la planification du comportement de remplacement, et doit être combinée à la vérification de la compatibilité de chaque appareil.
- Les haptiques claires sont des sensations nettes et précises qui sont moins choquantes pour les utilisateurs.
- Les haptiques riches sont plus expressifs et nécessitent souvent du matériel plus riche en fonctionnalités.
| Surface d'API | Disponibilité | Retour haptique clair | Technologies haptiques avancées |
|---|---|---|---|
| HapticFeedbackConstants | Android 1.5 ou version ultérieure (par constante) |
||
| VibrationEffect prédéfini | Android 10 ou version ultérieure | ||
| Composition VibrationEffect | Android 11 ou version ultérieure (selon la constante) | ||
| Vibreur activé/désactivé, 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 s'affichent pour les notifications entrantes.
Cette page décrit également d'autres concepts qui couvrent les 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 compatible avec tous les appareils.
VibrationAttributes()vous aide à classer les vibrations en fonction de leur utilisation, en vous assurant que les paramètres utilisateur appropriés leur seront appliqués et en évitant ainsi les surprises pour l'utilisateur.
HapticFeedbackConstants
La classe HapticFeedbackConstants fournit des constantes basées sur les actions pour permettre aux applications d'ajouter un retour haptique cohérent sur l'ensemble de l'expérience sur l'appareil, au lieu que chaque application ait des effets différents pour les actions courantes.
Compatibilité et conditions requises
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 retour haptique sur la vue, y compris ceux par défaut.Le paramètre principal est la propriété View.hapticFeedbackEnabled, qui, si elle est définie sur false, désactive tous les appels de retour 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 les retours tactiles.
Le seul élément à prendre en compte pour la compatibilité est le niveau du SDK de la constante spécifique pour l'action.
Il n'est pas nécessaire de fournir un comportement de remplacement 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 conditions requises
La lecture de tout VibrationEffect nécessite 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éfinies, car les constantes qui ne disposent pas d'une 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 si une implémentation optimisée pour l'appareil est disponible.
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 tenir compte de l'optimisation de l'effet pour l'appareil ou non.
Les méthodes de vérification des effets peuvent renvoyer l'une des trois valeurs suivantes:
VIBRATION_EFFECT_SUPPORT_YESindique que l'appareil est compatible avec cet effet.VIBRATION_EFFECT_SUPPORT_NOindique que l'appareil n'est pas compatible de manière optimisée, mais qu'il utilise toujours le remplacement de la plate-forme.VIBRATION_EFFECT_SUPPORT_UNKNOWNindique que le système ne sait pas si l'implémentation est optimisée ou non.
Comme 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 pour aucun d'entre eux. Ces appareils utilisent une stratégie de remplacement dynamique.
Utilisation de VibrationEffect prédéfinis
Pour en savoir plus sur l'utilisation d'un VibrationEffect prédéfini, consultez la section Utiliser un VibrationEffect prédéfini pour générer un retour haptique.
Composition VibrationEffect
Une composition VibrationEffect est un effet de vibration créé à l'aide de l'API VibrationEffect.startComposition. Cette API permet d'utiliser des haptiques riches expressifs en créant une séquence de primitives avec des délais et des intensités personnalisés. Toutefois, veillez à vous assurer que l'appareil est compatible avec les fonctionnalités combinées pour éviter une expérience globale incohérente.
Compatibilité et conditions requises
La lecture de tout VibrationEffect nécessite 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 de composition. Il est important de s'assurer que les primitives sont disponibles.
Vérifier la prise en charge des primitives de vibration
La prise en charge 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 ensemble à l'aide de 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", "one-shot" et en forme de vague
La forme de vibration la plus ancienne compatible avec Android est des modèles de vibration simple "marche/arrêt" 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 haptiques bruyantes. Évitez-les sauf en dernier recours.
Le cas d'utilisation le plus courant des vibrations activées/désactivées est les notifications, où une vibration est toujours souhaitée. Les vibrations de forme d'onde permettent également de répéter un motif indéfiniment, comme vous pouvez l'imaginer pour une sonnerie.
Un modèle ponctuel consiste à vibrer une fois pendant N millisecondes.
Il existe deux types de formes d'onde:
- Codes temporels uniquement. Ce type de forme d'onde décrit des durées alternées de fonctionnement et d'arrêt. Les temps de début et de fin commencent par la durée pendant laquelle le vibreur est désactivé. Par conséquent, les modèles de forme d'onde commencent souvent par une valeur nulle pour indiquer que le vibreur doit commencer à vibrer immédiatement.
- Temps et amplitudes Ce type de forme d'onde comporte un tableau supplémentaire d'amplitudes à faire correspondre à chaque figure temporelle, plutôt que 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 prévue peut être obtenue.
Compatibilité et conditions requises
Comme les vibrations marche/arrêt sont la forme la plus ancienne de vibrations, elles sont compatibles avec la quasi-totalité des appareils avec vibreur, comme décrit plus loin sur cette page.
Pour lire des appels VibrationEffect ou vibrate plus anciens, vous devez disposer de l'autorisation VIBRATE 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 vous assurer que l'appareil est compatible avec la commande d'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 de l'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 examiner attentivement 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 "marche/arrêt"
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 notification
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 prennent un motif de forme d'onde marche/arrêt de base, comme décrit précédemment, où la première entrée correspond au délai avant d'allumer le vibreur.
Concepts généraux
Plusieurs concepts s'appliquent aux surfaces d'API décrites 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 vibreur, les appels aux API de vibration n'ont aucun effet. Les applications n'ont donc pas besoin de filtrer toutes leurs haptiques en fonction d'une condition. Toutefois, si nécessaire, une application peut appeler hasVibrator() pour déterminer s'il s'agit d'un vrai vibreur (true) ou d'un bouchon (false).
L'utilisateur a-t-il désactivé les retours haptiques tactiles ?
Certaines implémentations personnalisées peuvent nécessiter de vérifier manuellement si l'utilisateur a entièrement désactivé le paramètre Rétroaction tactile d'Android, auquel cas les effets de rétroaction tactile doivent être supprimés. Vous pouvez interroger ce paramètre à l'aide de la clé HAPTIC_FEEDBACK_ENABLED, où une valeur de zéro signifie "désactivé".
Attributs de vibration
Des attributs de vibration (actuellement sous la forme de AudioAttributes) peuvent être fournis pour aider le système à identifier l'objectif de la vibration. Cela est nécessaire lorsque vous déclenchez une vibration lorsque votre application est en arrière-plan, car seules les haptiques attentionnelles sont compatibles avec l'utilisation en arrière-plan.
La création de AudioAttributes est décrite dans la documentation de la classe. Elle doit être considérée comme une vibration plutôt qu'un son.
À titre indicatif, dans la plupart des cas, 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 aucun effet sur les vibrations.
Contrôle de l'amplitude
Si un vibreur est doté d'un contrôle de l'amplitude, il peut produire des vibrations d'intensités différentes. Il s'agit d'une fonctionnalité importante pour produire des haptiques riches, et potentiellement pour permettre à l'utilisateur de contrôler les intensités haptiques par défaut.
Pour vérifier la compatibilité avec le contrôle de l'amplitude, appelez Vibrator.hasAmplitudeControl. Si un vibreur n'est pas compatible avec l'amplitude, toutes les valeurs d'amplitude seront mappées sur "arrêt"/"marche" selon qu'elles sont égales à zéro ou non. Par conséquent, les applications qui utilisent 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.