기기 기능 공통 규칙 개요 | 기기 기능 공통 규칙 | Appbox Android SDK 가이드

기기 기능

기기 기능 공통 규칙 개요

기기와 OS 기능을 다루는 공개 함수 45개입니다. SDK 1.3.37+ 모두 같은 파이프라인을 공유하므로 공통 규칙을 먼저 정리하고, 각 함수는 차이점만 표로 설명합니다.

45개 전부에 적용되는 함정 3가지: 상세는 아래 동작 설명에 있습니다.

함정내용
백그라운드 호출조회 함수도 앱이 백그라운드면 NOT_SUPPORTED(-5002). Service, WorkManager, BroadcastReceiver에서 호출 불가
연속 호출share, openBrowser, openApp, sendSMS, dial 성공 직후엔 앱이 백그라운드라 다음 호출이 실패
8자리 색상 hexAndroid #RRGGBBAA vs iOS #AARRGGBB. 문자열 공유 불가. 크로스플랫폼은 6자리 권장

항목 정의

공통 규칙 요약

규칙내용
필요 artifact45개 전부 appbox-webview (선언은 appbox-core라 컴파일은 통과. 상세: 동작 설명). getPushAgree, localPushSend는 appbox-push도 필요
Activity 요건foreground FragmentActivity 필수. 아니면 -5002. AppCompatActivity 사용 가능
callbackAppBoxValueCallback<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)는 반복하지 않습니다.

코드이름의미
-1000USER_CANCELLED사용자가 닫음
-1002SDK_NOT_INITIALIZEDSDK 미초기화
-1003ALREADY_CALLED같은 기능이 이미 실행 중
-1004INVALID_URLURL 정책 위반
-2000MISSING_KEY필수 인자 누락
-2001INVALID_TYPE인자 타입 불일치
-3000EMPTY_VALUE빈 값
-3001VALUE_OUT_OF_RANGE허용 범위 밖의 값
-4000LOCAL_PUSH_ICON_MISSINGcommon.pushIcon 미설정
-5000FEATURE_UNAVAILABLE필요한 artifact 없음
-5001FEATURE_NOT_CONFIGURED초기화 설정 누락
-5002NOT_SUPPORTEDforeground FragmentActivity 아님
-6000APP_NOT_ON_MARKET스토어에서 앱을 찾을 수 없음
-7000PERMISSION_DENIED권한 거부
-7001NOT_SUPPORTED_DEVICE기기 미지원
-7002APP_NOT_INSTALLED대상 앱 미설치
-8000SERVICE_UNAVAILABLE실행 실패 또는 서버 오류
-9999UNKNOWN_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 가이드의 그 표기는 뷰 컨트롤러 필요 여부 기준이라 이 문서의 동시 실행 잠금 축과 다릅니다.
www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.