Native In-App | Appbox Android SDK 가이드

Android SDK 연동

Native In-App 개요

전제내용
필요 artifactappbox-inapp + 초기화 설정의 inApp (예외는 함수별 표기)
전제 미충족 시콜백 error로 AppBoxInAppUnavailableException 또는 AppBoxInAppNotConfiguredException → 예외 카탈로그
콘솔, 서버 전제캠페인 생성과 캠페인 코드 발급은 AppBox 콘솔에서 합니다 (캠페인 설정 가이드)
웹 브릿지 대응inapp.requestShow: 관리 화면 전용. 고객 WebView에서는 -8000으로 차단되며, 네이티브에서는 showInAppCampaign을 사용합니다

표시 대상과 옵트인

표시 대상은 초기화 설정 AppBoxInAppConfig.displayScope가 결정합니다.

displayScope동작
ALL_SCREENS (기본)사일런트 Push 캠페인이 화면 종류, onInAppResume 호출과 무관하게 표시
OPTED_IN_SCREENS_ONLYonInAppResume을 호출한 화면만 표시 대상. 옵트인은 onInAppPause에 해제되므로 매 onResume마다 호출

전체 흐름: 사일런트 Push 도착 → 캠페인 동기화(setInAppSyncListener) → 표시 대기열 → 노출 조건 통과 시 표시. 관리 화면 메인은 SDK가 이미 연결합니다.

표시 화면 등록

현재 Activity를 In-App 메시지 표시 대상으로 등록하고 표시 조건을 평가합니다. OPTED_IN_SCREENS_ONLY 구성에서 메시지를 띄울 화면의 onResume()마다 호출합니다.

표시 화면 등록

AppBox.onInAppResume(activity, delayMillis, callback)

Kotlin
1 override fun onResume() {
2 super.onResume()
3 AppBox.onInAppResume(this) { success, error ->
4 if (!success) Log.w("AppBox", error?.message ?: "In-App 평가 요청 실패")
5 }
6 }
7
8 // 평가 시점을 조절하려면: 무인자 형태는 즉시가 아니라 500ms 지연 후 평가입니다
9 AppBox.onInAppResume(this, 0L) { success, error -> } // 즉시
10 AppBox.onInAppResume(this, 1000L) { success, error -> } // 1초 뒤
1 @Override
2 protected void onResume() {
3 super.onResume();
4 AppBox.onInAppResume(this, new AppBoxOperationCallback() {
5 @Override
6 public void onComplete(boolean success, Throwable error) {
7 if (!success) Log.w("AppBox", String.valueOf(error));
8 }
9 });
10 }
11
12 // 평가 시점을 조절하려면: 무인자 형태는 즉시가 아니라 500ms 지연 후 평가입니다
13 AppBox.onInAppResume(this, 0L, new AppBoxOperationCallback() {
14 @Override
15 public void onComplete(boolean success, Throwable error) { }
16 });

Request 항목 정의

Request 항목필수여부설명기본값
activity필수메시지를 표시할 foreground Activity-
delayMillis-평가 전 지연 시간(ms). 음수는 0으로 보정됩니다500
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success평가 요청 전달 성공 여부 (true | false)


Activity의 onResume()에서 직접 호출합니다. 함수 이름이 callback처럼 보이지만 SDK가 Activity lifecycle을 자동으로 가로채지 않습니다. AppBox 관리 화면의 메인 화면은 SDK가 이미 연결합니다. 같은 Activity에서 추가로 호출하면 중복 평가됩니다. displayScope = ALL_SCREENS(기본)에서는 사일런트 Push 캠페인 표시가 이 함수의 호출 여부와 무관합니다 → Native In-App 개요.

표시 화면 해제

현재 Activity를 In-App 메시지 표시 대상에서 제외합니다. onInAppResume을 호출한 Activity의 onPause()에서 반드시 짝을 맞춰 호출합니다.

표시 화면 해제

AppBox.onInAppPause(activity, callback)

Kotlin
1 override fun onPause() {
2 AppBox.onInAppPause(this) { success, error -> }
3 super.onPause()
4 }
1 @Override
2 protected void onPause() {
3 AppBox.onInAppPause(this, new AppBoxOperationCallback() {
4 @Override
5 public void onComplete(boolean success, Throwable error) { }
6 });
7 super.onPause();
8 }

Request 항목 정의

Request 항목필수여부설명기본값
activity필수표시 대상에서 제외할 Activity-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success해제 처리 성공 여부 (true | false)


