Android ハプティクス API リファレンス

このセクションでは、Android で利用可能なさまざまなハプティクス API について説明します。また、触覚効果が意図したとおりに再生されるようにするために必要なデバイスのサポートを確認するタイミングと方法についても説明します。

ハプティクス エフェクトを作成するにはいくつかの方法がありますが、その中から選択する際には、Android ハプティクスの設計原則を検討することが重要です。次の表に、各アプローチの概要を示します。

  • 可用性は、動作のフォールバック計画において特に重要であり、個々のデバイスのサポートの確認と組み合わせる必要があります。
  • クリア ハプティクスは、ユーザーに違和感を与えない、鮮明でクリーンな感覚です。
  • リッチ ハプティクスは表現力が高く、多くの場合、より機能豊富なハードウェアが必要です。
API サーフェス 対象 クリア ハプティクス リッチ ハプティクス
HapticFeedbackConstants Android 1.5 以降
（定数ごと）
事前定義された VibrationEffect Android 10 以上
VibrationEffect の合成 Android 11 以降（定数ごと）
オン/オフ、ワンショット、波形のバイブレーション Android 1

また、このページで説明する通知 API を使用すると、受信した通知で再生されるハプティクス エフェクトをカスタマイズできます。

このページでは、API サーフェスにまたがる追加のコンセプトについても説明します。

  • デバイスにバイブレーション機能はありますか？
  • 振幅制御を使用すると、よりスムーズで豊かなハプティクス エフェクトを実現できますが、すべてのデバイスでサポートされているわけではありません。
  • VibrationAttributes() を使用すると、振動の使用状況に基づいて振動を分類できます。これにより、適切なユーザー設定が振動に適用され、ユーザーに不意の振動が発生するのを防ぐことができます。

HapticFeedbackConstants

HapticFeedbackConstants クラスは、アクションベースの定数を提供します。これにより、アプリは、共通のアクションに対して各アプリで異なる効果を設定することなく、デバイス全体で一貫した触覚フィードバックを追加できます。

互換性と要件

これらの定数で View.performHapticFeedback メソッドを使用する場合、アプリに特別な権限は必要ありません。View.hapticFeedbackEnabled プロパティが適用されます。このプロパティを false に設定すると、デフォルトのものを含む、ビューでのハプティクス フィードバックの呼び出しがすべて無効になります。主な関連設定は View.hapticFeedbackEnabled プロパティです。このプロパティを false に設定すると、デフォルトのものを含む、ビューでのハプティクス フィードバックの呼び出しがすべて無効になります。また、このメソッドは、タップ フィードバックを有効にするユーザーのシステム設定も尊重します。

互換性に関する唯一の考慮事項は、アクションの特定の定数の SDK レベルです。

HapticFeedbackConstants を使用する場合は、代替動作を指定する必要はありません。

HapticsFeedbackConstants の使用

HapticFeedbackConstants の使用方法については、イベントにハプティクス フィードバックを追加するをご覧ください。

事前定義された VibrationEffect

VibrationEffect クラスには、CLICK、TICK、DOUBLE_CLICK などの事前定義された定数がいくつか用意されています。これらの効果はデバイス用に最適化されている場合があります。

互換性と要件

VibrationEffect を再生するには、アプリ マニフェストで VIBRATE 権限が必要です。

デバイスに最適化された実装がない定数は標準のプラットフォーム フォールバックに戻るため、事前定義された VibrationEffect を使用する場合はフォールバック動作を指定する必要はありません。

Vibrator.areEffectsSupported API と Vibrator.areAllEffectsSupported API は、デバイス向けに最適化された実装があるかどうかを判断するためのものです。事前定義されたエフェクトは、最適化された実装なしで使用でき、標準のプラットフォーム フォールバックを使用します。したがって、これらの areEffectsSupported API は、アプリでエフェクトがデバイス用に最適化されているかどうかを考慮する場合にのみ必要です。

効果チェック メソッドは、次の 3 つの値のいずれかを返します。

  • VIBRATION_EFFECT_SUPPORT_YES は、デバイスがこのエフェクトのサポートを最適化していることを示します。
  • VIBRATION_EFFECT_SUPPORT_NO は、デバイスが最適化されたサポートを備えていないが、プラットフォームのフォールバックを使用していることを示します。
  • VIBRATION_EFFECT_SUPPORT_UNKNOWN は、実装が最適化されているかどうかがシステムで不明であることを示します。

UNKNOWN 値は、チェック対象の API が使用できないことを示します。通常、この値はすべてのエフェクトに対して返されます。これらのデバイスは動的にフォールバックします。

事前定義された VibrationEffect の使用

事前定義された VibrationEffect の使用方法については、事前定義された VibrationEffect を使用してハプティクス フィードバックを生成するをご覧ください。

VibrationEffect の構成

VibrationEffect コンポジションは、VibrationEffect.startComposition API を使用して作成されたバイブレーション効果です。この API を使用すると、カスタマイズされた遅延と強度を持つプリミティブのシーケンスを作成することで、表現力豊かなリッチ ハプティクスを実現できます。ただし、全体的なエクスペリエンスの不整合を避けるため、組み合わせる機能がデバイスでサポートされていることを特に注意してください。

互換性と要件

VibrationEffect を再生するには、アプリ マニフェストで VIBRATE 権限が必要です。

すべてのデバイスが Composition API のすべての機能をサポートしているわけではありません。プリミティブが使用可能であることを確認することが重要です。

バイブレーション プリミティブのサポートを確認する

