화면과 WebView | Appbox Android SDK 가이드
Android SDK 연동
화면과 WebView 개요
| 전제 | 내용 |
|---|---|
| 필요 artifact | appbox-webview (+ AppBox 관리 화면은 초기화 설정의 webView) |
| 웹 브릿지 대응 | 고객 WebView에서 gmenu.* 등 대부분의 브릿지 action 동작. 지원 범위는 고객 WebView 연결 참고 |
화면을 다루는 방식은 두 가지입니다: AppBox 관리 화면을 주 화면으로 쓰거나(AppBox.start), 앱이 소유한 WebView에 브릿지를 연결하거나(attachWebView).
usageMode는 화면 동작 조건이 아니라 푸시 클릭 라우팅 설정입니다. SERVICE_APP 상태에서도 관리 화면은 열립니다. 이름 때문에 화면 모드로 오해하기 쉽습니다.
⚠️ 이 장의 함수 대부분은 반환값, 콜백이 없어 실패를 알리지 않습니다. artifact 누락, 초기화 전 호출 모두 조용히 무시되므로 호출 순서가 유일한 안전장치입니다.
연결, 설정 여부는 웹페이지에서 appbox.getDeviceUserId를 호출해 확인할 수 있습니다.
관리 화면 설정 함수의 호출 시점은 다음과 같습니다. 셋 다 초기화 전 호출은 조용히 무시됩니다.
| 함수 | 권장 호출 시점 | start 후 호출 시 |
|---|---|---|
setLoadingData | start 전 | - |
setSystemBarAppearance | start 전, 후 모두 가능 | 표시 중인 화면에 즉시 반영 |
setPullDownRefresh | start 전 | - |
AppBox 화면 시작
AppBox 화면 시작
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| callback | 필수 | AppBoxOperationCallback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 화면 실행 요청 전달 성공 여부 (true | false) |
| 오류 | AppBoxWebViewUnavailableException: appbox-webview 미포함 또는 초기화 설정의 webView 누락 |
success == true는 실행 요청이 전달됐다는 의미입니다. 페이지 로딩 완료를 뜻하지 않습니다. 초기화보다 먼저 호출하지 않습니다. usageMode = APPBOX_WEBVIEW는 이 함수의 동작 조건이 아니라 푸시 클릭 라우팅 설정입니다 → 화면과 WebView 개요.
고객 WebView 연결
고객 WebView 연결
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| webView | 필수 | Activity의 context로 생성한 android.webkit.WebView. applicationContext로 만든 WebView는 연결되지 않습니다 | - |
- 로드할 웹페이지에는 웹 SDK 스크립트 선언이 필요합니다. 웹 가이드의 초기 설정
- 반환값, 콜백이 없으며 오류 전달이 없습니다. 연결 여부는 웹에서
appbox.getDeviceUserId를 호출해 확인합니다.
브릿지 지원 범위와 제약 요약
상세 동작은 아래 동작 설명에 있습니다.
| 항목 | 동작 |
|---|---|
| bridge action | inapp.requestShow 하나만 차단(-8000). 네이티브에서는 showInAppCampaign 사용 |
gmenu.* 7개 | 동작함. 단 그 WebView의 하단 모서리에 고정 표시 (관리 화면과 다름) |
| 스레드 | SDK가 관리: 웹으로 보내는 응답은 항상 main thread |
WebChromeClient | 감싸지 않음. 파일 선택, JS dialog, 새 창은 앱 책임 (SDK fallback 없음) |
webViewClient | 연결 전에 설정, 이후 교체 금지: 교체 시 페이지 로드 추적, 이벤트 전달 중단 |
| 동시 연결 | hosted WebView 1개만 공식 지원, 연결 해제 함수 없음 |
동작 설명
- 오류가 전달되지 않는 실패에는 artifact 누락, context 문제, 내부 오류가 모두 포함됩니다.
inapp.requestShow는 고객 WebView에 캠페인 컨텍스트가 없어SERVICE_UNAVAILABLE(-8000)로 거절됩니다.gmenu.*는 SDK가 해당 WebView 영역에 오버레이를 만들어 붙입니다. WebView가 화면에서 떨어지면 메뉴도 함께 사라지고, 스크롤 연동 자동 숨김은 관리 화면 전용이라 고객 WebView에서는 고정 표시됩니다. 오버레이를 만들 수 없는 호스트에서는FEATURE_UNAVAILABLE(-5000)로 실패합니다.- bridge 요청은 WebView의 백그라운드 스레드로 들어오지만 SDK가 처리 스레드를 관리하므로 앱이 신경 쓸 일이 없습니다.
WebChromeClient미래핑의 영향: 웹 페이지에서<input type="file">(onShowFileChooser)이나window.open을 쓴다면 앱이 직접WebChromeClient를 설정해야 합니다.- 기존
WebViewClient는 SDK가 delegate로 보존한 wrapper로 감쌉니다. 연결 후 교체하면 bridge 호출 자체는 계속 동작하지만 SDK의 페이지 로드 추적이 끊겨, native에서 웹으로 보내는 이벤트 전달(AppsFlyer 딥링크 결과 등)과 브라우저 메뉴의 back/forward 활성 상태 갱신이 멈춥니다.
로딩 화면 설정
로딩 화면 설정
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| loadingIcon | - | Lottie JSON 또는 이미지 URL. null이면 SDK 기본 표시 | null |
| sizePercentage | - | 화면 대비 아이콘 크기 비율 | 10f |
| iconColor | - | 아이콘 색상 hex | null |
| backColor | - | 배경 색상 hex | null |
인자 개수가 다른 5가지 형태를 제공합니다. 뒤쪽 인자를 생략하면 위 기본값이 적용됩니다.
반환값, 콜백이 없으며 오류 전달이 없습니다. appbox-webview가 없으면 아무 동작도 하지 않습니다. AppBox 관리 화면에만 적용됩니다. 고객 WebView와 앱의 다른 화면에는 영향이 없습니다. AppBox.start 전에 호출합니다.
웹 브릿지에서는 로딩 인디케이터의 application.loadingShow입니다.
시스템 바 외관 설정
시스템 바 외관 설정
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| backgroundHex | - | #RRGGBB 또는 #AARRGGBB. 앞의 #은 생략 가능. null이면 배경을 변경하지 않음 | null |
| style | - | AppBoxSystemBarStyle. Auto, Light, Dark. 글자, 아이콘 기준 | Auto |
style은 글자, 아이콘 기준입니다. 어두운 배경 → Light(흰 글자), 밝은 배경 → Dark(검은 글자). Auto는 배경색 밝기로 자동 결정합니다. backgroundHex = null은 "배경을 변경하지 않음"이며 style만 적용됩니다. 반환값, 콜백이 없으며 오류 전달이 없습니다. 관리 화면에만 적용되고, start 후 호출하면 표시 중인 화면에 즉시 반영됩니다.
잘못된 색상값을 전달하면 호출 전체가 무시됩니다. 배경색과 style 모두 이전 값을 유지합니다. 3자리 색상값과 색상 이름은 사용할 수 없습니다.
당겨서 새로고침 설정
false를 권장합니다.당겨서 새로고침 설정
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| used | 필수 | 당겨서 새로고침 사용 여부 | - |
반환값, 콜백이 없으며 오류 전달이 없습니다. appbox-webview가 없으면 아무 동작도 하지 않습니다. AppBox 관리 화면에만 적용됩니다.