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 컴포지션 사용에 관한 자세한 내용은 진동 컴포지션 만들기를 참고하세요.

켜기, 1회, 파형 진동

Android에서 지원되는 가장 오래된 형태의 진동은 지속 시간을 구성할 수 있는 간단한 진동 켜기/끄기 패턴입니다. 이러한 API는 윙윙거리는 햅틱을 생성할 수 있으므로 일반적으로 햅틱 디자인 원칙과 잘 일치하지 않습니다. 최후의 수단으로 사용하는 것이 아니라면 사용하지 마세요.

켜기/끄기 진동의 가장 일반적인 사용 사례는 알림으로, 무엇이든 어느 정도의 진동이 필요합니다. 또한 파형 진동은 벨소리에 사용할 수 있는 것처럼 패턴이 무기한 반복되도록 허용합니다.

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

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

  • 타이밍만. 이 유형의 파형은 교대하는 시간과 쉬는 시간을 교대로 설명합니다. 타이밍은 꺼진 지속 시간과 함께 시작됩니다. 따라서 파형 패턴은 종종 진동이 즉시 시작됨을 나타내기 위해 0 값으로 시작합니다.
  • 타이밍 및 진폭. 이 유형의 파형에는 첫 번째 형식의 암시적 on/off가 아닌 각 타이밍 수치와 일치하는 추가 진폭 배열이 있습니다. 그러나 의도한 확장을 달성할 수 있도록 기기가 진폭 제어를 지원하는지 확인하는 것이 중요합니다.

호환성 및 요구사항

켜짐-꺼짐 진동은 가장 오래된 형태의 진동이므로 이 페이지의 뒷부분에서 설명하는 것처럼 진동기가 있는 거의 모든 기기에서 지원됩니다.

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

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

진폭 제어 지원 확인

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

진폭 제어 없이도 효과가 충분한 품질을 갖는지 신중하게 고려해야 합니다. 명시적으로 설계된 켜짐 꺼짐 진동으로 되돌아가는 것이 더 나을 수 있습니다.

켜기/끄기 진동 사용

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

알림 API

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

이러한 모든 형식은 앞서 설명한 것처럼 기본적인 on-off 파형 패턴을 사용합니다. 여기서 첫 번째 항목은 진동을 켜기 전의 지연입니다.

일반적인 개념

위에서 설명한 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이 아닌지에 따라 off/on에 매핑됩니다. 따라서 다양한 진폭의 리치 햅틱을 사용하는 애플리케이션은 기기에 진폭 제어가 없는 경우 햅틱을 사용 중지하는 것을 고려해야 합니다.