오버레이 가이드

🎈 오버레이란?

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

가능한 것

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

제한사항

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

🚀 웹앱에서 제어하기

JavaScript Bridge를 통해 간단하게 오버레이를 표시하고 숨길 수 있습니다.

오버레이 표시

// 오버레이 표시 요청
await bridge.showOverlay({
  type: 'floating_button', // 오버레이 타입
  position: 'centerRight', // 위치
  width: 60,               // 너비 (픽셀)
  height: 60,              // 높이 (픽셀)
  enableDrag: true         // 드래그 가능 여부
});

오버레이 숨김

// 오버레이 닫기
await bridge.hideOverlay();

⚙️ 옵션 설명

위치 (position)

다음 문자열 값을 사용하여 오버레이 위치를 지정할 수 있습니다:

• topLeft, topCenter, topRight
• centerLeft, center, centerRight
• bottomLeft, bottomCenter, bottomRight

타입 (type)

• floating_button: 둥근 플로팅 버튼 형태
• navigation_bar: 상단/하단 네비게이션 바 형태
• custom: 사용자 정의 레이아웃

💬 데이터 통신

오버레이와 메인 웹앱 간에 데이터를 주고받을 수 있습니다.

데이터 보내기 (Web → Overlay)

// 오버레이로 데이터 전송
await bridge.sendToOverlay({
  action: 'UPDATE_COUNT',
  value: 5
});

데이터 받기 (Overlay → Web)

// 오버레이로부터 메시지 수신
window.addEventListener('overlay-message', (event) => {
  const { action, value } = event.detail;
  console.log('오버레이 메시지:', action, value);
});

💡 베스트 프랙티스

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

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