패키지, 저장소 및 앱 카테고리 검색

패키지 상세v0.8.0

haptic_feedback

하프틱 피드백을 위한 플러터 플러그인입니다. 표준 iOS 하프틱을 사용하지만, 안드로이드에서도 동일한 하프틱 패턴을 에뮬레이션하여 플랫폼 간 일관된 경험을 제공하고자 합니다.

AndroidiOS
30일 다운로드
4.8만
좋아요
136
Pub 점수
160

패키지 설치

flutter pub add haptic_feedback

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

haptic_feedback 패키지는 Flutter 애플리케이션에서 안드로이드 및 iOS 플랫폼 간에 일관된 햅틱 피드백을 제공합니다. 원격 iOS 햅틱 기능을 활용하면서 안드로이드에서는 유사한 패턴을 시뮬레이션하여 통합된 사용자 경험을 보장합니다. 앱에서 촉각 반응을 원하는 개발자를 위해 설계되었으며, 충격, 알림, 선택과 같은 표준 햅틱 패턴을 지원합니다. 가볍고 쉽게 통합할 수 있어 모바일 앱의 상호작용 피드백을 강화하기에 이상적입니다.

사용 사례

  • 촉각 피드백을 통한 터치 상호작용 개선
  • 물리적 신호를 통한 접근성 향상
  • 게임 앱에서 반응형 피드백 추가하기
  • 몰입형 사용자 경험 만들기
  • 제스처 기반 탐색 지원
  • 작업에 대한 확인 피드백 제공

주요 기능

  • 다중 플랫폼 햅틱 일관성
  • 안드로이드에서 iOS 햅틱 에뮬레이션
  • 일반적인 햅틱 패턴을 위한 간단한 API
  • 경량이고 효율적
  • 영향, 알림 및 선택 유형을 지원합니다
  • Flutter pub를 통한 간편한 통합

적합한 대상

  • Android 및 iOS 양쪽을 대상으로 하는 모바일 앱 개발자
  • 접근성 중심의 애플리케이션 설계
  • 촉각 반응이 필요한 인터랙티브 UI 컴포넌트
  • 게임화 또는 제스처 기반 인터페이스
  • 사용자 피드백이 사용성 향상에 기여하는 앱

고려 사항

  • 기본 햅틱 패턴으로 제한됨
  • Android 에뮬레이션은 기기마다 다를 수 있습니다
  • 모든 기기에서 고급 햅틱을 지원하지 않습니다
  • 플랫폼별 권한이 필요합니다
  • 플랫폼 간에 동작이 약간 다릅니다
  • 완전한 효과를 위해서는 하드웨어 기능에 의존합니다

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

haptic_feedback

A haptic feedback plugin for both iOS and Android.

While it utilizes standard iOS haptics, it aims to emulate these same haptic patterns on Android for a consistent experience across platforms.

For a guide on when to use each haptic type, see Missing haptic types, and which to use when by Kamran.

Getting Started

1. Add the dependency
flutter pub add haptic_feedback
2. Use the plugin
final canVibrate = await Haptics.canVibrate();

await Haptics.vibrate(HapticsType.success);
await Haptics.vibrate(HapticsType.warning);
await Haptics.vibrate(HapticsType.error);

await Haptics.vibrate(HapticsType.light);
await Haptics.vibrate(HapticsType.medium);
await Haptics.vibrate(HapticsType.heavy);

await Haptics.vibrate(HapticsType.rigid);
await Haptics.vibrate(HapticsType.soft);

await Haptics.vibrate(HapticsType.selection);

If you want to be defensive, you can wrap calls in a try/catch to handle a PlatformException. Native exceptions are caught and returned as PlatformException (code: VIBRATION_ERROR) so they won't crash your app, but you can log or react if needed:

try {
  await Haptics.vibrate(HapticsType.success);
} on PlatformException catch (e) {
  // Handle or log as needed
}

Android-specific options

