오버레이 가이드

🎈 오버레이란?

다른 앱 위에도 항상 표시되는 플로팅 위젯입니다. Facebook Messenger의 채팅 버블처럼 어떤 앱을 사용하든 항상 접근 가능합니다.

가능한 것

• ✅ 다른 앱 위에 위젯 표시 (Android)
• ✅ 항상 최상단 유지
• ✅ 드래그로 위치 이동
• ✅ 클릭/터치 이벤트 처리

제한사항

• ⚠️ Android 전용 (iOS는 보안상 불가)
• ⚠️ SYSTEM_ALERT_WINDOW 권한 필요
• ⚠️ 배터리 소모 증가 가능

📦 패키지 설치

pubspec.yaml:

dependencies:
  flutter_overlay_window: ^0.4.6

설치:

flutter pub get

🔒 권한 설정

android/app/src/main/AndroidManifest.xml:

<manifest>
  <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
  
  <application>
    <service
        android:name="flutter_overlay_window.OverlayService"
        android:exported="false"/>
  </application>
</manifest>

🚀 기본 사용법

1. 권한 요청

final status = await FlutterOverlayWindow.isPermissionGranted();
if (!status) {
  await FlutterOverlayWindow.requestPermission();
}

2. 오버레이 표시

await FlutterOverlayWindow.showOverlay(
  height: 100,
  width: 100,
  alignment: OverlayAlignment.centerRight,
  enableDrag: true,
);

3. 오버레이 숨김

await FlutterOverlayWindow.closeOverlay();

🎨 오버레이 타입

плотfloating 버튼

FlutterOverlayWindow.showOverlay(
  height: 60,
  width: 60,
  alignment: OverlayAlignment.centerRight,
);

미니 네비게이션 바

FlutterOverlayWindow.showOverlay(
  height: 50,
  width: WindowSize.matchParent,
  alignment: OverlayAlignment.topCenter,
);

🔗 Vue 브릿지 연동

웹앱에서 오버레이 제어

// Vue
await bridge.showOverlay({
  type: 'floating_button',
  position: 'right'
});

await bridge.hideOverlay();

Flutter 구현

case 'SHOW_OVERLAY':
  await FlutterOverlayWindow.showOverlay(...);
  break;

case 'HIDE_OVERLAY':
  await FlutterOverlayWindow.closeOverlay();
  break;

💬 데이터 통신

메인 앱 → 오버레이

await FlutterOverlayWindow.shareData({
  'type': 'steps',
  'value': 5000
});

오버레이 수신

FlutterOverlayWindow.overlayListener.listen((data) {
  setState(() {
    steps = data['value'];
  });
});

⚙️ 커스터마이징

위치

• OverlayAlignment.topLeft
• OverlayAlignment.topCenter
• OverlayAlignment.topRight
• OverlayAlignment.centerLeft
• OverlayAlignment.center
• OverlayAlignment.centerRight
• OverlayAlignment.bottomLeft
• OverlayAlignment.bottomCenter
• OverlayAlignment.bottomRight

크기

height: 100,                    // 고정 크기
width: WindowSize.matchParent,  // 화면 너비 가득
width: WindowSize.wrapContent,  // 내용에 맞게

💡 베스트 프랙티스

• 크기: 너무 크면 방해됨 (48-60dp 권장)
• 닫기: 쉽게 닫을 수 있어야 함
• 위치: 드래그 가능하게
• 배터리: 필요할 때만 활성화

⚠️ Android 전용 기능입니다
iOS에서는 자체 앱 내 오버레이만 가능합니다