super.onPause() 전에 호출합니다. 표시 중인 메시지가 닫히고 대기 중인 표시 요청이 정리됩니다. 화면 회전처럼 설정 변경으로 인한 일시 중지에서는 표시 세션이 강제로 종료되지 않습니다. OPTED_IN_SCREENS_ONLY인 경우 이 호출로 해당 화면의 옵트인이 해제됩니다. 이후 사일런트 Push가 도착하면 캠페인 동기화만 수행되고 표시되지 않으며, 다시 옵트인 화면에 진입할 때 재평가됩니다.

조건에 맞는 메시지 표시 요청

현재 조건에 맞는 In-App 메시지가 있으면 표시를 요청합니다. 화면 진입 외의 시점(탭 전환, 특정 동작 완료 등)에 노출 기회를 주고 싶을 때 호출합니다.

조건에 맞는 메시지 표시 요청

AppBox.showInAppIfAvailable(activity, callback)

Kotlin
1 AppBox.showInAppIfAvailable(this) { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "In-App 표시 요청 실패")
3 }
1 AppBox.showInAppIfAvailable(this, new AppBoxOperationCallback() {
2 @Override
3 public void onComplete(boolean success, Throwable error) {
4 if (!success) Log.w("AppBox", String.valueOf(error));
5 }
6 });

Request 항목 정의

Request 항목필수여부설명기본값
activity필수메시지를 표시할 foreground Activity-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success표시 요청 처리 성공 여부 (true | false)


강제 표시 함수가 아닙니다. 서버 노출 조건, 캠페인 기간, 노출 빈도, 오늘 보지 않기 설정을 모두 통과한 경우에만 표시됩니다. 표시할 메시지가 없거나 이미 다른 메시지가 떠 있어도 성공으로 처리됩니다. success == true로 노출 여부를 판단할 수 없습니다. displayScope 설정과 무관하게 호출한 화면에서 평가, 표시되며, 호출하면 해당 화면이 옵트인 상태로도 기록됩니다.

특정 캠페인 표시 요청

캠페인 코드로 지정한 In-App 메시지의 표시를 요청합니다. 특정 버튼이나 이벤트에 특정 캠페인을 연결할 때 호출합니다.

특정 캠페인 표시 요청

AppBox.showInAppCampaign(activity, campaignCode, callback)

Kotlin
1 AppBox.showInAppCampaign(this, "<CAMPAIGN_CODE>") { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "캠페인 표시 요청 실패")
3 }
1 AppBox.showInAppCampaign(this, "<CAMPAIGN_CODE>", new AppBoxOperationCallback() {
2 @Override
3 public void onComplete(boolean success, Throwable error) {
4 if (!success) Log.w("AppBox", String.valueOf(error));
5 }
6 });

Request 항목 정의

Request 항목필수여부설명기본값
activity필수메시지를 표시할 foreground Activity-
campaignCode필수콘솔의 캠페인 코드. 빈 문자열이면 아무 것도 하지 않고 성공합니다-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success표시 요청 처리 성공 여부 (true | false)


강제 표시 함수가 아닙니다. 캠페인 코드를 지정해도 서버 노출 조건, 기간, 빈도, 오늘 보지 않기 설정을 통과해야 표시되며, 조건에 걸려 표시되지 않아도 성공으로 처리됩니다. 전달한 Activity가 포그라운드 상태여야 합니다. 이 함수는 전달받은 Activity를 표시 대상으로 등록하므로 onInAppResume을 먼저 호출할 필요는 없습니다.

액션 listener 설정

사용자가 In-App 메시지의 버튼이나 이미지를 눌렀을 때 호출할 listener를 등록합니다. function 액션으로 앱 고유 동작을 연결할 때 사용합니다.

액션 listener 설정

AppBox.setInAppActionListener(listener, callback)

Kotlin
1 AppBox.setInAppActionListener({ event ->
2 when (event.action) {
3 "link", "external" -> Unit // SDK가 처리합니다
4 "function" -> handleCustomAction(event.actionValue)
5 "event", "conversion" -> Unit
6 }
7 }, AppBoxOperationCallback { success, error -> })
8
9 // 해제
10 AppBox.setInAppActionListener(null, AppBoxOperationCallback { success, error -> })
1 AppBox.setInAppActionListener(new AppBoxInAppActionListener() {
2 @Override
3 public void onAction(AppBoxInAppActionEvent event) {
4 if ("function".equals(event.getAction())) {
5 handleCustomAction(event.getActionValue());
6 }
7 // "link", "external"은 SDK가 처리합니다
8 }
9 }, new AppBoxOperationCallback() {
10 @Override
11 public void onComplete(boolean success, Throwable error) { }
12 });
13
14 // 해제
15 AppBox.setInAppActionListener(null, new AppBoxOperationCallback() {
16 @Override
17 public void onComplete(boolean success, Throwable error) { }
18 });

