Android SDK 연동

Push 개요

전제내용
필요 artifactappbox-push + 초기화 설정의 push (예외는 함수별 표기)
전제 미충족 시콜백 error로 AppBoxPushUnavailableException(artifact 없음) 또는 AppBoxPushNotConfiguredException(설정 없음) → 예외 카탈로그
콘솔, 서버 전제topic 등록은 서버에서 관리합니다. 등록되지 않은 topic은 필터되어 무시됩니다(호출은 성공 처리)
웹 브릿지 대응message.setPushAgree, getToken, getPushList, subscribeToTopic, unsubscribeFromTopic, setChannelPhoneNumber

클릭 라우팅

수신 → 표시 → 클릭. 클릭의 목적지는 초기화 설정의 usageMode가 결정합니다.

usageMode클릭하면
APPBOX_WEBVIEWAppBox 관리 화면으로 이동
SERVICE_APP (기본)SDK는 이동하지 않음. 앱이 setPushEventListener payload로 직접 처리

listener는 Application.onCreate()에서 등록하세요.

topic 규칙 요약

구독, 해제 4개 함수의 공통 계약입니다. 상세 동작은 아래 동작 설명에 있습니다.

상황동작
success == true서버 접수 의미: 실제 구독 상태를 보장하지 않음
미등록 topic걸러지고 성공 처리 (무엇이 걸러졌는지 알 수 없음)
부분 실패없음. 전체 반영 또는 전체 오류
AOS-<PROJECT_ID>1.4.0부터 SDK 보호 topic 이 아닙니다. 서버가 시스템 topic 으로 보고 처리하지 않으므로 구독, 해제 모두 반영되지 않습니다(네이티브는 성공으로 끝나지만 아무 것도 바뀌지 않음, 웹 브릿지는 failed). 수신을 끄려면 setPushAgreement(false)
웹 브릿지topic별 succeeded/failed 배열 반환 (네이티브와 다름)

동작 설명

topic 구독, 해제 요청은 다음 순서로 처리됩니다.

  • success == true는 서버가 변경 요청을 접수했다는 의미입니다. FCM 구독, 해제는 서버가 기기 토큰으로 대행하므로 이 값으로 실제 구독 상태를 확인할 수 없습니다.
  • 서버가 요청한 topic을 모두 거부해도 success == true입니다. 등록되지 않은 topic 이름을 보낸 경우가 여기에 해당하며, 어떤 topic이 걸러졌는지는 응답으로 알 수 없습니다.
  • 부분 실패나 롤백이라는 상태가 없습니다. 어느 단계든 실패하면 요청 전체가 오류로 끝나고 아무 topic도 반영되지 않으며, 성공하면 filter를 통과한 topic 전체가 한 번에 반영됩니다.
  • 앞뒤 공백이 제거되고 빈 값과 중복이 정리됩니다. 처리할 대상이 남지 않으면 아무 것도 하지 않고 성공으로 끝납니다.
  • 수신 동의는 topic 이 아니라 토큰 등록의 동의값으로 서버에 반영됩니다. 동의하지 않은 기기는 콘솔 전체 발송, 구독 그룹, 여정, API 그룹 발송에서 빠집니다. SDK 가 수신 동의에 맞춰 topic 을 구독, 해제하지 않습니다.

알림 권한 상태 확인

현재 앱의 시스템 알림 권한 상태를 확인합니다. 푸시 설정 화면의 토글 초기값을 그릴 때 사용합니다.

알림 권한 상태 확인

AppBox.isPushPermissionGranted(context, callback)

Kotlin
1 AppBox.isPushPermissionGranted(this) { granted, error ->
2 if (error != null) return@isPushPermissionGranted
3 updatePushToggle(granted == true)
4 }
1 AppBox.isPushPermissionGranted(this, new AppBoxValueCallback<Boolean>() {
2 @Override
3 public void onComplete(Boolean granted, Throwable error) {
4 if (error != null) return;
5 updatePushToggle(Boolean.TRUE.equals(granted));
6 }
7 });

