초기 설정 | Appbox iOS SDK 가이드

시작하기

AppBox iOS SDK를 앱에 연동하는 절차입니다. Swift Package를 추가하고, 권한 문자열을 선언한 뒤, 초기화 코드를 넣으면 완료됩니다. 이미 연동돼 있다면 공통 규칙부터 읽으세요.
단계하는 일필수
1단계: 패키지와 Product 추가Swift Package를 받고 쓸 Product를 앱 target에 연결필수
2단계: Info.plist와 Capability사용하는 기능의 권한 문자열과 Capability 선언필수
3단계: 초기화AppDelegate에서 AppBox.initialize 호출필수
설치 확인세 층으로 나눠 실제 동작 확인옵션

동작하는 예제로 시작하기

설치 절차를 따라가기 전에 동작하는 앱을 먼저 보고 싶다면 AppBoxSampleiOS를 받으세요. SDK 설치, 초기화, 관리 화면 실행까지의 최소 구성이며, Swift와 Objective-C 구성이 함께 들어 있습니다.

1단계: 패키지와 Product 추가

(필수) SDK는 Swift Package Manager로 배포됩니다. Xcode에서 다음 순서로 추가합니다.
1. File → Add Package Dependencies를 엽니다. 2. 오른쪽 위 검색창에 아래 저장소 URL을 넣습니다. 3. Dependency Rule에서 사용할 버전을 지정합니다(예: Exact Version 1.4.0). 4. Add Package를 누르면 Product 선택 창이 뜹니다. 사용할 Product만 체크하고 Add to Target에서 앱 target을 고릅니다.

1단계: 패키지와 Product 추가

Text
1 https://github.com/MobilePartnersCo/AppBoxSDKFramwork.git

저장소 이름은 AppBoxSDKFramwork입니다. Framework로 고쳐 입력하면 패키지를 찾지 못합니다.

버전 규칙은 사용할 릴리스 태그를 지정합니다(예: 1.4.0). 공개 저장소라 별도 인증은 필요 없습니다.

Product 선택

공개 Product는 5개입니다. 사용하는 것만 앱 target에 추가하세요.
Product필요한 경우없으면
AppBoxSDK관리 화면, 웹 브릿지, 기기 기능 47개import AppBoxSDK 컴파일 실패
AppBoxPushSDK푸시 알림Push 함수가 실패로 응답 (빌드는 성공)
AppBoxInappMessageSDK네이티브 인앱 메시지인앱 미표시: AppBoxInitResult.inApp.status로 확인
AppBoxHealthSDK걸음 수걸음 수 조회 실패, isHealthAvailable() == false
AppBoxSnsLoginSDKSNS 로그인로그인 실패, isAuthAvailable(...) == false

Push, In-App, Auth, Health 함수의 선언은 AppBoxSDK에 있어 해당 Product 없이도 컴파일되고 호출까지 됩니다. 실행 모듈이 없으면 앱을 중단시키지 않고 NSError, false, 빈 결과로 실패합니다. 빌드 성공이 동작을 보장하지 않는 지점입니다.

AppBoxPushSDK는 AppBoxSDK에 포함되지 않습니다. 서로 의존하지 않으므로 푸시를 쓰는 앱은 두 Product를 각각 추가해야 합니다. 일반적인 서비스 앱은 이 조합이 기본입니다.

기기 기능 47개는 AppBox.shared.toastShow(...)처럼 인스턴스로 호출하는 함수들이며 AppBoxSDK에 있습니다. 자세한 내용은 기기 기능 공통 규칙 이하를 보세요.

웹뷰가 필요한 기능과 아닌 기능

AppBox 관리 화면(웹뷰)을 쓰지 않는 네이티브 앱도 SDK 대부분을 그대로 사용할 수 있습니다. 초기화 설정의 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는 앱 target의 General → Frameworks, Libraries, and Embedded Content에서 Embed & Sign으로 설정하세요.

외부 의존성

