getAppVersion, getBatteryLevel 등 대부분의 조회 함수가 이 패턴입니다.기기와 OS 기능을 다루는 공개 함수 45개입니다. SDK 1.3.37+ 모두 같은 파이프라인을 공유하므로 공통 규칙을 먼저 정리하고, 각 함수는 차이점만 표로 설명합니다.
45개 전부에 적용되는 함정 3가지: 상세는 아래 동작 설명에 있습니다.
| 함정 | 내용 |
|---|---|
| 백그라운드 호출 | 조회 함수도 앱이 백그라운드면 NOT_SUPPORTED(-5002). Service, WorkManager, BroadcastReceiver에서 호출 불가 |
| 연속 호출 | share, openBrowser, openApp, sendSMS, dial 성공 직후엔 앱이 백그라운드라 다음 호출이 실패 |
| 8자리 색상 hex | Android #RRGGBBAA vs iOS #AARRGGBB. 문자열 공유 불가. 크로스플랫폼은 6자리 권장 |
항목 정의
공통 규칙 요약
| 규칙 | 내용 |
|---|---|
| 필요 artifact | 45개 전부 appbox-webview (선언은 appbox-core라 컴파일은 통과. 상세: 동작 설명). getPushAgree, localPushSend는 appbox-push도 필요 |
| Activity 요건 | foreground FragmentActivity 필수. 아니면 -5002. AppCompatActivity 사용 가능 |
| callback | AppBoxValueCallback<T> / AppBoxOperationCallback, main thread 최대 1회. error가 null이어도 value가 null일 수 있음 |
| 동시 실행 잠금 | "잠금 있음" 함수는 동시에 하나만. 실행 중이면 -1003. 웹 브릿지와 잠금 공유 |
| 권한 | 선언, 런타임 요청 모두 SDK가 처리: 거부 시 -7000 |
| URL 인자 | http/https만 허용, localhost, 사설 IP 거절. 위반 시 -1004 |
| 색상 인자 | #RGB, #RRGGBB, #RRGGBBAA, rgb(), rgba(), transparent. 잘못된 값은 오류 없이 불투명 검정. 상세: 동작 설명 |
calendarOpen의 selColor, textColor만 색상 규칙을 따르지 않습니다. 8자리 값을 #AARRGGBB(알파가 앞)로 해석하며, rgb(), rgba()와 3자리 축약형은 기본값으로 대체됩니다. 다른 함수와 색상 문자열을 재사용하지 마세요.
오류 코드 표 (정본)
실행 중 실패는 AppBoxBridgeException의 errorCode로 전달되며 웹 브릿지의 err.code와 같은 값입니다. 각 함수 문서에는 고유 코드만 적혀 있고 공통 코드(-1002, -5000, -5002)는 반복하지 않습니다.
| 코드 | 이름 | 의미 |
|---|---|---|
-1000 | USER_CANCELLED | 사용자가 닫음 |
-1002 | SDK_NOT_INITIALIZED | SDK 미초기화 |
-1003 | ALREADY_CALLED | 같은 기능이 이미 실행 중 |
-1004 | INVALID_URL | URL 정책 위반 |
-2000 | MISSING_KEY | 필수 인자 누락 |
-2001 | INVALID_TYPE | 인자 타입 불일치 |
-3000 | EMPTY_VALUE | 빈 값 |
-3001 | VALUE_OUT_OF_RANGE | 허용 범위 밖의 값 |
-4000 | LOCAL_PUSH_ICON_MISSING | common.pushIcon 미설정 |
-5000 | FEATURE_UNAVAILABLE | 필요한 artifact 없음 |
-5001 | FEATURE_NOT_CONFIGURED | 초기화 설정 누락 |
-5002 | NOT_SUPPORTED | foreground FragmentActivity 아님 |
-6000 | APP_NOT_ON_MARKET | 스토어에서 앱을 찾을 수 없음 |
-7000 | PERMISSION_DENIED | 권한 거부 |
-7001 | NOT_SUPPORTED_DEVICE | 기기 미지원 |
-7002 | APP_NOT_INSTALLED | 대상 앱 미설치 |
-8000 | SERVICE_UNAVAILABLE | 실행 실패 또는 서버 오류 |
-9999 | UNKNOWN_ERROR | 그 외 |
45개의 호출 형태는 패턴 A~E 5가지뿐입니다. 개별 함수 문서에서는 패턴 이름만 표기합니다.
동작 설명
함정과 규칙의 상세 동작입니다.
getAppVersion처럼 값만 읽어오는 함수도 예외가 아닙니다. 45개 전부 화면에 떠 있는 Activity를 통해 동작하므로, 앱이 백그라운드이거나 Activity가 없으면 진입 시점에 NOT_SUPPORTED(-5002)로 실패합니다.#RRGGBBAA), iOS는 알파가 앞(#AARRGGBB)이라 같은 문자열을 양쪽에 쓰면 색이 달라집니다. 크로스플랫폼 공유는 6자리(#RRGGBB)를 쓰거나 플랫폼별로 분기하세요.appbox-core에 있어 appbox-webview 없이도 컴파일, 호출까지 되지만, 실행 파이프라인이 없어 모든 호출이 AppBoxDeviceBridgeUnavailableException으로 실패합니다 → 2단계: 모듈 선언.appbox-webview가 매니페스트에 선언하므로 앱이 따로 선언할 필요가 없습니다.openBrowser, modalPageOpen, pdfViewerOpen, imageViewerOpen, localPushSend의 targetUrl, imageUrl이며, 위반 시 error 메시지에 어떤 인자가 문제인지 담깁니다.toastShow, imageViewerOpen, calendarOpen은 불투명 검정(#000000)이 됩니다. 예를 들어 toastShow의 잘못된 backColor는 기본값 #00000099가 아니라 불투명 검정이 됩니다. 스캐너 2개 함수의 messageColor, defColor, succColor만 예외로 투명이 되어 해당 요소가 아예 보이지 않습니다. 인자를 넘기지 않았을 때만 표의 기본값이 쓰입니다.getAppVersion, getBatteryLevel 등 대부분의 조회 함수가 이 패턴입니다.패턴 A: 인자 없는 값 조회
get, set, remove 등 저장소 함수가 이 패턴입니다.패턴 B: 인자 있는 값 조회
setClipBoard, dial, openBrowser 등이 이 패턴입니다.패턴 C: 인자 있는 동작
@JvmOverloads가 만든 오버로드를 사용하는데, 뒤쪽 인자부터 생략할 수 있고 callback은 항상 마지막에 유지됩니다. 중간 인자만 건너뛸 수는 없으므로, 앞쪽 인자를 기본값으로 두려면 null을 명시적으로 넘깁니다.패턴 D: 선택 인자가 여러 개인 함수
Map으로 돌려받는 형태입니다. getLocationCurrent, getDeviceInfo, getContacts 등이 이 패턴입니다.패턴 E: Map 반환
항목 정의
AppBoxValueCallback의 value는 nullable입니다. error가 null이어도 value가 null일 수 있으므로(예: getBatteryLevel이 배터리 정보를 읽지 못한 경우) 두 값을 모두 확인하세요.