Request 항목 정의

Request 항목필수여부설명기본값
context필수Application 또는 Activity context-
callback필수AppBoxValueCallback<Boolean>-


Response 항목 정의

Response 결과값
granted알림 권한 허용 여부 (true | false)


예외적으로 appbox-push artifact만 있으면 동작합니다. 초기화 설정에 push가 없어도 호출할 수 있습니다. 이 값은 OS 권한 상태입니다. 서비스의 Push 수신 동의(Push 수신 동의 저장)와 다릅니다.

알림 권한 요청

시스템 알림 권한을 요청합니다. 온보딩이나 푸시 설정 화면에서 사용자에게 권한을 물을 때 호출합니다.

알림 권한 요청

AppBox.requestPushPermission(activity, callback)

Kotlin
1 AppBox.requestPushPermission(this) { granted, error ->
2 when {
3 error is AppBoxPushPromptInterruptedException -> Unit // 거부가 아님
4 granted == true -> enablePushUi()
5 else -> showNotificationSettingsGuide()
6 }
7 }
1 AppBox.requestPushPermission(this, new AppBoxValueCallback<Boolean>() {
2 @Override
3 public void onComplete(Boolean granted, Throwable error) {
4 if (error instanceof AppBoxPushPromptInterruptedException) {
5 return; // 거부가 아님
6 }
7 if (Boolean.TRUE.equals(granted)) {
8 enablePushUi();
9 } else {
10 showNotificationSettingsGuide();
11 }
12 }
13 });

Request 항목 정의

Request 항목필수여부설명기본값
activity필수권한 다이얼로그를 표시할 foreground Activity. Application context는 쓸 수 없습니다-
callback필수AppBoxValueCallback<Boolean>-


Response 항목 정의

Response 결과값
granted = true, error = null사용자가 허용
granted = false, error = null사용자가 거부
granted = null, error = AppBoxPushPromptInterruptedException사용자가 응답하지 않고 프롬프트가 종료됨
오류AppBoxPushPromptInterruptedException: 홈 화면 이동, 화면 잠금으로 프롬프트가 응답 없이 닫힘


응답 없이 종료된 상태를 거부로 저장하지 마세요. 사용자의 의사 표시가 아니며, 거부로 저장하면 사용자를 잘못 옵트아웃시킵니다. Android 13 이상에서는 시스템 다이얼로그가 표시됩니다. Android 12 이하에서는 다이얼로그 없이 현재 알림 활성화 상태가 반환됩니다. 예외적으로 appbox-push artifact만 있으면 동작합니다.

Push token 조회

현재 기기의 Push token을 조회합니다. 자체 서버나 외부 도구에서 이 기기를 식별해야 할 때의 상태 확인 용도입니다.

Push token 조회

AppBox.getPushToken(context, callback)

Kotlin
1 AppBox.getPushToken(this) { token, error ->
2 if (error != null) return@getPushToken
3 Log.d("AppBox", "token length=${token?.length}") // 원문은 로그에 남기지 않습니다
4 }
1 AppBox.getPushToken(this, new AppBoxValueCallback<String>() {
2 @Override
3 public void onComplete(String token, Throwable error) {
4 if (error != null) return;
5 Log.d("AppBox", "token length=" + (token == null ? 0 : token.length()));
6 }
7 });

Request 항목 정의

Request 항목필수여부설명기본값
context필수Application 또는 Activity context-
callback필수AppBoxValueCallback<String>-


Response 항목 정의

Response 결과값
token현재 Push token 문자열. 실패 시 null


token을 서버에 등록하는 별도 작업은 필요하지 않습니다. SDK가 자동으로 동기화합니다. token은 민감한 값입니다. 원문을 로그에 출력하지 않습니다.

웹 브릿지에서는 푸시 토큰 요청의 message.getToken입니다.

Push 수신 동의 저장

