local.properties에 그대로 복사해 넣고, settings.gradle.kts에 저장소를 등록하면 됩니다.AppBox Android SDK를 앱에 붙이는 절차입니다. 세 단계(저장소 접근 설정, 모듈 선언, Manifest와 초기화)를 따라 하면 끝나고, 설치 확인으로 동작까지 검증할 수 있습니다.
동작하는 앱을 먼저 보고 싶다면 AppBoxSampleAndroid. SDK 설치, 초기화, 관리 화면 실행까지의 최소 구성이 Kotlin과 Java로 들어 있습니다.
local.properties에 그대로 복사해 넣고, settings.gradle.kts에 저장소를 등록하면 됩니다.1단계: 저장소 접근 설정
항목 정의
Kakao 로그인(appbox-auth-kakao)을 쓴다면 같은 repositories 블록에 카카오 저장소를 함께 추가하세요: maven { url = uri("https://devrepo.kakao.com/nexus/content/groups/public/") }
appbox-core는 항상 필요하고, 나머지는 쓰는 기능만 넣습니다.2단계: 모듈 선언
build.gradle.kts (app)
항목 정의
| 요구사항 | 값 |
|---|---|
minSdk | 26: 미만이면 manifest 병합 실패 |
compileSdk / targetSdk | 36 |
| Java/Kotlin JVM target | 17 |
모듈 선택
| artifact | 필요한 경우 | 없으면 |
|---|---|---|
appbox-core | 항상 | SDK가 동작하지 않습니다 |
appbox-webview | AppBox 관리 화면, 웹 브릿지, 기기 기능 45개 | 기기 기능이 FEATURE_UNAVAILABLE(-5000) |
appbox-push | 푸시 알림, localPushSend | Push 함수가 FEATURE_UNAVAILABLE(-5000) |
appbox-inapp | 네이티브 인앱 메시지 | 인앱 메시지가 표시되지 않습니다 |
appbox-health | 걸음 수 | getHealthSteps가 FEATURE_UNAVAILABLE(-5000) |
appbox-appsflyer | AppsFlyer 딥링크 | 딥링크 어트리뷰션이 동작하지 않습니다 |
appbox-auth-google | Google 로그인 | 해당 provider가 목록에 없습니다 |
appbox-auth-apple | Apple 로그인 | 〃 |
appbox-auth-naver | Naver 로그인 | 〃 |
appbox-auth-kakao | Kakao 로그인 | 〃 (카카오 저장소도 필요. 1단계 참고) |
기기 기능 45개의 함수 선언은 appbox-core에 있어 appbox-webview 없이도 컴파일되고 호출까지 됩니다. 실행 파이프라인은 appbox-webview가 제공하므로, 없으면 런타임에 FEATURE_UNAVAILABLE(-5000)로 실패합니다. 빌드 성공이 동작을 보장하지 않는 지점입니다.
Application.onCreate()에서 진행합니다. 그러려면 먼저 Application 클래스가 Manifest에 등록돼 있어야 합니다.3단계: Manifest와 초기화
항목 정의
android:name에 Application 클래스를 등록하지 않으면 빌드와 실행은 성공하는데 SDK만 조용히 초기화되지 않습니다. 원인을 찾기 어려운 실패입니다.
appbox-webview가 allowBackup 등을 선언하므로 병합 충돌이 나면 해당 항목에만 tools:replace를 적용하세요.Activity.onCreate()에서 호출하지 마세요. 화면 회전으로 반복 호출됩니다. 초기화 전에 부른 다른 함수는 조용히 무시됩니다.초기화에서 정하는 값 중 두 개는 특히 주의가 필요합니다.
| 설정 | 주의 |
|---|---|
usageMode | APPBOX_WEBVIEW(AppBox 화면이 주 화면) / SERVICE_APP(앱이 자체 화면). 푸시 클릭을 어디로 보낼지가 이 값으로 갈립니다 |
common.pushIcon | 알림 small icon은 실루엣으로 마스킹되므로 흰색/투명 리소스를 쓰세요. 컬러 아이콘은 뭉개집니다 |
인자와 반환값 전체는 SDK 초기화에서 다룹니다.
google-services.json과 google-services plugin은 필요 없습니다. Firebase 콘솔에서 발급한 서버 JSON을 AppBox 콘솔에 업로드하면 SDK가 서버에서 받아 초기화합니다. (콘솔 메뉴: 빌드 > FCM 설정)
| 층 | 확인 방법 | 증명하는 것 |
|---|---|---|
| artifact 포함 | is*Available(): 동기, 초기화 전에도 동작 | 의존성 선언 여부만 |
| 초기화 성공 | initialize 반환값의 기능별 status | 설정, 초기화까지 |
| 실제 동작 | getSDKVersion 콜백 | 파이프라인 전체 |
다음 단계
설치가 끝났다면 쓰려는 기능의 장으로 이동하세요.
SDK 1.3.37+설치 확인
항목 정의
is*Available은 인자 없이 즉시 Boolean을 돌려주고, getSDKVersion은 콜백으로 받습니다. 두 계열의 호출 방식이 다릅니다.
결과가 이상하면
| 증상 | 돌아갈 곳 |
|---|---|
webview=false / push=false | 2단계: 모듈 선언에서 artifact 누락 |
status가 FAILED / SKIPPED | 3단계: Manifest와 초기화에서 초기화 설정 누락 |
getSDKVersion 콜백이 오지 않음 | 3단계: Manifest와 초기화에서 Application 등록 의심. artifact가 있어도 is*Available은 true가 나오므로 이 실패는 콜백 무응답으로만 드러납니다 |
기능 호출이 FEATURE_UNAVAILABLE(-5000) | 2단계: 모듈 선언에서 해당 artifact 미포함 |