기기 기능 공통 규칙 | Appbox iOS SDK 가이드

기기 기능 공통 규칙

기기와 OS 기능을 다루는 공개 함수 47개입니다. 앞 장들과 달리 정적 AppBox가 아니라 인스턴스 AppBox.shared로 호출하며, 47개가 모두 같은 호출 경로를 공유하므로 공통 규칙을 먼저 정리하고 각 함수는 차이점만 표로 설명합니다.

시작하기 전에

1. 호출 방식이 다릅니다. 다른 장의 함수는 AppBox.initialize(...)처럼 정적으로 부르지만, 이 장의 47개는 AppBox.shared.toastShow(...) 처럼 인스턴스를 거칩니다. AppBox.shared는 AppBoxProtocol 타입이며 SDK가 만들어 둔 단일 인스턴스입니다.

2. 화면이 필요한 함수와 아닌 함수가 나뉩니다. 조회 계열은 앱이 백그라운드여도 동작하지만, 화면을 띄우는 계열은 표시할 뷰 컨트롤러가 없으면 -5002로 실패합니다. Android가 45개 전부 foreground Activity를 요구하는 것과 다른 지점이니 크로스플랫폼으로 옮길 때 주의하세요.

3. 웹 브릿지와 같은 기능입니다. 각 함수는 웹에서 쓰던 AppboxSDK.application.toastShow(...)와 같은 동작을 네이티브에서 부르는 것입니다. 같은 화면을 웹과 네이티브 양쪽에서 동시에 띄우지 않도록 하세요.

기기 기능 공통 규칙

호출 방법: AppBox.shared.함수명(...). Objective-C에서는 [AppBox.shared 함수명...] 형태이며 셀렉터는 각 함수 표에 적었습니다.
completion: 메인 스레드에서 정확히 한 번 호출됩니다. 호출을 어느 스레드에서 하든 SDK가 메인으로 넘깁니다.
성공과 실패: 성공은 (값, nil), 실패는 (기본값 또는 nil, NSError)입니다. 오류의 domain은 kr.co.mobpa.appbox.bridge 이고 code는 아래 표와 같습니다. 이 코드값은 웹 브릿지와 동일합니다.
코드의미
-1000사용자가 취소
-1003같은 기능이 이미 실행 중
-1004URL 정책 위반
-2000필수 인자 누락
-2001인자 타입 불일치
-3000빈 값
-3001허용 범위 밖의 값
-5000네이티브에 공개되지 않은 기능
-5002표시할 화면이 없음
-6000스토어에서 앱을 찾을 수 없음
-7000권한 거부
-7001기기 미지원
-8000실행 실패 또는 서버 오류
-9999그 외
화면 요건: 화면 필요로 분류한 함수는 SDK가 화면 위에 뷰를 올립니다. 표시할 뷰 컨트롤러를 찾지 못하면 -5002로 실패합니다. 화면 불필요로 분류한 함수는 앱이 백그라운드여도 동작합니다.
중복 호출: 화면을 띄우는 함수가 이미 실행 중일 때 다시 부르면 -1003으로 거절됩니다. 이 잠금은 화면 요건과 별개 축이라 화면 불필요로 분류한 함수도 잠금에 참여할 수 있습니다 (예: 앱 평가). 잠금은 웹 브릿지와 공유되므로, 웹에서 스캐너가 열려 있으면 네이티브 호출도 거절됩니다.
기본값 오버로드: 인자가 많은 함수 10개는 자주 쓰는 값을 채워 주는 축약형을 함께 제공합니다. 해당 함수의 주의사항에 축약형으로 표시했습니다. 축약형은 Swift 전용입니다. Objective-C에는 전체 인자 형태만 있습니다.

색상 인자는 문자열입니다. 8자리 hex를 쓸 때 iOS는 #AARRGGBB(알파가 앞), Android는 #RRGGBBAA(알파가 뒤) 라 같은 문자열을 양쪽에 쓰면 색이 달라집니다. 6자리(#RRGGBB)만 쓰면 안전합니다.

권한을 쓰는 함수는 Info.plist에 사용 목적 문자열이 있어야 합니다. 카메라는 NSCameraUsageDescription, Face ID는 NSFaceIDUsageDescription, 위치는 NSLocationWhenInUseUsageDescription입니다. SDK가 대신 넣어 주지 않으므로 앱에서 직접 설정하세요. Android와 가장 크게 다른 지점입니다. Android는 SDK가 매니페스트에 권한을 선언합니다.

호출 패턴

47개의 호출 형태는 아래 3가지뿐입니다. 개별 함수 설명에서는 패턴 이름만 표기합니다.
www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.