Android 햅틱 API 참조

이 섹션에서는 Android에서 사용할 수 있는 다양한 햅틱 API를 소개합니다. 또한 햅틱 효과가 의도한 대로 재생되도록 필요한 기기 지원을 언제 어떻게 확인해야 하는지도 설명합니다.

촉각 효과를 만드는 방법은 여러 가지가 있으며, 이러한 방법 중에서 선택할 때는 Android 햅틱 설계 원칙을 고려해야 합니다. 다음 표에는 각 접근 방식의 대략적인 속성이 요약되어 있습니다.

  • 사용 가능 여부는 동작 대체를 계획할 때 특히 중요하며 개별 기기 지원을 확인하는 것과 결합해야 합니다.
  • 선명한 햅틱은 사용자에게 덜 충격적인 선명하고 깔끔한 감각입니다.
  • 풍부한 햅틱은 표현력이 더 뛰어나며 기능이 풍부한 하드웨어가 필요한 경우가 많습니다.
API 노출 영역 사용 가능 여부 명확한 햅틱 리치 햅틱
HapticFeedbackConstants Android 1.5 이상
(상수별)
사전 정의된 VibrationEffect Android 10+
VibrationEffect Composition 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를 사용하여 햅틱 피드백 생성을 참고하세요.

Envelope VibrationEffect

엔벨로프 기반 진동을 사용하면 제어점 시퀀스를 정의하여 시간 경과에 따른 진동의 진폭과 주파수를 정확하게 제어할 수 있습니다. 이를 통해 개발자는 더 풍부하고 미묘한 햅틱 피드백 환경을 만들 수 있습니다. 이러한 진동은 BasicEnvelopeBuilder 및 WaveformEnvelopeBuilder 클래스를 사용하여 만들 수 있습니다.

호환성 및 요구사항

진동 효과를 재생하려면 앱이 앱 매니페스트에서 VIBRATE 권한을 선언해야 합니다.

엔벨로프 효과 지원 여부를 확인하려면 Vibrator.areEnvelopeEffectsSupported()을 호출하세요.

기본 봉투 빌더

원활하고 매끄러운 햅틱 환경을 만들려면 엔벨로프 효과가 \( 0.0 \)강도로 시작하고 끝나야 합니다. API는 시작 강도를 0으로 고정하여 이를 적용하고 종료 강도가 0이 아니면 예외를 발생시킵니다. 이 제약 조건은 진폭의 불연속으로 인해 진동에서 바람직하지 않은 동적 효과가 발생하는 것을 방지하여 사용자의 햅틱 인식에 부정적인 영향을 미칠 수 있습니다.

기기 간에 일관된 엔벨로프 효과 렌더링을 제공하기 위해 프레임워크에서는 이 기능을 지원하는 기기가 제어점 간 최소 20ms의 지속 시간과 엔벨로프 효과를 위한 최소 16개의 포인트를 처리할 수 있어야 합니다.

파형 엔벨로프 빌더

프레임워크는 개발자가 제공한 요청된 주파수 및 진폭 값을 수정하지 않습니다. 하지만 API는 부드러운 전환을 만들기 위해 시작 진폭을 0으로 고정합니다.

앱의 파형 엔벨로프 효과를 최적화하고 기기 간 호환성을 제공할 수 있도록 Android에서는 중요한 기기 기능을 쿼리하는 API를 제공합니다. 이러한 메서드는 제어점 간 최대 및 최소 전환 지속 시간, 단일 효과에 지원되는 최대 제어점 수와 같은 기기의 제한사항에 관한 정보를 제공합니다.

getMaxSize()
엔벨로프 효과에 지원되는 최대 제어점을 가져옵니다.
getMinControlPointDurationMillis()
엔벨로프 효과 내 두 제어점 사이에서 지원되는 최소 지속 시간을 밀리초 단위로 가져옵니다.
getMaxControlPointDurationMillis()
엔벨로프 효과 내 두 제어점 사이에서 지원되는 최대 지속 시간을 밀리초 단위로 가져옵니다.
getMaxDurationMillis()
봉투 효과에 지원되는 최대 지속 시간을 밀리초 단위로 가져옵니다.

효과가 너무 많은 제어 지점을 허용하거나 최대값을 초과하는 지속 시간과 같이 기기의 제한을 초과하는 경우 프레임워크는 허용된 경계 내에 맞도록 효과를 자동으로 조정합니다. 이 조정 프로세스는 디자인의 원래 의도와 느낌을 최대한 보존하려고 합니다.

봉투 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를 사용하여 생성됩니다.

알림 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을 호출하여 확인할 수 있습니다. 진동기에 진폭 지원이 없는 경우 모든 진폭 값은 0인지 0이 아닌지에 따라 꺼짐/켜짐에 매핑됩니다. 따라서 진폭이 다양한 풍부한 햅틱을 사용하는 애플리케이션은 기기에 진폭 제어가 없는 경우 이를 사용 중지하는 것을 고려해야 합니다.

엔벨로프 효과 지원

엔벨로프 효과가 있는 진동기는 더 역동적이고 미묘한 진동을 생성할 수 있도록 지원하고 이를 가능하게 하여 강도와 선명도를 더 정밀하게 제어하여 더 풍부한 햅틱 경험을 제공합니다. Vibration.areEnvelopeEffectsSupported를 사용하여 기기에서 이 기능을 지원하는지 확인합니다. 그렇지 않으면 엔벨로프 기반 진동이 무시됩니다.