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

このドキュメントでは、Android で利用可能なさまざまなハプティクス API を紹介し、さまざまな触覚フィードバック効果の作成方法と、必要なデバイス サポートの確認方法について説明します。 keywords_public: > Android、ハプティクス、API、バイブレーション、HapticFeedbackConstants、VibrationEffect、エンベロープ ハプティクス、触覚フィードバック、通知、振幅制御

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

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

  • 可用性は、動作フォールバックを計画する際に特に重要であり、個々のデバイスのサポートを確認することと組み合わせる必要があります。
  • クリアなハプティクスは、ユーザーにとって不快感の少ない、鮮明でクリーンな感覚です。
  • リッチなハプティクスは表現力が優れており、多くの場合、より機能豊富なハードウェアが必要です。
API サーフェス 対象 クリア ハプティクス リッチ ハプティクス
HapticFeedbackConstants Android 1.5+
（定数ごと）
事前定義された VibrationEffect Android 10 以上
VibrationEffect 構成（推奨） Android 16+（26Q4）
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 は、開始強度を 0 に固定することでこれを強制し、終了強度が 0 でない場合は例外をスローします。この制約により、振幅の不連続性によって生じる振動の望ましくない動的効果を防ぎ、ユーザーの触覚認識に悪影響を及ぼす可能性を回避します。

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

波形エンベロープ作成ツール

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

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

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

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

Envelope VibrationEffect の使用

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

VibrationEffect 構成

Android 16（26Q4）以降では、VibrationEffect.Builder が、設計されたタイムラインに沿って複数のハプティクス要素をシーケンス処理することで、リッチで表現力豊かなハプティクス効果を構成するための推奨 API となります。タイムライン アンカー スケジューリング、アトミック カプセル化、混合イベントのサポート（プリセットとエンベロープの組み合わせ）、組み込みの自動フォールバックを提供することで、VibrationEffect.Composition を置き換えます。

構成要素

ビルダーでは、次の触覚要素を順序付けできます。

  • VibrationEffect.Preset: PRESET_CLICK、PRESET_TICK、PRESET_LOW_TICK などの一般的な短いパルスを表す、事前定義された触覚。プリセットは、VibrationEffect.Composition API の short プリミティブよりも優先されます。以前は rise や fall などのプリミティブで処理されていた、より長く連続的な効果やランプ効果には、代わりにエンベロープ（PWLE）を使用します。プリセットは、Preset.create(presetId, scale) を使用して 0.0f から 1.0f にスケーリングできます。
  • VibrationEffect.Envelope: BasicEnvelopeBuilder（強度とシャープネス）または WaveformEnvelopeBuilder（周波数と振幅）を使用して作成された区分的線形エンベロープ（PWLE）。エンベロープは Envelope.create(builder) を使用して構築されます。
  • VibrationEffect.Event: getEvents() を使用して既存の VibrationEffect から取得されたタイムライン イベント。これらは、addEvents(startTimeShiftMillis, events) を使用してタイムライン オフセットで追加できます。

タイムラインのスケジュール設定と検証

各要素は、コンポジションの開始からの時間オフセット（ミリ秒単位）を表す startTimeMillis とともにビルダーに追加されます。

  • ビルド時の検証: 要素は、開始時刻の厳密な昇順で追加する必要があります。ビルダーは、ビルド時間時に最小期間（プリセットの場合は 1 ミリ秒、エンベロープの場合は既知の期間など）に対してチェックすることで、ベスト エフォート検証を行います。ビルド時に重複が検出されると、IllegalArgumentException がスローされます。
  • 再生タイミングの調整: フレームワークは、再生中にベスト エフォートでタイミングのサポートを提供します。次のスケジュールされたイベントの開始時刻になっても前のイベントがまだ実行中の場合、フレームワークは後続のイベントを次に利用可能な最も早いスロットに自動的にシフトします。これにより、物理的な再生でイベントが重複することを防ぎ、ハプティクス イベントがドロップされないことが保証されます。

繰り返し効果

setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis) を使用して、繰り返し効果をコンポジションに追加できます。繰り返し効果を設定すると、ビルダーに要素を追加できなくなります。

代替のサポート

フレームワーク レベルの自動フォールバック サポートは、VibrationEffect.Builder によって作成されたバイブレーションに対してデフォルトで有効になっています。

  • 透過的なプラットフォーム フォールバック: デバイスがリクエストされた Preset または基本的な Envelope をサポートしていない場合、フレームワークは、サポートされていない要素を、実行時に適切なサポートされているバイブレーションにベスト エフォートで自動的に置き換えます。VibrationEffect.Builder でビルドされたコンポジションを再生する前に、アプリでデバイスの機能（isPresetSupported など）を手動で確認する必要はありません。
  • WaveformEnvelopeBuilder の例外: WaveformEnvelopeBuilder（ヘルツ単位の絶対物理周波数と G 単位の振幅を指定）によって作成されたエンベロープ効果には、自動フォールバック サポートがありません。高度な PWLE は特定のハードウェア周波数曲線（FOAM）に依存しているため、自動的に置き換えると設計意図が損なわれます。デバイスが PWLE 効果またはリクエストされた周波数をサポートしていない場合、そのようなバイブレーションは再生されません。普遍的な互換性を確保するには、BasicEnvelopeBuilder を優先します。

VibrationEffect.Builder の使用状況

VibrationEffect.Builder を使用してエフェクトを構成するコード例については、VibrationEffect.Builder を使用してタイムライン アンカー付きのコンポジションを作成するをご覧ください。

VibrationEffect プリミティブの構成

VibrationEffect プリミティブ コンポジションは、VibrationEffect.startComposition API を使用して作成されたバイブレーション効果です。この API を使用すると、プリミティブのシーケンスを作成できます。

互換性と要件

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

プリミティブのサポートを確認する

そのため、VibrationEffect.Composition API を使用する場合は、再生前に Vibrator.arePrimitivesSupported または Vibrator.areAllPrimitivesSupported を使用してプリミティブごとのサポートを確認する必要があります。

プリミティブごとのサポートは、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 を使用します。一致しない場合、エンベロープ ベースのバイブレーションは無視されます。