SDK가 SPM으로 함께 설치하는 라이브러리입니다. 앱이 같은 라이브러리를 다른 버전으로 쓰고 있으면 충돌할 수 있습니다.
라이브러리버전함께 설치되는 Product
firebase-ios-sdk11.12.0 이상AppBoxPushSDK, AppBoxSnsLoginSDK
GoogleSignIn-iOS9.0.0 이상AppBoxSnsLoginSDK
kakao-ios-sdk2.26.0 이상AppBoxSnsLoginSDK
naveridlogin-sdk-ios-swift5.1.0 이상AppBoxSnsLoginSDK
AppsFlyerFramework6.17.6 이상 (minor 고정)AppBoxSDK
lottie-spm4.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에서만 이 단계가 앱의 몫입니다.

키필요한 기능
NSCameraUsageDescriptionopenQRCodeScanner, openBarcodeScanner
NSFaceIDUsageDescriptionbiometricAuth (Face ID)
NSLocationWhenInUseUsageDescriptiongetLocationCurrent
NSHealthShareUsageDescription걸음 수
LSApplicationQueriesSchemesopenApp: 실행할 앱의 scheme을 배열로 등록

2단계: Info.plist와 Capability

Text
1 <key>NSCameraUsageDescription</key>
2 <string>QR 코드와 바코드 스캔에 카메라를 사용합니다.</string>
3
4 <key>LSApplicationQueriesSchemes</key>
5 <array>
6 <string>instagram</string> <!-- openApp으로 실행할 앱의 scheme -->
7 </array>

LSApplicationQueriesSchemes에 등록하지 않으면 iOS가 scheme 조회를 차단합니다. 대상 앱이 설치돼 있어도 openApp이 App Store로 이동합니다.

사용하는 기능의 키만 선언하세요. 모든 권한 키를 일괄로 추가하면 App Store 심사에서 사용 근거를 요구받을 수 있습니다.

연락처 기능은 사용 목적 문자열이 필요 없습니다. SDK가 OS의 연락처 선택 화면을 사용하므로 앱이 주소록을 직접 읽지 않습니다.

Capability

기능앱 target에 추가할 것
푸시Push Notifications
사일런트 푸시, 백그라운드 처리Background Modes → Remote notifications
걸음 수HealthKit
푸시 이미지(NSE)앱과 NSE target에 같은 App Groups
서비스 URL은 HTTPS를 사용하세요. NSAllowsArbitraryLoads = true를 기본으로 켜지 말고, 불가피한 HTTP 도메인이 있으면 그 도메인만 예외로 선언하세요. 이 안내는 SDK를 직접 붙이는 앱 기준입니다. 앱박스 클라우드 빌드로 만든 앱은 기존 사이트 호환을 위해 NSAllowsArbitraryLoads = true가 켜진 채 빌드되므로 따로 설정할 것이 없습니다.

3단계: 초기화

(필수) 초기화는 앱 시작 시 한 번, AppDelegate의 didFinishLaunchingWithOptions에서 진행합니다. common은 필수이고, 나머지 설정은 1단계에서 추가한 Product에 맞춰 넣습니다.

3단계: 초기화