// Use native Android haptic constants (default: false)
// When true, uses HapticFeedbackConstants like CONFIRM, REJECT, etc.
// When false, uses custom vibration primitives that are more aligned
// with iOS haptics
await Haptics.vibrate(
  HapticsType.success,
  useAndroidHapticConstants: false,  // default
);

// On Android 13+, you can hint how the system should treat this vibration
// (alarm, communicationRequest, hardwareFeedback, media, notification, physicalEmulation, ringtone, touch, unknown)
await Haptics.vibrate(
  HapticsType.success,
  usage: HapticsUsage.media,
);

The optional usage parameter is a hint for the system. It can influence how the vibration is routed and which volume / haptics settings control it (for example, notification vs touch feedback).

Use a concrete value whenever the vibration clearly matches one of the defined categories (for example HapticsUsage.notification for reminders or status updates), and keep the default HapticsUsage.unknown for simple taps and other lightweight UI feedback.

iOS: SwiftPM vs CocoaPods

Flutter can consume this plugin via Swift Package Manager (SPM) or CocoaPods. SPM support in Flutter is still experimental:

  1. To enable SPM (Flutter 3.24+): flutter config --enable-swift-package-manager or add to pubspec.yaml:

    flutter:
      config:
        enable-swift-package-manager: true
    

    If you hit Xcode build issues after switching, do a one-time clean: flutter clean and remove Xcode DerivedData for this app (e.g., rm -rf ~/Library/Developer/Xcode/DerivedData/Runner-*), then rebuild.

  2. To stick with CocoaPods (or if you hit SPM issues): disable SPM with flutter config --no-enable-swift-package-manager or by adding to pubspec.yaml:

    flutter:
      config:
        enable-swift-package-manager: false
    

The plugin still supports CocoaPods; SPM is available for native iOS apps and newer Flutter toolchains.

Platform Implementation

iOS

Uses Apple's native haptic feedback APIs:

  • UINotificationFeedbackGenerator for success, warning, and error
  • UIImpactFeedbackGenerator for light, medium, heavy, rigid, and soft
  • UISelectionFeedbackGenerator for selection
Android

On Android, the plugin defaults to high-fidelity haptic primitives on API 30+ (great on devices with advanced/HD hardware); falls back to waveforms on API 26-29 and legacy timing-only vibration on older SDKs; and can opt into system HapticFeedbackConstants via useAndroidHapticConstants on supported SDKs. The plugin uses a multi-strategy approach for the best possible haptic experience:

Strategy 1: Native HapticFeedbackConstants (when enabled)

When useAndroidHapticConstants: true, the plugin uses Android's system-level haptic constants via View.performHapticFeedback():

Type Android Constant API Level
success CONFIRM ≥ 30
error REJECT ≥ 30
light VIRTUAL_KEY ≥ 5
medium KEYBOARD_PRESS (≥ 27) / KEYBOARD_TAP (≥ 8) ≥ 8
heavy CONTEXT_CLICK ≥ 23
selection CLOCK_TICK ≥ 21

Note: warning, rigid, and soft don't have direct Android mappings and fall back to primitives/waveforms/legacy.

Strategy 2: Haptic Primitives (API 30+)

When native constants aren't available or useAndroidHapticConstants: false (default), the plugin uses VibrationEffect.Composition, which is tuned to resemble the iOS patterns:

Type Primitive(s) Description
success CLICK × 2 Two clicks with increasing intensity
warning CLICK × 2 Two clicks with decreasing intensity
error CLICK × 4 Four clicks with an accented third pulse
light TICK Subtle, light feedback
medium CLICK Moderate feedback
heavy THUD Strong, deep feedback
rigid CLICK Sharp, crisp feedback
soft SPIN* Gentle, longer feedback
selection TICK Subtle selection feedback

* SPIN requires API 31+; falls back to TICK on API 30.

Strategy 3: Waveform Vibrations (API 26-29)

