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 は耳障りなハプティクスを生成する可能性があるため、ハプティクス設計の原則に沿っていません。最後の手段として、使用しないようにしてください。

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

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

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

  • タイミングのみ。このタイプの波形は、経過時間と経過時間を交互に記述したものです。タイミングはオフの時間から始まります。そのため、多くの場合、波形パターンはすぐに振動し始めることを示すゼロ値で始まります。
  • タイミングと振幅。このタイプの波形には、最初の形式が暗黙的にオン / オフするのではなく、各タイミング値に対応する振幅の配列が追加されています。ただし、目的のスケーリングが実現されるように、デバイスが振幅制御をサポートしているかどうかを確認することが重要です。

互換性と要件

オン / オフ バイブレーションは最も古いバイブレーション形式であるため、このページで後述するように、バイブレーションが備わっているほぼすべてのデバイスでサポートされています。

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

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

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

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

効果が振幅制御なしで十分な品質を備えているかどうかを慎重に検討する必要があります。明示的に設計されたオンオフ バイブレーションに戻すことをおすすめします。

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

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

通知 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 を呼び出して確認できます。バイブレーターが振幅をサポートしていない場合、すべての振幅値は、ゼロかゼロでないかに基づいてオフ / オンにマッピングされます。そのため、振幅が変動するリッチ ハプティクスを使用するアプリでは、デバイスに振幅制御がない場合には、ハプティクスの無効化を検討する必要があります。