プリミティブごとのサポートは、Vibrator.arePrimitivesSupported メソッドを使用して取得できます。または、Vibrator.areAllPrimitivesSupported メソッドを使用して、プリミティブのセットをまとめてチェックすることもできます。これは、プリミティブごとのサポートを AND すると同じです。

VibrationEffect コンポジションの使用

VibrationEffect コンポジションの使用方法については、バイブレーション コンポジションを作成するをご覧ください。

オン / オフ、ワンショット、波形のバイブレーション

Android でサポートされている最も古いバイブレーションは、構成可能な時間のシンプルなバイブレーションのオン / オフ パターンです。これらの API は、バズ音の触覚を生成できるため、通常は触覚設計の原則に沿っていません。最後の手段として使用する以外は使用しないでください。

オン / オフのバイブレーションの最も一般的なユースケースは通知です。通知では、どのような場合でもバイブレーションが必要な場合があります。波形バイブレーションでは、着信音のようにパターンを無限に繰り返すこともできます。

ワンショット パターンは、1 回振動して N ミリ秒間振動することを指します。

波形パターンには次の 2 種類があります。

  • タイミングのみ。このタイプの波形は、オフとオンの時間を交互に表します。タイミングはオフの状態の時間が最初に設定されます。そのため、振動をすぐに開始することを示すために、波形パターンは多くの場合 0 値から始まります。
  • タイミングと振幅。このタイプの波形には、最初の形式の暗黙的なオン / オフではなく、各タイミング数値に一致する振幅の追加配列があります。ただし、目的のスケーリングが実現できるように、デバイスが振幅制御をサポートしていることを確認することが重要です。

互換性と要件

オン / オフの振動は最も古い振動形式であるため、このページの後半で説明するように、バイブレーション機能を備えたほぼすべてのデバイスでサポートされています。

VibrationEffect または古いスタイルの vibrate 呼び出しを再生するには、アプリ マニフェストで VIBRATE 権限が必要です。

波形で異なる振幅値を使用する場合は、デバイスが振幅制御をサポートしていることを強くおすすめします。

振幅制御のサポートを確認する

振幅制御のないデバイスでは、振幅値が 0 以外の場合、100% に切り上げられます。そのため、Vibrator.hasAmplitudeControl を使用してサポートされているかどうかを確認することが重要です。詳しくは、振幅制御をご覧ください。

振幅を制御せずにエフェクトの品質が十分かどうかを慎重に検討する必要があります。明示的に設計されたオン / オフの振動にフォールバックすることをおすすめします。

オン / オフ バイブレーションの使用

新しい SDK レベルでは、すべてのバイブレーション モードが単一の表現力豊かな VibrationEffect クラスに統合されました。ここでは、これらの単純なバイブレーションは VibrationEffect.createOneshot または VibrationEffect.createWaveform を使用して作成されます。

Notification API

アプリの通知をカスタマイズする場合は、次のいずれかの API を使用して、各通知チャンネルにパターンを関連付けることができます。

これらの形式はすべて、前述のように基本的なオン / オフの波形パターンを採用しています。最初のエントリは、バイブレーターをオンにするまでの遅延時間です。

一般的なコンセプト

上記の API サーフェス全体に適用されるコンセプトがいくつかあります。

デバイスにバイブレーション機能はありますか？

context.getSystemService(Vibrator.class) から null 以外の Vibrator クラスを取得できます。デバイスにバイブレーターがない場合、バイブレーション API の呼び出しは効果がないため、アプリは条件に基づいてすべてのハプティクスを制限する必要はありません。ただし、必要に応じて、アプリケーションは hasVibrator() を呼び出して、これが実際のバイブレーター（true）かスタブ（false）かを判断できます。

タップ ハプティクスがオフになっているか

一部のカスタム実装では、ユーザーが Android の [タップ フィードバック] 設定を完全に無効にしているかどうかを手動で確認する必要があります。この場合、タップ フィードバックの効果を抑制する必要があります。この設定は HAPTIC_FEEDBACK_ENABLED キーを使用してクエリできます。値が 0 の場合、無効になります。

バイブレーションの属性

バイブレーションの目的をシステムに通知するために、バイブレーション属性（現在は AudioAttributes の形式）を指定できます。バックグラウンドでの使用では注意喚起ハプティクスのみがサポートされているため、アプリがバックグラウンドにあるときにバイブレーションを開始する場合は、これが必要になります。

AudioAttributes の作成については、クラスのドキュメントをご覧ください。これは音ではなく振動と考えてください。

ガイドとして、ほとんどの場合、コンテンツ タイプは CONTENT_TYPE_SONIFICATION であり、使用方法は、フォアグラウンドのタップ フィードバックの場合は USAGE_ASSISTANCE_SONIFICATION、バックグラウンドのアラームの場合は USAGE_ALARM などの値になります。音声フラグはバイブレーションには影響しません。

振幅の制御

バイブレーションに振幅コントロールがある場合、振動の強さを変更できます。これは、豊かな触覚を生成するための重要な機能であり、デフォルトの触覚強度をユーザーが制御できるようにする可能性もあります。

振幅制御のサポートを確認するには、Vibrator.hasAmplitudeControl を呼び出します。バイブレータが振幅をサポートしていない場合、すべての振幅値は、ゼロかどうかに基づいてオフまたはオンにマッピングされます。したがって、振幅が変化するリッチ ハプティクスを使用するアプリは、デバイスに振幅制御がない場合は、無効にすることを検討してください。