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 및 Vibrator.areAllEffectsSupported API는 기기 최적화 구현이 있는지 확인하는 데 사용됩니다. 사전 정의된 효과는 최적화된 구현 없이도 계속 사용할 수 있으며 표준 플랫폼 대체를 사용합니다. 따라서 이러한 areEffectsSupported API는 애플리케이션에서 효과가 기기에 최적화되어 있는지 고려하려는 경우에만 필요합니다.

효과 확인 메서드는 다음 세 가지 값 중 하나를 반환할 수 있습니다.

UNKNOWN 값은 검사 API를 사용할 수 없음을 나타내므로 일반적으로 모든 효과 또는 그 중 아무것도 반환되지 않습니다. 이러한 기기는 동적으로 대체됩니다.

사전 정의된 VibrationEffect 사용

사전 정의된 VibrationEffect 사용에 관한 자세한 내용은 사전 정의된 VibrationEffect를 사용하여 햅틱 반응 생성을 참고하세요.

VibrationEffect 구성

VibrationEffect 컴포지션은 VibrationEffect.startComposition API를 사용하여 만든 진동 효과입니다. 이 API를 사용하면 맞춤 지연 시간과 강도로 프리미티브의 시퀀스를 만들어 표현력이 뛰어난 리치 햅틱을 구현할 수 있습니다. 그러나 전체 환경의 일관성을 유지하려면 기기가 결합되는 기능을 지원하는지 특히 주의하세요.

호환성 및 요구사항

VibrationEffect를 재생하려면 앱 매니페스트에 VIBRATE 권한이 필요합니다.

일부 기기는 컴포지션 API의 모든 기능을 지원하지 않으므로 원시 유형을 사용할 수 있는지 확인하는 것이 중요합니다.

진동 원시 유형 지원 확인

Vibrator.arePrimitivesSupported 메서드를 사용하여 원시별 지원을 가져올 수 있습니다. 또는 Vibrator.areAllPrimitivesSupported 메서드를 사용하여 일련의 프리미티브를 함께 확인할 수 있습니다. 이는 프리미티브별 지원을 AND하는 것과 같습니다.

VibrationEffect 컴포지션 사용

VibrationEffect 컴포지션 사용에 관한 자세한 내용은 진동 컴포지션 만들기를 참고하세요.

켜기/끄기, 원샷, 파형 진동

Android에서 지원되는 가장 오래된 형태의 진동은 구성 가능한 시간의 간단한 진동기 켜기/끄기 패턴입니다. 이러한 API는 일반적으로 잡음이 있는 햅틱을 생성할 수 있으므로 햅틱 디자인 원칙에 잘 부합하지 않습니다. 최후의 수단으로만 사용하세요.

켜기/끄기 진동의 가장 일반적인 사용 사례는 알림으로, 어떤 경우든 진동이 필요합니다. 파형 진동은 벨소리에서 상상할 수 있듯이 패턴을 무한대로 반복할 수 있는 고유한 기능도 있습니다.

원샷 패턴은 N밀리초 동안 한 번 진동하는 것을 의미합니다.

파형 패턴에는 두 가지 유형이 있습니다.

  • 타이밍만 표시됩니다. 이 유형의 웨이브폼은 꺼져 있는 시간과 켜져 있는 시간을 번갈아 설명하는 것입니다. 타이밍은 꺼져 있던 시간으로 시작합니다. 따라서 파형 패턴은 종종 0 값으로 시작하여 즉시 진동을 시작함을 나타냅니다.
  • 타이밍 및 진폭 이 유형의 파형에는 첫 번째 형식의 암시적 켜기/끄기 대신 각 타이밍 수치와 일치하는 추가 진폭 배열이 있습니다. 그러나 의도한 크기 조정을 실행할 수 있도록 기기가 진폭 제어를 지원하는지 확인하는 것이 중요합니다.

호환성 및 요구사항

켜기/끄기 진동은 가장 오래된 형태의 진동이므로 이 페이지 뒷부분에 설명된 대로 진동 모터가 있는 거의 모든 기기에서 지원됩니다.