서비스의 Push 수신 동의값을 저장합니다. 서비스 약관, 마케팅 동의 화면에서 사용자의 선택을 반영할 때 호출합니다.

Push 수신 동의 저장

AppBox.setPushAgreement(context, agreed, callback)

Kotlin
1 AppBox.setPushAgreement(this, true) { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "수신 동의 저장 실패")
3 }
1 AppBox.setPushAgreement(this, true, 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 항목필수여부설명기본값
context필수Application 또는 Activity context-
agreed필수true는 수신 동의, false는 수신 거부-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success저장 요청 성공 여부 (true | false)


이 값은 서비스 수신 동의입니다. OS 알림 권한과 별개입니다. 조회 함수 getPushAgree는 동의값과 OS 권한을 함께 판정하므로 저장값과 1:1로 대응하지 않습니다. 저장값 표시가 필요하면 앱에서 따로 보관하세요. 동의하지 않은 기기도 고객사 서버가 토큰을 직접 지정하는 서버 API 개별 발송은 받습니다. 이 경로의 동의 확인은 호출하는 서버의 책임입니다.

웹 브릿지에서는 푸시 허용 등록의 message.setPushAgree입니다.

채널 전화번호 저장

SMS 및 알림 채널에서 사용할 전화번호를 저장합니다. 문자 채널 발송 대상에 이 기기의 번호를 연결할 때 호출합니다.

채널 전화번호 저장

AppBox.setChannelPhoneNumber(context, phoneNumber, consent, callback)

Kotlin
1 // 채널 수신 동의를 함께 저장
2 AppBox.setChannelPhoneNumber(this, "+821000000000", true) { success, error ->
3 if (!success) Log.w("AppBox", error?.message ?: "전화번호 저장 실패")
4 }
5
6 // 동의값 없이 전화번호만 저장
7 AppBox.setChannelPhoneNumber(this, "+821000000000") { success, error -> }
1 // 채널 수신 동의를 함께 저장
2 AppBox.setChannelPhoneNumber(this, "+821000000000", true, new AppBoxOperationCallback() {
3 @Override
4 public void onComplete(boolean success, Throwable error) {
5 if (!success) Log.w("AppBox", String.valueOf(error));
6 }
7 });
8
9 // 동의값 없이 전화번호만 저장
10 AppBox.setChannelPhoneNumber(this, "+821000000000", new AppBoxOperationCallback() {
11 @Override
12 public void onComplete(boolean success, Throwable error) { }
13 });

Request 항목 정의

Request 항목필수여부설명기본값
context필수Application 또는 Activity context-
phoneNumber필수국가번호를 포함한 형식을 권장합니다. 빈 값이면 오류-
consent-SMS, 알림 채널 수신 동의값. 생략하면 서버 요청에서 제외됩니다생략
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success저장 요청 성공 여부 (true | false)


consent는 채널 수신 동의입니다. Push 수신 동의(setPushAgreement)와 다른 값입니다. 전화번호는 개인정보입니다. 수집 근거를 먼저 확보하고 로그에 남기지 않습니다. appbox-webview는 필요하지 않습니다.

웹 브릿지에서는 message.setChannelPhoneNumber입니다.

Topic 하나 구독

FCM topic 하나를 구독합니다. 사용자가 알림 설정에서 관심 주제를 켰을 때 호출합니다.

Topic 하나 구독

AppBox.subscribeTopic(context, topic, callback)

Kotlin
1 AppBox.subscribeTopic(this, "notice") { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "topic 구독 실패")
3 }
1 AppBox.subscribeTopic(this, "notice", 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 항목필수여부설명기본값
context필수Application 또는 Activity context-
topic필수구독할 topic 이름-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success서버에 변경 기록 요청이 접수됐는지 (true | false)


topic 공통 의미론을 따릅니다. success는 접수 의미이며 실제 구독 상태를 보장하지 않습니다.

웹 브릿지에서는 메시지 구독 등록의 message.subscribeToTopic입니다.

Topic 여러 개 구독

FCM topic 여러 개를 한 번에 구독합니다. 알림 설정 화면에서 여러 주제를 일괄 반영할 때 호출합니다.

Topic 여러 개 구독

AppBox.subscribeTopics(context, topics, callback)

Kotlin
1 AppBox.subscribeTopics(this, listOf("notice", "marketing")) { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "topic 구독 실패")
3 }
1 AppBox.subscribeTopics(this, Arrays.asList("notice", "marketing"),
2 new AppBoxOperationCallback() {
3 @Override
4 public void onComplete(boolean success, Throwable error) {
5 if (!success) Log.w("AppBox", String.valueOf(error));
6 }
7 });

