화면과 WebView | Appbox Android SDK 가이드

Android SDK 연동

화면과 WebView 개요

전제내용
필요 artifactappbox-webview (+ AppBox 관리 화면은 초기화 설정의 webView)
웹 브릿지 대응고객 WebView에서 gmenu.* 등 대부분의 브릿지 action 동작. 지원 범위는 고객 WebView 연결 참고

화면을 다루는 방식은 두 가지입니다: AppBox 관리 화면을 주 화면으로 쓰거나(AppBox.start), 앱이 소유한 WebView에 브릿지를 연결하거나(attachWebView).

usageMode는 화면 동작 조건이 아니라 푸시 클릭 라우팅 설정입니다. SERVICE_APP 상태에서도 관리 화면은 열립니다. 이름 때문에 화면 모드로 오해하기 쉽습니다.

⚠️ 이 장의 함수 대부분은 반환값, 콜백이 없어 실패를 알리지 않습니다. artifact 누락, 초기화 전 호출 모두 조용히 무시되므로 호출 순서가 유일한 안전장치입니다.

연결, 설정 여부는 웹페이지에서 appbox.getDeviceUserId를 호출해 확인할 수 있습니다.

관리 화면 설정 함수의 호출 시점은 다음과 같습니다. 셋 다 초기화 전 호출은 조용히 무시됩니다.

함수권장 호출 시점start 후 호출 시
setLoadingDatastart 전-
setSystemBarAppearancestart 전, 후 모두 가능표시 중인 화면에 즉시 반영
setPullDownRefreshstart 전-

AppBox 화면 시작

AppBox가 관리하는 WebView 화면을 실행합니다. 관리 화면을 서비스의 주 화면이나 부가 화면으로 쓸 때 호출합니다.

AppBox 화면 시작

AppBox.start(callback)

Kotlin
1 AppBox.start { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "화면 시작 실패")
3 }
1 AppBox.start(new AppBoxOperationCallback() {
2 @Override
3 public void onComplete(boolean success, Throwable error) {
4 if (!success) Log.w("AppBox", String.valueOf(error));
5 }
6 });

Request 항목 정의

Request 항목필수여부설명기본값
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success화면 실행 요청 전달 성공 여부 (true | false)
오류AppBoxWebViewUnavailableException: appbox-webview 미포함 또는 초기화 설정의 webView 누락


success == true는 실행 요청이 전달됐다는 의미입니다. 페이지 로딩 완료를 뜻하지 않습니다. 초기화보다 먼저 호출하지 않습니다. usageMode = APPBOX_WEBVIEW는 이 함수의 동작 조건이 아니라 푸시 클릭 라우팅 설정입니다 → 화면과 WebView 개요.

고객 WebView 연결

앱이 소유한 WebView에 AppBox bridge를 연결합니다. 자체 화면 구조를 유지하면서 웹페이지에서 브릿지 기능을 쓰게 하고 싶을 때 사용합니다.

고객 WebView 연결

AppBox.attachWebView(webView)

Kotlin
1 val webView: WebView = findViewById(R.id.webView)
2 webView.settings.javaScriptEnabled = true
3 webView.webViewClient = MyWebViewClient() // client는 연결 전에 설정합니다
4
5 AppBox.attachWebView(webView)
6 webView.loadUrl("<SERVICE_URL>")
1 WebView webView = findViewById(R.id.webView);
2 webView.getSettings().setJavaScriptEnabled(true);
3 webView.setWebViewClient(new MyWebViewClient()); // client는 연결 전에 설정합니다
4
5 AppBox.attachWebView(webView);
6 webView.loadUrl("<SERVICE_URL>");

Request 항목 정의

Request 항목필수여부설명기본값
webView필수Activity의 context로 생성한 android.webkit.WebView. applicationContext로 만든 WebView는 연결되지 않습니다-
  • 로드할 웹페이지에는 웹 SDK 스크립트 선언이 필요합니다. 웹 가이드의 초기 설정
  • 반환값, 콜백이 없으며 오류 전달이 없습니다. 연결 여부는 웹에서 appbox.getDeviceUserId를 호출해 확인합니다.

브릿지 지원 범위와 제약 요약

상세 동작은 아래 동작 설명에 있습니다.

항목동작
bridge actioninapp.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 활성 상태 갱신이 멈춥니다.

로딩 화면 설정

관리 화면의 로딩 표시를 설정합니다. 서비스 브랜드에 맞는 로딩 애니메이션을 쓰고 싶을 때 호출합니다.

로딩 화면 설정