VibrationEffect 또는 이전 스타일의 vibrate 호출을 재생하려면 앱 매니페스트에 VIBRATE 권한이 필요합니다.

파형에서 서로 다른 진폭 값을 사용할 때는 기기가 진폭 제어를 지원하는 것이 좋습니다.

진폭 제어 지원 확인

진폭 제어가 없는 기기에서는 0이 아닌 진폭 값이 100% 로 반올림되므로 Vibrator.hasAmplitudeControl를 사용하여 지원이 있는지 확인하는 것이 중요합니다. 자세한 내용은 진폭 제어를 참고하세요.

효과의 품질이 진폭 제어 없이도 충분한지 신중하게 고려해야 합니다. 명시적으로 설계된 켜기/끄기 진동으로 대체하는 것이 더 나을 수 있습니다.

켜기/끄기 진동 사용

최신 SDK 수준에서는 모든 진동 모드가 단일 표현형 VibrationEffect 클래스로 통합되었으며, 여기서 이러한 간단한 진동은 VibrationEffect.createOneshot 또는 VibrationEffect.createWaveform를 사용하여 생성됩니다.

Notification API

앱 알림을 맞춤설정할 때 다음 API 중 하나를 사용하여 각 알림 채널과 패턴을 연결할 수 있습니다.

이러한 모든 양식은 앞에서 설명한 대로 기본 켜기/끄기 웨이브폼 패턴을 사용합니다. 여기서 첫 번째 항목은 진동기를 켜기 전의 지연 시간입니다.

일반적인 개념

위에 설명된 API 노출 영역에는 여러 개념이 적용됩니다.

기기에 진동 모터가 있나요?

context.getSystemService(Vibrator.class)에서 null이 아닌 Vibrator 클래스를 가져올 수 있습니다. 기기에 진동기가 없는 경우 vibration API 호출은 아무런 영향을 미치지 않으므로 앱은 조건에 따라 모든 햅틱을 게이트할 필요가 없습니다. 그러나 필요한 경우 애플리케이션은 hasVibrator()를 호출하여 실제 진동기 (true)인지 스텁 (false)인지 확인할 수 있습니다.

사용자가 터치 햅틱을 사용 중지했나요?

일부 맞춤 구현에서는 사용자가 Android의 터치 반응 설정을 완전히 사용 중지했는지 수동으로 확인해야 할 수 있습니다. 이 경우 터치 반응 효과를 억제해야 합니다. 이 설정은 HAPTIC_FEEDBACK_ENABLED 키를 사용하여 쿼리할 수 있으며, 값이 0이면 사용 중지된 것을 의미합니다.

진동 속성

진동 속성 (현재 AudioAttributes 형식)을 제공하면 시스템에 진동의 목적을 알릴 수 있습니다. 앱이 백그라운드에 있을 때 진동을 시작할 때는 주의 햅틱만 백그라운드 사용에 지원되므로 이 작업이 필요합니다.

AudioAttributes 생성은 클래스 문서에서 다루며 소리가 아닌 진동으로 생각해야 합니다.

참고로 대부분의 경우 콘텐츠 유형은 CONTENT_TYPE_SONIFICATION이며 사용 값은 포그라운드의 터치 의견에 관한 USAGE_ASSISTANCE_SONIFICATION 또는 백그라운드의 알람에 관한 USAGE_ALARM과 같은 값일 수 있습니다. 오디오 플래그는 진동에 영향을 미치지 않습니다.

진폭 제어

진동기에 진폭 제어가 있으면 다양한 강도로 진동을 재생할 수 있습니다. 이는 리치 햅틱을 생성하는 데 중요한 기능이며, 기본 햅틱 강도를 사용자가 제어할 수 있도록 허용할 수도 있습니다.

진폭 제어 지원은 Vibrator.hasAmplitudeControl를 호출하여 확인할 수 있습니다. 진동기에 진폭 지원이 없는 경우 모든 진폭 값은 0인지 아닌지에 따라 꺼짐/켜짐에 매핑됩니다. 따라서 진폭이 다양한 풍부한 햅틱을 사용하는 애플리케이션은 기기에 진폭 제어가 없는 경우 이를 사용 중지하는 것이 좋습니다.