Swift
1 import AppBoxSDK
2
3 func application(
4 _ application: UIApplication,
5 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
6 ) -> Bool {
7 let config = AppBoxInitConfig(
8 common: AppBoxCommonConfig(
9 projectId: "<PROJECT_ID>" // AppBox 콘솔에서 발급
10 ),
11 webView: AppBoxWebViewConfig(
12 baseURL: "https://service.example.com" // 관리 화면이 처음 여는 HTTPS 주소
13 ),
14 push: AppBoxPushConfig()
15 )
16 AppBox.initialize(config) { result in
17 // 모듈별 status: .INITIALIZED / .SKIPPED / .FAILED
18 // 해석은 SDK 초기화 페이지 참고
19 }
20 return true
21 }
1 @import AppBoxSDK;
2
3 - (BOOL)application:(UIApplication *)application
4 didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
5 AppBoxCommonConfig *common =
6 [[AppBoxCommonConfig alloc] initWithProjectId:@"<PROJECT_ID>" // AppBox 콘솔에서 발급
7 debugMode:NO];
8 AppBoxWebViewConfig *webView =
9 [[AppBoxWebViewConfig alloc] initWithBaseURL:@"https://service.example.com"
10 webConfig:[[AppBoxWebConfig alloc] init]];
11 AppBoxInitConfig *config =
12 [[AppBoxInitConfig alloc] initWithCommon:common
13 webView:webView
14 push:[[AppBoxPushConfig alloc] init]
15 inApp:[[AppBoxInAppConfig alloc] init]
16 auth:nil
17 appsFlyer:nil
18 initializationTimeout:30];
19
20 [AppBox initializeWithConfig:config completion:^(AppBoxInitResult *result) {
21 // 모듈별 status: INITIALIZED / SKIPPED / FAILED: 해석은 SDK 초기화 페이지 참고
22 }];
23 return YES;
24 }

AppBox 관리 화면을 쓰지 않는 앱은 webView를 넣지 않습니다. 선택 인자라 생략하면 되고, 푸시, 인앱, 로그인, 걸음 수, 기기 기능은 그대로 동작합니다.

초기화 전에 부른 기능 함수는 앱을 중단시키지 않고 NSError나 false로 실패합니다. 앱 시작 직후 SDK 기능을 쓰는 앱이라면 초기화 완료 callback 이후로 호출을 미루세요.

Firebase

GoogleService-Info.plist는 넣지 않아도 됩니다. AppBox 콘솔에 Firebase 설정이 등록돼 있으면, SDK가 프로젝트 ID와 Bundle ID로 설정을 받아 Firebase를 초기화합니다. 앱이 Firebase를 직접 관리할 때만 plist를 넣습니다.

앱이 이미 FirebaseApp.configure()를 호출한다면 AppBox 초기화 전에 끝내세요. SDK가 기존 FirebaseApp을 재사용합니다. 두 경로로 중복 초기화하지 마세요.

AppDelegate 전체 예제는 AppBoxSampleiOS에서 확인할 수 있습니다. 인자 전체와 반환값 해석은 SDK 초기화 페이지가 정본입니다. SNS 로그인, AppsFlyer 설정값은 각 장에서 다룹니다.

설치 확인

(옵션) 빌드가 통과해도 세 층은 별개입니다. 각 층이 잡아내는 실패가 다릅니다.
층확인 방법증명하는 것
Product 포함is*Available(): 동기, 초기화 전에도 동작 (예외: isInAppAvailable()은 항상 true)Product 추가 여부만
초기화 성공initialize callback AppBoxInitResult의 모듈별 status설정, 초기화까지
실제 동작getSDKVersion callback파이프라인 전체

설치 확인

Swift
1 print("push=\(AppBox.isPushAvailable())")
2
3 AppBox.shared.getSDKVersion { version, _ in
4 print("SDK \(version ?? "-")")
5 }
1 NSLog(@"push=%d", [AppBox isPushAvailable]);
2
3 [AppBox.shared getSDKVersionWithCompletion:^(NSString *version, NSError *error) {
4 NSLog(@"SDK %@", version ?: @"-");
5 }];

결과가 이상하면

증상돌아갈 곳
isPushAvailable() == false1단계: Product 누락
initialize status가 .FAILED/.SKIPPED3단계: 초기화 설정 누락
getSDKVersion callback이 실패3단계: 초기화 미실행 의심
스캐너 호출이 -5002로 실패2단계: NSCameraUsageDescription 누락

동작하는 예제가 필요하면 AppBoxSampleiOS. 올리려는 버전이 실제로 어떻게 연동되는지는 같은 태그에서 확인하세요.

다음 단계

푸시를 추가했다면 Push 장에서 delegate 연결을, 관리 화면을 열려면 AppBox 화면 시작에서 AppBox.start(from:)을, 앱이 만든 WebView에 브릿지를 연결하려면 자체 WebView 연동 장을 이어서 보세요.
www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.