Request 항목 정의

Request 항목필수여부설명기본값
listener-AppBoxInAppActionListener. null이면 등록을 해제합니다-
callback필수등록 결과를 받는 AppBoxOperationCallback-


Response 항목 정의

Response 결과값
successlistener 등록 성공 여부 (true | false)
event.campaignCodelistener로 전달되는 캠페인 식별자
event.action실행된 동작 종류. 항상 소문자
event.actionValue동작에 설정된 값
오류등록 시 (callback): AppBoxInAppUnavailableException. appbox-inapp 미포함
이벤트 수신 시 (listener): 오류 전달 없음


listener는 알림용입니다. link와 external의 URL 열기는 SDK가 계속 담당합니다. listener에서 같은 URL을 다시 열면 화면이 두 번 열립니다.

  • action 값은 서버 설정과 무관하게 소문자로 전달됩니다.
  • 메시지 노출 자체는 listener로 전달되지 않습니다.
  • 마지막에 등록한 하나만 유지됩니다. Application.onCreate()에서 등록을 권장합니다.

In-App 동기화 listener 설정

사일런트 Push로 In-App 캠페인 동기화 신호가 도착했을 때 호출할 listener를 등록합니다. 동기화 시점에 앱 고유의 후속 처리를 연결할 때 사용합니다.

In-App 동기화 listener 설정

AppBox.setInAppSyncListener(listener)

Kotlin
1 AppBox.setInAppSyncListener { context, campaignCode, handledBySdk ->
2 Log.d("AppBox", "sync campaign=$campaignCode handled=$handledBySdk")
3 }
4
5 // 해제
6 AppBox.setInAppSyncListener(null)
1 AppBox.setInAppSyncListener(new AppBoxInAppSyncListener() {
2 @Override
3 public void onInAppSyncReceived(Context context, String campaignCode, boolean handledBySdk) {
4 Log.d("AppBox", "sync campaign=" + campaignCode + " handled=" + handledBySdk);
5 }
6 });
7
8 // 해제
9 AppBox.setInAppSyncListener(null);

Request 항목 정의

Request 항목필수여부설명기본값
listener-AppBoxInAppSyncListener. null이면 등록을 해제합니다-


Response 항목 정의

Response 결과값
contextlistener로 전달되는 context
campaignCode동기화 대상 캠페인 식별자. 값이 없으면 빈 문자열
handledBySdkSDK가 이 신호를 처리했는지 여부
오류이 함수에는 오류 전달이 없습니다. 등록은 appbox-core만으로 되지만 발화는 appbox-push가 담당합니다. appbox-push가 없으면 listener는 등록되지만 호출되지 않습니다. appbox-webview는 필요하지 않습니다.
handledBySdk의미
trueSDK가 신호를 처리함. 표시됐다는 뜻이 아님. 상세는 아래 동작 설명
false표시 조건 화면 없음, artifact 없음, 미초기화, 처리 중 예외

동기화 신호가 아닌 일반 알림 Push는 전달되지 않습니다. listener의 예외는 SDK가 삼켜 Push 처리에 영향을 주지 않습니다. 마지막에 등록한 하나만 유지됩니다. Application.onCreate()에서 등록합니다.

if (!handledBySdk) { 화면 전환 } 패턴을 In-App을 쓰지 않는 앱에 넣지 마세요. 그런 앱에서는 이 값이 항상 false라 Push마다 화면이 전환됩니다.

동작 설명

handledBySdk 판정 상세입니다.

  • true는 표시 대기열에 정상 진입한 경우 외에도, 조건에 맞는 캠페인이 없어 대기열이 비었거나 In-App 설정이 enabled = false이거나 이미 처리한 중복 Push인 경우에도 true입니다.
  • false는 표시 조건을 만족하는 화면이 없어 보류됐거나(다시 옵트인 화면에 진입할 때 재평가), appbox-inapp artifact가 없거나, In-App이 초기화되지 않았거나, 처리 중 예외가 발생한 경우입니다.
  • In-App을 실제로 사용하는 앱에서만 handledBySdk 조건 분기를 사용하세요.
www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.