For devices without primitive support, the plugin uses VibrationEffect.createWaveform() with amplitude control.

Strategy 4: Legacy Vibration (API < 26)

Basic timing-only patterns for older devices.

For detailed timing specifications and implementation rationale, see HAPTIC_PATTERNS.md.

Testing

When testing widgets that use haptic feedback, defaultTargetPlatform is TargetPlatform.android by default, but the default platform implementation still calls the method channel and will throw MissingPluginException unless you register a mock. If you swap in a mock platform that returns true, Haptics.canVibrate() will return true even on a non-mobile host unless you override the target platform.

To test widgets that use haptic feedback, you can:

  1. Use debugDefaultTargetPlatformOverride to test platform-specific behavior:
import 'package:flutter/foundation.dart';

void main() {
  testWidgets('test on iOS', (tester) async {
    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
    addTearDown(() => debugDefaultTargetPlatformOverride = null);

    // Your test code here
  });
}
  1. Mock the platform interface in your tests:
import 'package:haptic_feedback/src/haptic_feedback_platform_interface.dart';
import 'package:plugin_platform_interface/plugin_platform_interface.dart';

class MockHapticFeedbackPlatform extends Mock
    with MockPlatformInterfaceMixin
    implements HapticFeedbackPlatform {}

void main() {
  testWidgets('my widget test', (tester) async {
    final mockPlatform = MockHapticFeedbackPlatform();
    HapticFeedbackPlatform.instance = mockPlatform;
    
    when(() => mockPlatform.canVibrate()).thenAnswer((_) async => true);
    when(() => mockPlatform.vibrate(any())).thenAnswer((_) async {});
    
    // Your test code here
  });
}
  1. Mock the method channel to avoid MissingPluginException while using the real platform class:
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:haptic_feedback/src/haptic_feedback_method_channel.dart';
import 'package:haptic_feedback/src/haptics_type.dart';

void main() {
  const channel = MethodChannelHapticFeedback.methodChannel;
  TestDefaultBinaryMessengerBinding.ensureInitialized();

  setUp(() {
    final binding = TestDefaultBinaryMessengerBinding.instance;
    binding.defaultBinaryMessenger.setMockMethodCallHandler(
      channel,
      (MethodCall call) async {
        if (call.method == 'canVibrate') return true;
        return null; // success for vibrate calls
      },
    );
  });

  tearDown(() {
    final binding = TestDefaultBinaryMessengerBinding.instance;
    binding.defaultBinaryMessenger.setMockMethodCallHandler(channel, null);
  });

  test('canVibrate works with mocked channel', () async {
    expect(await MethodChannelHapticFeedback().canVibrate(), isTrue);
  });

  test('vibrate forwards to mocked channel', () async {
    await MethodChannelHapticFeedback().vibrate(HapticsType.success);
  });
}

You can find these examples as runnable tests in example/test on GitHub.

Automatic Permissions Inclusion

Android VIBRATE Permission

When you integrate the haptic_feedback plugin into your Flutter project, it will automatically include the necessary VIBRATE permission in the final merged AndroidManifest.xml of your app. This is due to the permission being declared in the plugin's manifest.

What this means for you:
  • No Manual Action Required: You don't have to add the <uses-permission android:name="android.permission.VIBRATE"/> permission to your app's AndroidManifest.xml manually. It will be automatically merged when building the app.

  • Transparency: By using the haptic_feedback plugin, your app will request the VIBRATE permission. Ensure that you are aware of all permissions your app requires, especially if you publish it on app stores. Some users may be sensitive to app permissions, even if they don't require explicit consent.

  • Permission Overview: To review all permissions that your app requests due to plugins and your own declarations, inspect the final merged AndroidManifest.xml after a build. This will provide a comprehensive view of all permissions and other manifest entries.

카테고리

의존성

의존성 목록 1 개

  • plugin_platform_interface^2.0.0

소스 저장소

이 패키지를 사용하는 프로젝트