Request 항목 정의

Request 항목필수여부설명기본값
context필수Application 또는 Activity context-
topics필수구독할 topic 이름 목록-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success서버에 변경 기록 요청이 접수됐는지 (true | false)


topic 공통 의미론을 따릅니다. 특히 부분 실패, 롤백 없음: 요청 전체가 반영되거나 전체가 오류로 끝납니다.

웹 브릿지에서는 메시지 구독 등록의 message.subscribeToTopic입니다.

Topic 하나 구독 해제

FCM topic 하나의 구독을 해제합니다. 사용자가 알림 설정에서 관심 주제를 껐을 때 호출합니다.

Topic 하나 구독 해제

AppBox.unsubscribeTopic(context, topic, callback)

Kotlin
1 AppBox.unsubscribeTopic(this, "marketing") { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "topic 해제 실패")
3 }
1 AppBox.unsubscribeTopic(this, "marketing", 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 항목필수여부설명기본값
context필수Application 또는 Activity context-
topic필수해제할 topic 이름-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success서버에 변경 기록 요청이 접수됐는지 (true | false)


topic 공통 의미론을 따릅니다. 수신을 끄려면 topic 해제가 아니라 setPushAgreement(false) 를 사용합니다.

웹 브릿지에서는 메시지 구독 해지의 message.unsubscribeFromTopic입니다.

Topic 여러 개 구독 해제

FCM topic 여러 개의 구독을 한 번에 해제합니다. 알림 설정 화면에서 여러 주제를 일괄 해제할 때 호출합니다.

Topic 여러 개 구독 해제

AppBox.unsubscribeTopics(context, topics, callback)

Kotlin
1 AppBox.unsubscribeTopics(this, listOf("marketing", "event")) { success, error ->
2 if (!success) Log.w("AppBox", error?.message ?: "topic 해제 실패")
3 }
1 AppBox.unsubscribeTopics(this, Arrays.asList("marketing", "event"),
2 new AppBoxOperationCallback() {
3 @Override
4 public void onComplete(boolean success, Throwable error) {
5 if (!success) Log.w("AppBox", String.valueOf(error));
6 }
7 });

Request 항목 정의

Request 항목필수여부설명기본값
context필수Application 또는 Activity context-
topics필수해제할 topic 이름 목록-
callback필수AppBoxOperationCallback-


Response 항목 정의

Response 결과값
success서버에 변경 기록 요청이 접수됐는지 (true | false)


topic 공통 의미론을 따릅니다. 부분 실패, 롤백 없음 규칙이 적용됩니다.

웹 브릿지에서는 메시지 구독 해지의 message.unsubscribeFromTopic입니다.

Push 수신 목록 조회

기기에 저장된 Push 수신 목록을 조회합니다. 앱 안에 알림함 화면을 만들 때 사용합니다.

Push 수신 목록 조회

AppBox.getPushHistory(context, fromDate, toDate, callback)

Kotlin
1 // 전체 조회
2 AppBox.getPushHistory(this) { items, error ->
3 if (error != null) return@getPushHistory
4 renderInbox(items.orEmpty())
5 }
6
7 // 기간 조회 — 날짜 형식은 yyyyMMdd
8 AppBox.getPushHistory(this, "20260501", "20260506") { items, error ->
9 if (error != null) return@getPushHistory
10 renderInbox(items.orEmpty())
11 }
1 // 전체 조회
2 AppBox.getPushHistory(this, new AppBoxValueCallback<List<AppBoxPushHistoryItem>>() {
3 @Override
4 public void onComplete(List<AppBoxPushHistoryItem> items, Throwable error) {
5 if (error != null) return;
6 renderInbox(items == null ? Collections.emptyList() : items);
7 }
8 });
9
10 // 기간 조회 — 날짜 형식은 yyyyMMdd
11 AppBox.getPushHistory(this, "20260501", "20260506",
12 new AppBoxValueCallback<List<AppBoxPushHistoryItem>>() {
13 @Override
14 public void onComplete(List<AppBoxPushHistoryItem> items, Throwable error) {
15 if (error != null) return;
16 renderInbox(items == null ? Collections.emptyList() : items);
17 }
18 });

Request 항목 정의

Request 항목필수여부설명기본값
context필수Application 또는 Activity context-
fromDate-시작일. yyyyMMdd없음
toDate-종료일. yyyyMMdd없음
callback필수AppBoxValueCallback<List<AppBoxPushHistoryItem>>-
fromDatetoDate조회 범위
없음없음전체
값없음해당 날짜 하루
값값시작일과 종료일 포함
없음값오류


Response 항목 정의

Response 결과값
itemsList<AppBoxPushHistoryItem>. 실패 시 null
items[].id수신 항목 식별자
items[].title, items[].body알림 제목과 본문
items[].url, items[].imageUrl연결 URL과 이미지 URL
items[].createdAt수신 시각
items[].isOpened열람 여부
오류error: 날짜 형식 오류, 존재하지 않는 날짜(자동 보정하지 않음), toDate만 지정


날짜 형식은 yyyyMMdd입니다. 걸음 수 조회(getHealthSteps)는 yyyy-MM-dd로 다릅니다. 기기에 저장된 목록입니다. 서버의 발송 원본과 다를 수 있습니다.

웹 브릿지에서는 푸시 수신 리스트의 message.getPushList입니다.

Push 클릭 listener 설정

사용자가 알림을 클릭했을 때 호출할 listener를 등록합니다. SERVICE_APP 모드에서 클릭의 목적지를 앱이 직접 결정할 때 필수입니다.

Push 클릭 listener 설정

AppBox.setPushEventListener(listener)

Kotlin
1 AppBox.setPushEventListener(object : PushEventListener {
2 override fun onPushClicked(context: Context, payload: PushEventPayload) {
3 if (payload.paramType == "url") openInApp(payload.param)
4 }
5 })
6
7 // 해제
8 AppBox.setPushEventListener(null)
1 AppBox.setPushEventListener(new PushEventListener() {
2 @Override
3 public void onPushClicked(Context context, PushEventPayload payload) {
4 if ("url".equals(payload.getParamType())) openInApp(payload.getParam());
5 }
6 });
7
8 // 해제
9 AppBox.setPushEventListener(null);

Request 항목 정의

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


Response 항목 정의

Response 결과값
payload.title, payload.messagelistener로 전달되는 알림 제목과 본문
payload.paramType클릭 동작 종류
payload.param클릭 동작에 설정된 값
오류이 listener에는 오류 전달이 없습니다.

마지막에 등록한 하나만 유지됩니다. Application.onCreate()에서 등록해야 종료 상태의 클릭을 놓치지 않으며, null이면 해제됩니다. PushEventListener는 fun interface가 아니므로 Kotlin에서도 람다를 쓸 수 없습니다. 기본 구성(usageMode = SERVICE_APP)에서 SDK는 화면을 이동시키지 않습니다. 목적지 결정은 앱의 몫입니다 → Push 개요.

www.naver.com
QR 코드를 촬영하면 입력하신 주소의
앱 예시 화면을 테스트할 수 있습니다.
* 스캔 후 바로 앱 다운로드 이동합니다.