초기 설정 | Appbox iOS SDK 가이드
시작하기
| 단계 | 하는 일 | 필수 |
|---|---|---|
| 1단계: 패키지와 Product 추가 | Swift Package를 받고 쓸 Product를 앱 target에 연결 | 필수 |
| 2단계: Info.plist와 Capability | 사용하는 기능의 권한 문자열과 Capability 선언 | 필수 |
| 3단계: 초기화 | AppDelegate에서 AppBox.initialize 호출 | 필수 |
| 설치 확인 | 세 층으로 나눠 실제 동작 확인 | 옵션 |
동작하는 예제로 시작하기
1단계: 패키지와 Product 추가
1.4.0). 4. Add Package를 누르면 Product 선택 창이 뜹니다. 사용할 Product만 체크하고 Add to Target에서 앱 target을 고릅니다.
1단계: 패키지와 Product 추가
저장소 이름은 AppBoxSDKFramwork입니다. Framework로 고쳐 입력하면 패키지를 찾지 못합니다.
1.4.0). 공개 저장소라 별도 인증은 필요 없습니다.
Product 선택
| Product | 필요한 경우 | 없으면 |
|---|---|---|
AppBoxSDK | 관리 화면, 웹 브릿지, 기기 기능 47개 | import AppBoxSDK 컴파일 실패 |
AppBoxPushSDK | 푸시 알림 | Push 함수가 실패로 응답 (빌드는 성공) |
AppBoxInappMessageSDK | 네이티브 인앱 메시지 | 인앱 미표시: AppBoxInitResult.inApp.status로 확인 |
AppBoxHealthSDK | 걸음 수 | 걸음 수 조회 실패, isHealthAvailable() == false |
AppBoxSnsLoginSDK | SNS 로그인 | 로그인 실패, isAuthAvailable(...) == false |
Push, In-App, Auth, Health 함수의 선언은 AppBoxSDK에 있어 해당 Product 없이도 컴파일되고 호출까지 됩니다. 실행 모듈이 없으면 앱을 중단시키지 않고 NSError, false, 빈 결과로 실패합니다. 빌드 성공이 동작을 보장하지 않는 지점입니다.
AppBoxPushSDK는 AppBoxSDK에 포함되지 않습니다. 서로 의존하지 않으므로 푸시를 쓰는 앱은 두 Product를 각각 추가해야 합니다. 일반적인 서비스 앱은 이 조합이 기본입니다.
AppBox.shared.toastShow(...)처럼 인스턴스로 호출하는 함수들이며 AppBoxSDK에 있습니다. 자세한 내용은 기기 기능 공통 규칙 이하를 보세요.
웹뷰가 필요한 기능과 아닌 기능
webView는 선택 인자라 넣지 않아도 초기화됩니다.
| 구분 | 내용 |
|---|---|
| 웹뷰가 있어야 하는 것 | AppBox 관리 화면 실행(AppBox.start(from:)), 앱이 소유한 WebView에 브릿지 연결 |
| 웹뷰 없이 되는 것 | 푸시, 네이티브 인앱 메시지, SNS 로그인, 걸음 수, 기기 기능 47개 |
웹뷰와는 별개로 화면(뷰 컨트롤러)이 필요한 기기 기능이 14개 있습니다. 스캐너, 뷰어, 토스트처럼 화면 위에 무언가를 올리는 함수들이며, 앱이 백그라운드이거나 표시할 뷰 컨트롤러가 없으면 -5002로 실패합니다. 함수별 구분은 기기 기능 공통 규칙의 화면 요건을 보세요.
구성별 권장 조합
| 앱 구성 | 추가할 Product |
|---|---|
| 기본 AppBox 서비스 앱 | AppBoxSDK + AppBoxPushSDK |
고객사 WKWebView 연결 | AppBoxSDK + AppBoxPushSDK |
| SNS 로그인 추가 | 위 + AppBoxSnsLoginSDK |
| 걸음 수 추가 | 위 + AppBoxHealthSDK |
| 푸시 이미지 처리 | 앱 target과 NSE target 양쪽에 AppBoxPushSDK |
| 푸시만 쓰는 앱 | AppBoxPushSDK만 |
| 웹뷰 없이 네이티브 인앱만 | AppBoxInappMessageSDK (푸시 클릭, 사일런트 푸시가 필요하면 AppBoxPushSDK 추가) |
target 연결
외부 의존성
| 라이브러리 | 버전 | 함께 설치되는 Product |
|---|---|---|
| firebase-ios-sdk | 11.12.0 이상 | AppBoxPushSDK, AppBoxSnsLoginSDK |
| GoogleSignIn-iOS | 9.0.0 이상 | AppBoxSnsLoginSDK |
| kakao-ios-sdk | 2.26.0 이상 | AppBoxSnsLoginSDK |
| naveridlogin-sdk-ios-swift | 5.1.0 이상 | AppBoxSnsLoginSDK |
| AppsFlyerFramework | 6.17.6 이상 (minor 고정) | AppBoxSDK |
| lottie-spm | 4.6.0 이상 | AppBoxSDK |
Lottie와 AppsFlyerLib는 AppBoxSDK의 전이 의존성으로 함께 설치됩니다. 같은 패키지를 앱에 따로 추가하지 마세요. 버전이 다르면 충돌합니다.
푸시 이미지나 수신 집계가 필요한 앱이라면 Notification Service Extension target을 따로 만들고, 앱 target과 NSE target 양쪽에 AppBoxPushSDK를 추가하세요. 구현 코드는 Notification Service Extension 장에 있습니다.
2단계: Info.plist와 Capability
Info.plist에 사용 목적 문자열이 있어야 합니다. SDK가 대신 선언해 주지 않으므로 앱에서 직접 넣습니다.
Android와 함께 연동 중이라면 주의하세요. Android에서는 SDK가 매니페스트에 권한을 선언하므로, iOS에서만 이 단계가 앱의 몫입니다.
| 키 | 필요한 기능 |
|---|---|
NSCameraUsageDescription | openQRCodeScanner, openBarcodeScanner |
NSFaceIDUsageDescription | biometricAuth (Face ID) |
NSLocationWhenInUseUsageDescription | getLocationCurrent |
NSHealthShareUsageDescription | 걸음 수 |
LSApplicationQueriesSchemes | openApp: 실행할 앱의 scheme을 배열로 등록 |
2단계: Info.plist와 Capability
LSApplicationQueriesSchemes에 등록하지 않으면 iOS가 scheme 조회를 차단합니다. 대상 앱이 설치돼 있어도 openApp이 App Store로 이동합니다.
연락처 기능은 사용 목적 문자열이 필요 없습니다. SDK가 OS의 연락처 선택 화면을 사용하므로 앱이 주소록을 직접 읽지 않습니다.
Capability
| 기능 | 앱 target에 추가할 것 |
|---|---|
| 푸시 | Push Notifications |
| 사일런트 푸시, 백그라운드 처리 | Background Modes → Remote notifications |
| 걸음 수 | HealthKit |
| 푸시 이미지(NSE) | 앱과 NSE target에 같은 App Groups |
NSAllowsArbitraryLoads = true를 기본으로 켜지 말고, 불가피한 HTTP 도메인이 있으면 그 도메인만 예외로 선언하세요. 이 안내는 SDK를 직접 붙이는 앱 기준입니다. 앱박스 클라우드 빌드로 만든 앱은 기존 사이트 호환을 위해 NSAllowsArbitraryLoads = true가 켜진 채 빌드되므로 따로 설정할 것이 없습니다.
3단계: 초기화
didFinishLaunchingWithOptions에서 진행합니다. common은 필수이고, 나머지 설정은 1단계에서 추가한 Product에 맞춰 넣습니다.
3단계: 초기화
AppBox 관리 화면을 쓰지 않는 앱은 webView를 넣지 않습니다. 선택 인자라 생략하면 되고, 푸시, 인앱, 로그인, 걸음 수, 기기 기능은 그대로 동작합니다.
초기화 전에 부른 기능 함수는 앱을 중단시키지 않고 NSError나 false로 실패합니다. 앱 시작 직후 SDK 기능을 쓰는 앱이라면 초기화 완료 callback 이후로 호출을 미루세요.
Firebase
GoogleService-Info.plist는 넣지 않아도 됩니다. AppBox 콘솔에 Firebase 설정이 등록돼 있으면, SDK가 프로젝트 ID와 Bundle ID로 설정을 받아 Firebase를 초기화합니다. 앱이 Firebase를 직접 관리할 때만 plist를 넣습니다.
앱이 이미 FirebaseApp.configure()를 호출한다면 AppBox 초기화 전에 끝내세요. SDK가 기존 FirebaseApp을 재사용합니다. 두 경로로 중복 초기화하지 마세요.
설치 확인
| 층 | 확인 방법 | 증명하는 것 |
|---|---|---|
| Product 포함 | is*Available(): 동기, 초기화 전에도 동작 (예외: isInAppAvailable()은 항상 true) | Product 추가 여부만 |
| 초기화 성공 | initialize callback AppBoxInitResult의 모듈별 status | 설정, 초기화까지 |
| 실제 동작 | getSDKVersion callback | 파이프라인 전체 |
설치 확인
결과가 이상하면
| 증상 | 돌아갈 곳 |
|---|---|
isPushAvailable() == false | 1단계: Product 누락 |
initialize status가 .FAILED/.SKIPPED | 3단계: 초기화 설정 누락 |
getSDKVersion callback이 실패 | 3단계: 초기화 미실행 의심 |
스캐너 호출이 -5002로 실패 | 2단계: NSCameraUsageDescription 누락 |
동작하는 예제가 필요하면 AppBoxSampleiOS. 올리려는 버전이 실제로 어떻게 연동되는지는 같은 태그에서 확인하세요.
다음 단계
AppBox.start(from:)을, 앱이 만든 WebView에 브릿지를 연결하려면 자체 WebView 연동 장을 이어서 보세요.