AppBox.setLoadingData(loadingIcon, sizePercentage, iconColor, backColor)

Kotlin
1 AppBox.setLoadingData("<LOADING_LOTTIE_URL>", 20f, "#FFFFFF", "#33000000")
2
3 // 기본값을 쓰려면 인자를 줄일 수 있습니다
4 AppBox.setLoadingData("<LOADING_LOTTIE_URL>")
5 AppBox.setLoadingData()
1 AppBox.setLoadingData("<LOADING_LOTTIE_URL>", 20f, "#FFFFFF", "#33000000");
2
3 // 기본값을 쓰려면 인자를 줄일 수 있습니다
4 AppBox.setLoadingData("<LOADING_LOTTIE_URL>");
5 AppBox.setLoadingData();

Request 항목 정의

Request 항목필수여부설명기본값
loadingIcon-Lottie JSON 또는 이미지 URL. null이면 SDK 기본 표시null
sizePercentage-화면 대비 아이콘 크기 비율10f
iconColor-아이콘 색상 hexnull
backColor-배경 색상 hexnull

인자 개수가 다른 5가지 형태를 제공합니다. 뒤쪽 인자를 생략하면 위 기본값이 적용됩니다.

반환값, 콜백이 없으며 오류 전달이 없습니다. appbox-webview가 없으면 아무 동작도 하지 않습니다. AppBox 관리 화면에만 적용됩니다. 고객 WebView와 앱의 다른 화면에는 영향이 없습니다. AppBox.start 전에 호출합니다.

웹 브릿지에서는 로딩 인디케이터의 application.loadingShow입니다.

시스템 바 외관 설정

관리 화면의 상태바와 하단 내비게이션 바 배경색, 글자, 아이콘 밝기를 설정합니다. 관리 화면의 시스템 바를 서비스 테마에 맞출 때 호출합니다.

시스템 바 외관 설정

AppBox.setSystemBarAppearance(backgroundHex, style)

Kotlin
1 // 어두운 배경 + 자동 판정
2 AppBox.setSystemBarAppearance(backgroundHex = "#1F124C")
3
4 // 밝은 배경 + 어두운 글자
5 AppBox.setSystemBarAppearance("#FFFFFF", AppBoxSystemBarStyle.Dark)
6
7 // 배경은 유지하고 글자만 밝게
8 AppBox.setSystemBarAppearance(null, AppBoxSystemBarStyle.Light)
1 // 어두운 배경 + 자동 판정
2 AppBox.setSystemBarAppearance("#1F124C");
3
4 // 밝은 배경 + 어두운 글자
5 AppBox.setSystemBarAppearance("#FFFFFF", AppBoxSystemBarStyle.Dark);
6
7 // 배경은 유지하고 글자만 밝게
8 AppBox.setSystemBarAppearance(null, AppBoxSystemBarStyle.Light);

Request 항목 정의

Request 항목필수여부설명기본값
backgroundHex-#RRGGBB 또는 #AARRGGBB. 앞의 #은 생략 가능. null이면 배경을 변경하지 않음null
style-AppBoxSystemBarStyle. Auto, Light, Dark. 글자, 아이콘 기준Auto


style은 글자, 아이콘 기준입니다. 어두운 배경 → Light(흰 글자), 밝은 배경 → Dark(검은 글자). Auto는 배경색 밝기로 자동 결정합니다. backgroundHex = null은 "배경을 변경하지 않음"이며 style만 적용됩니다. 반환값, 콜백이 없으며 오류 전달이 없습니다. 관리 화면에만 적용되고, start 후 호출하면 표시 중인 화면에 즉시 반영됩니다.

잘못된 색상값을 전달하면 호출 전체가 무시됩니다. 배경색과 style 모두 이전 값을 유지합니다. 3자리 색상값과 색상 이름은 사용할 수 없습니다.

당겨서 새로고침 설정

관리 화면에서 당겨서 새로고침 동작을 사용할지 설정합니다. 콘텐츠를 임의로 새로고침하면 안 되는 화면이라면 false를 권장합니다.

당겨서 새로고침 설정

AppBox.setPullDownRefresh(used)

Kotlin
1 AppBox.setPullDownRefresh(false)
1 AppBox.setPullDownRefresh(false);

Request 항목 정의

Request 항목필수여부설명기본값
used필수당겨서 새로고침 사용 여부-


반환값, 콜백이 없으며 오류 전달이 없습니다. appbox-webview가 없으면 아무 동작도 하지 않습니다. AppBox 관리 화면에만 적용됩니다.

www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.