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

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

触覚効果の作成にはいくつかの方法があり、それらの中から選択する際には、Android の触覚に関する設計原則を考慮することが重要です。次の表に、各アプローチの概要をまとめます。

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

また、このページで説明する通知 API を使用すると、着信通知で再生される触覚効果をカスタマイズできます。

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

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 を使用して触覚フィードバックを生成するをご覧ください。

Envelope VibrationEffect

エンベロープ ベースのバイブレーションでは、一連のコントロール ポイントを定義することで、バイブレーションの振幅と周波数を時間経過とともに正確に制御できます。これにより、デベロッパーはよりリッチでニュアンスのある触覚フィードバック エクスペリエンスを作成できます。これらのバイブレーションは、BasicEnvelopeBuilder クラスと WaveformEnvelopeBuilder クラスを使用して作成できます。

互換性と要件

バイブレーション効果を再生するには、アプリのマニフェストで VIBRATE 権限を宣言する必要があります。

エンベロープ効果のサポートを確認するには、Vibrator.areEnvelopeEffectsSupported() を呼び出します。

Basic Envelope Builder

スムーズでシームレスな触覚エクスペリエンスを実現するには、エンベロープ効果を強度 \( 0.0 \)で開始し、終了する必要があります。API は、開始強度をゼロに固定し、終了強度がゼロでない場合は例外をスローすることで、これを強制します。この制約により、振幅の不連続性によって生じる振動の望ましくない動的効果を防ぎ、ユーザーの触覚認識に悪影響を与えないようにします。

デバイス間でエンベロープ効果のレンダリングを統一するため、この機能をサポートするデバイスは、制御点間の最小期間が 20 ミリ秒、エンベロープ効果のポイントが 16 個以上を処理できることがフレームワークで求められています。

波形エンベロープ ビルダー

フレームワークは、デベロッパーが指定したリクエストされた周波数と振幅の値を変更しません。ただし、API は開始振幅をゼロに固定して、スムーズな移行も作成します。

アプリの波形エンベロープ効果を最適化し、デバイス間の互換性を提供するために、Android は重要なデバイス機能をクエリするための API を提供しています。これらのメソッドは、デバイスの制限に関する情報（コントロール ポイント間の最大および最小の移行時間、1 つのエフェクトでサポートされるコントロール ポイントの最大数など）を提供します。

getMaxSize()
エンベロープ効果でサポートされているコントロール ポイントの最大数を取得します。
getMinControlPointDurationMillis()
エンベロープ効果内の 2 つのコントロール ポイント間の最小期間（ミリ秒単位）を取得します。
getMaxControlPointDurationMillis()
エンベロープ効果内の 2 つのコントロール ポイント間でサポートされる最大期間（ミリ秒単位）を取得します。
getMaxDurationMillis()
エンベロープ効果でサポートされている最大期間をミリ秒単位で取得します。

効果がデバイスの制限を超える場合（制御点の数が多すぎる、期間が最大値を超えるなど）、フレームワークは効果を自動的に調整して、許容範囲内に収めます。この調整プロセスでは、デザインの元の意図と雰囲気を可能な限り維持しようとします。

Envelope VibrationEffect の使用

エンベロープ波形効果の作成の詳細については、エンベロープでバイブレーション波形を作成するをご覧ください。

VibrationEffect 構成

VibrationEffect 構成は、VibrationEffect.startComposition API を使用して作成されたバイブレーション効果です。この API を使用すると、カスタマイズされた遅延と強度のプリミティブのシーケンスを作成して、表現力豊かなリッチな触覚を実現できます。ただし、デバイスが組み合わせる機能をサポートしていることを確認し、全体的なエクスペリエンスに一貫性がない状態にならないように注意してください。

互換性と要件

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

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

エンベロープ効果のサポート

エンベロープ効果のあるバイブレーターをサポートし、よりダイナミックでニュアンスのあるバイブレーションを作成できるようにします。これにより、強度とシャープさをより正確に制御して、より豊かな触覚体験を提供できます。Vibration.areEnvelopeEffectsSupported を使用して、デバイスがこの機能をサポートしているかどうかを判断します。そうでない場合、エンベロープ ベースのバイブレーションは無視されます。