초기 설정 | Appbox Android SDK 가이드

시작하기

시작하기 개요

AppBox Android SDK를 앱에 붙이는 절차입니다. 세 단계(저장소 접근 설정, 모듈 선언, Manifest와 초기화)를 따라 하면 끝나고, 설치 확인으로 동작까지 검증할 수 있습니다.

동작하는 앱을 먼저 보고 싶다면 AppBoxSampleAndroid. SDK 설치, 초기화, 관리 화면 실행까지의 최소 구성이 Kotlin과 Java로 들어 있습니다.

1단계: 저장소 접근 설정

(필수) SDK는 GitHub Packages로 배포됩니다. 아래 두 값을 local.properties에 그대로 복사해 넣고, settings.gradle.kts에 저장소를 등록하면 됩니다.

1단계: 저장소 접근 설정

local.properties

Properties
1 gpr.user=appbox
2 gpr.key=<AppBox에 발급 문의>
settings.gradle.kts

Kotlin
1 import java.util.Properties
2
3 val localProperties = Properties().apply {
4 rootProject.projectDir.resolve("local.properties").takeIf { it.exists() }
5 ?.inputStream()?.use { load(it) }
6 }
7
8 dependencyResolutionManagement {
9 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
10 repositories {
11 google()
12 mavenCentral()
13
14 maven {
15 url = uri("https://maven.pkg.github.com/MobilePartnersCo/AppBoxSDKPackage")
16 credentials {
17 username = localProperties.getProperty("gpr.user") ?: ""
18 password = localProperties.getProperty("gpr.key") ?: ""
19 }
20 }
21 }
22 }

항목 정의

Kakao 로그인(appbox-auth-kakao)을 쓴다면 같은 repositories 블록에 카카오 저장소를 함께 추가하세요: maven { url = uri("https://devrepo.kakao.com/nexus/content/groups/public/") }

2단계: 모듈 선언

(필수) BOM을 먼저 선언하고 개별 artifact에는 버전을 적지 않습니다. appbox-core는 항상 필요하고, 나머지는 쓰는 기능만 넣습니다.

2단계: 모듈 선언

build.gradle.kts (app)

Kotlin
1 dependencies {
2 // BOM이 모듈 간 버전을 맞춰 줍니다. 개별 artifact에 버전을 적지 마세요.
3 implementation(platform("com.appboxapp.sdk:appbox-bom:1.4.0"))
4
5 implementation("com.appboxapp.sdk:appbox-core") // 필수
6 implementation("com.appboxapp.sdk:appbox-webview") // AppBox 관리 화면, 웹 브릿지, 기기 기능
7 implementation("com.appboxapp.sdk:appbox-push") // 푸시 알림
8 }

항목 정의

요구사항값
minSdk26: 미만이면 manifest 병합 실패
compileSdk / targetSdk36
Java/Kotlin JVM target17

모듈 선택

artifact필요한 경우없으면
appbox-core항상SDK가 동작하지 않습니다
appbox-webviewAppBox 관리 화면, 웹 브릿지, 기기 기능 45개기기 기능이 FEATURE_UNAVAILABLE(-5000)
appbox-push푸시 알림, localPushSendPush 함수가 FEATURE_UNAVAILABLE(-5000)
appbox-inapp네이티브 인앱 메시지인앱 메시지가 표시되지 않습니다
appbox-health걸음 수getHealthSteps가 FEATURE_UNAVAILABLE(-5000)
appbox-appsflyerAppsFlyer 딥링크딥링크 어트리뷰션이 동작하지 않습니다
appbox-auth-googleGoogle 로그인해당 provider가 목록에 없습니다
appbox-auth-appleApple 로그인〃
appbox-auth-naverNaver 로그인〃
appbox-auth-kakaoKakao 로그인〃 (카카오 저장소도 필요. 1단계 참고)

기기 기능 45개의 함수 선언은 appbox-core에 있어 appbox-webview 없이도 컴파일되고 호출까지 됩니다. 실행 파이프라인은 appbox-webview가 제공하므로, 없으면 런타임에 FEATURE_UNAVAILABLE(-5000)로 실패합니다. 빌드 성공이 동작을 보장하지 않는 지점입니다.

  • 난독화: SDK가 consumer ProGuard 규칙을 포함하므로 release 빌드에서 켜도 되고, 앱에서 별도 규칙을 추가할 필요가 없습니다.

3단계: Manifest와 초기화

(필수) 초기화는 Application.onCreate()에서 진행합니다. 그러려면 먼저 Application 클래스가 Manifest에 등록돼 있어야 합니다.

