기기 기능 공통 규칙 개요 | 기기 기능 공통 규칙 | Appbox Android SDK 가이드
기기 기능
기기 기능 공통 규칙 개요
기기와 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. 잘못된 값은 오류 없이 불투명 검정. 상세: 동작 설명 |
- iOS 가이드의 "표시/조회" 표기는 기준(뷰 컨트롤러 필요 여부)이 달라 이 문서의 잠금 표기와 호환되지 않습니다. 두 문서 사이에서 옮겨 적지 마세요.
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)로 실패합니다. - 연속 호출: 외부 화면을 여는 함수가 성공하면 다른 앱이 앞으로 나오면서 앱이 백그라운드로 내려가고, 곧바로 다른 기기 기능을 호출하면 백그라운드 규칙에 걸립니다. 후속 작업은 화면이 돌아온 뒤에 수행하세요.
- 8자리 색상 hex: Android는 알파가 뒤(
#RRGGBBAA), iOS는 알파가 앞(#AARRGGBB)이라 같은 문자열을 양쪽에 쓰면 색이 달라집니다. 크로스플랫폼 공유는 6자리(#RRGGBB)를 쓰거나 플랫폼별로 분기하세요. - artifact: 함수 선언은
appbox-core에 있어appbox-webview없이도 컴파일, 호출까지 되지만, 실행 파이프라인이 없어 모든 호출이AppBoxDeviceBridgeUnavailableException으로 실패합니다 → 2단계: 모듈 선언. - 동시 실행 잠금: 웹 브릿지와 잠금을 공유하므로, 웹에서 스캐너를 열어 둔 상태에서 네이티브로 스캐너를 호출해도 거절됩니다.
- 권한: 카메라, 위치, 생체인증 권한은
appbox-webview가 매니페스트에 선언하므로 앱이 따로 선언할 필요가 없습니다. - URL 정책: 대상 함수는
openBrowser,modalPageOpen,pdfViewerOpen,imageViewerOpen,localPushSend의targetUrl,imageUrl이며, 위반 시error메시지에 어떤 인자가 문제인지 담깁니다. - 색상 폴백: 형식이 잘못돼도 오류가 아니지만 표에 적힌 기본값으로 돌아가지 않습니다.
toastShow,imageViewerOpen,calendarOpen은 불투명 검정(#000000)이 됩니다. 예를 들어toastShow의 잘못된backColor는 기본값#00000099가 아니라 불투명 검정이 됩니다. 스캐너 2개 함수의messageColor,defColor,succColor만 예외로 투명이 되어 해당 요소가 아예 보이지 않습니다. 인자를 넘기지 않았을 때만 표의 기본값이 쓰입니다. - iOS "표시/조회" 표기: iOS 가이드의 그 표기는 뷰 컨트롤러 필요 여부 기준이라 이 문서의 동시 실행 잠금 축과 다릅니다.