Android 햅틱 API 참조

이 섹션에서는 Android에서 사용할 수 있는 다양한 햅틱 API를 소개합니다. 또한 햅틱 효과가 의도한 대로 재생되도록 하는 데 필요한 기기 지원을 확인하는 시기와 방법을 다룹니다.

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

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

Envelope VibrationEffect

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

호환성 및 요구사항

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

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

기본 봉투 빌더

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

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

파형 엔벨로프 빌더

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

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

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

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

Envelope VibrationEffects 사용

봉투 파형 효과를 만드는 방법에 관한 자세한 내용은 봉투로 진동 파형 만들기를 참고하세요.

VibrationEffect 구성

Android 16 (26Q4)부터 VibrationEffect.Builder는 설계된 타임라인을 따라 여러 햅틱 요소를 시퀀싱하여 풍부하고 표현력이 뛰어난 햅틱 효과를 구성하는 데 선호되는 API입니다. 타임라인 고정 예약, 원자성 캡슐화, 혼합 이벤트 지원(사전 설정과 봉투 결합), 내장 자동 대체 기능을 제공하여 VibrationEffect.Composition를 대체합니다.

빌딩 블록

빌더를 사용하면 다음 햅틱 요소를 순서대로 지정할 수 있습니다.

  • VibrationEffect.Preset: PRESET_CLICK, PRESET_TICK, PRESET_LOW_TICK과 같은 일반적인 짧은 진동을 나타내는 사전 정의된 햅틱 감각입니다. 사전 설정은 VibrationEffect.Composition API의 짧은 기본 요소를 대체합니다. 이전에는 상승, 하강 및 기타 기본 요소로 처리되었던 길고 연속적이거나 램핑 효과의 경우 대신 엔벨로프(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와 함께 빌더에 추가됩니다.

  • 빌드 시간 검증: 요소는 시작 시간의 엄격한 증가 순서로 추가해야 합니다. 빌더는 최소 지속 시간 (예: 프리셋의 경우 1ms 또는 엔벨로프의 알려진 지속 시간)을 확인하여 빌드 시간에 최선을 다해 검증합니다. 빌드 시간에 중복이 감지되면 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는 buzzy 햅틱을 생성할 수 있으므로 일반적으로 햅틱 설계 원칙과 잘 맞지 않습니다. 최후의 수단이 아닌 한 사용하지 마세요.

켜기/끄기 진동의 가장 일반적인 사용 사례는 알림입니다. 알림에서는 어떤 경우에도 진동이 필요합니다. 파형 진동은 벨소리에서 예상할 수 있듯이 패턴이 무한히 반복되도록 고유하게 허용합니다.

원샷 패턴은 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를 사용하여 기기에서 이 기능을 지원하는지 확인합니다. 그렇지 않으면 엔벨로프 기반 진동이 무시됩니다.