3단계: Manifest와 초기화

AndroidManifest.xml

XML
1 <uses-permission android:name="android.permission.INTERNET" />
2
3 <application
4 android:name=".MainApplication"
5 android:allowBackup="false"
6 android:fullBackupContent="false">
7 </application>
MainApplication.kt

Kotlin
1 class MainApplication : Application() {
2
3 override fun onCreate() {
4 super.onCreate()
5
6 val result = AppBox.initialize(
7 context = this,
8 config = AppBoxInitConfig(
9 common = AppBoxCommonConfig(
10 projectId = "<PROJECT_ID>", // AppBox 콘솔에서 발급합니다
11 pushIcon = R.mipmap.ic_launcher, // 알림 small icon. 흰색/투명 리소스 권장
12 debugMode = BuildConfig.DEBUG
13 ),
14 push = AppBoxPushConfig()
15 )
16 )
17
18 if (result.core.status != AppBoxInitStatus.INITIALIZED) {
19 Log.w("AppBox", result.core.error?.message ?: result.core.message ?: "core init failed")
20 }
21 }
22 }
1 public class MainApplication extends Application {
2
3 @Override
4 public void onCreate() {
5 super.onCreate();
6
7 AppBoxInitConfig config = new AppBoxInitConfig.Builder()
8 .setCommon(new AppBoxCommonConfig.Builder()
9 .setProjectId("<PROJECT_ID>") // AppBox 콘솔에서 발급합니다
10 .setPushIcon(R.mipmap.ic_launcher) // 알림 small icon. 흰색/투명 리소스 권장
11 .setDebugMode(BuildConfig.DEBUG)
12 .build())
13 .setPush(new AppBoxPushConfig.Builder().build())
14 .build();
15
16 AppBoxInitResult result = AppBox.initialize(this, config);
17
18 if (result.getCore().getStatus() != AppBoxInitStatus.INITIALIZED) {
19 Log.w("AppBox", String.valueOf(result.getCore().getMessage()));
20 }
21 }
22 }

항목 정의

android:name에 Application 클래스를 등록하지 않으면 빌드와 실행은 성공하는데 SDK만 조용히 초기화되지 않습니다. 원인을 찾기 어려운 실패입니다.

  • appbox-webview가 allowBackup 등을 선언하므로 병합 충돌이 나면 해당 항목에만 tools:replace를 적용하세요.
  • Activity.onCreate()에서 호출하지 마세요. 화면 회전으로 반복 호출됩니다. 초기화 전에 부른 다른 함수는 조용히 무시됩니다.

초기화에서 정하는 값 중 두 개는 특히 주의가 필요합니다.

설정주의
usageModeAPPBOX_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 콜백파이프라인 전체

다음 단계

설치가 끝났다면 쓰려는 기능의 장으로 이동하세요.

설치 확인

Kotlin
1 Log.d("AppBox", "webview=${AppBox.isWebViewAvailable()} push=${AppBox.isPushAvailable()}")
2
3 // SDK 버전은 콜백으로 받습니다. 이 콜백이 응답하면 파이프라인 전체가 동작하는 것입니다
4 AppBox.getSDKVersion { version, error ->
5 Log.d("AppBox", "SDK $version")
6 }
1 Log.d("AppBox", "webview=" + AppBox.isWebViewAvailable()
2 + " push=" + AppBox.isPushAvailable());
3
4 // SDK 버전은 콜백으로 받습니다. 이 콜백이 응답하면 파이프라인 전체가 동작하는 것입니다
5 AppBox.getSDKVersion((version, error) ->
6 Log.d("AppBox", "SDK " + version));

항목 정의

is*Available은 인자 없이 즉시 Boolean을 돌려주고, getSDKVersion은 콜백으로 받습니다. 두 계열의 호출 방식이 다릅니다.

결과가 이상하면

증상돌아갈 곳
webview=false / push=false2단계: 모듈 선언에서 artifact 누락
status가 FAILED / SKIPPED3단계: Manifest와 초기화에서 초기화 설정 누락
getSDKVersion 콜백이 오지 않음3단계: Manifest와 초기화에서 Application 등록 의심. artifact가 있어도 is*Available은 true가 나오므로 이 실패는 콜백 무응답으로만 드러납니다
기능 호출이 FEATURE_UNAVAILABLE(-5000)2단계: 모듈 선언에서 해당 artifact 미포함
  • 올리려는 버전이 실제로 어떻게 붙는지는 AppBoxSampleAndroid에서 같은 태그를 확인하세요.
www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.