Android SDK 연동
Push 개요
| 전제 | 내용 |
|---|---|
| 필요 artifact | appbox-push + 초기화 설정의 push (예외는 함수별 표기) |
| 전제 미충족 시 | 콜백 error로 AppBoxPushUnavailableException(artifact 없음) 또는 AppBoxPushNotConfiguredException(설정 없음) → 예외 카탈로그 |
| 콘솔, 서버 전제 | topic 등록은 서버에서 관리합니다. 등록되지 않은 topic은 필터되어 무시됩니다(호출은 성공 처리) |
| 웹 브릿지 대응 | message.setPushAgree, getToken, getPushList, subscribeToTopic, unsubscribeFromTopic, setChannelPhoneNumber |
클릭 라우팅
수신 → 표시 → 클릭. 클릭의 목적지는 초기화 설정의 usageMode가 결정합니다.
| usageMode | 클릭하면 |
|---|---|
APPBOX_WEBVIEW | AppBox 관리 화면으로 이동 |
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 을 구독, 해제하지 않습니다.
알림 권한 상태 확인
알림 권한 상태 확인
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| callback | 필수 | AppBoxValueCallback<Boolean> | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
granted | 알림 권한 허용 여부 (true | false) |
예외적으로 appbox-push artifact만 있으면 동작합니다. 초기화 설정에 push가 없어도 호출할 수 있습니다. 이 값은 OS 권한 상태입니다. 서비스의 Push 수신 동의(Push 수신 동의 저장)와 다릅니다.
알림 권한 요청
알림 권한 요청
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 조회
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| callback | 필수 | AppBoxValueCallback<String> | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
token | 현재 Push token 문자열. 실패 시 null |
token을 서버에 등록하는 별도 작업은 필요하지 않습니다. SDK가 자동으로 동기화합니다. token은 민감한 값입니다. 원문을 로그에 출력하지 않습니다.
웹 브릿지에서는 푸시 토큰 요청의 message.getToken입니다.
Push 수신 동의 저장
Push 수신 동의 저장
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| agreed | 필수 | true는 수신 동의, false는 수신 거부 | - |
| callback | 필수 | AppBoxOperationCallback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 저장 요청 성공 여부 (true | false) |
이 값은 서비스 수신 동의입니다. OS 알림 권한과 별개입니다. 조회 함수 getPushAgree는 동의값과 OS 권한을 함께 판정하므로 저장값과 1:1로 대응하지 않습니다. 저장값 표시가 필요하면 앱에서 따로 보관하세요. 동의하지 않은 기기도 고객사 서버가 토큰을 직접 지정하는 서버 API 개별 발송은 받습니다. 이 경로의 동의 확인은 호출하는 서버의 책임입니다.
웹 브릿지에서는 푸시 허용 등록의 message.setPushAgree입니다.
채널 전화번호 저장
채널 전화번호 저장
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| phoneNumber | 필수 | 국가번호를 포함한 형식을 권장합니다. 빈 값이면 오류 | - |
| consent | - | SMS, 알림 채널 수신 동의값. 생략하면 서버 요청에서 제외됩니다 | 생략 |
| callback | 필수 | AppBoxOperationCallback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 저장 요청 성공 여부 (true | false) |
consent는 채널 수신 동의입니다. Push 수신 동의(setPushAgreement)와 다른 값입니다. 전화번호는 개인정보입니다. 수집 근거를 먼저 확보하고 로그에 남기지 않습니다. appbox-webview는 필요하지 않습니다.
웹 브릿지에서는 message.setChannelPhoneNumber입니다.
Topic 하나 구독
Topic 하나 구독
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| topic | 필수 | 구독할 topic 이름 | - |
| callback | 필수 | AppBoxOperationCallback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 서버에 변경 기록 요청이 접수됐는지 (true | false) |
topic 공통 의미론을 따릅니다. success는 접수 의미이며 실제 구독 상태를 보장하지 않습니다.
웹 브릿지에서는 메시지 구독 등록의 message.subscribeToTopic입니다.
Topic 여러 개 구독
Topic 여러 개 구독
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| topics | 필수 | 구독할 topic 이름 목록 | - |
| callback | 필수 | AppBoxOperationCallback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 서버에 변경 기록 요청이 접수됐는지 (true | false) |
topic 공통 의미론을 따릅니다. 특히 부분 실패, 롤백 없음: 요청 전체가 반영되거나 전체가 오류로 끝납니다.
웹 브릿지에서는 메시지 구독 등록의 message.subscribeToTopic입니다.
Topic 하나 구독 해제
Topic 하나 구독 해제
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| topic | 필수 | 해제할 topic 이름 | - |
| callback | 필수 | AppBoxOperationCallback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 서버에 변경 기록 요청이 접수됐는지 (true | false) |
topic 공통 의미론을 따릅니다. 수신을 끄려면 topic 해제가 아니라 setPushAgreement(false) 를 사용합니다.
웹 브릿지에서는 메시지 구독 해지의 message.unsubscribeFromTopic입니다.
Topic 여러 개 구독 해제
Topic 여러 개 구독 해제
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| topics | 필수 | 해제할 topic 이름 목록 | - |
| callback | 필수 | AppBoxOperationCallback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 서버에 변경 기록 요청이 접수됐는지 (true | false) |
topic 공통 의미론을 따릅니다. 부분 실패, 롤백 없음 규칙이 적용됩니다.
웹 브릿지에서는 메시지 구독 해지의 message.unsubscribeFromTopic입니다.
Push 수신 목록 조회
Push 수신 목록 조회
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| context | 필수 | Application 또는 Activity context | - |
| fromDate | - | 시작일. yyyyMMdd | 없음 |
| toDate | - | 종료일. yyyyMMdd | 없음 |
| callback | 필수 | AppBoxValueCallback<List<AppBoxPushHistoryItem>> | - |
| fromDate | toDate | 조회 범위 |
|---|---|---|
| 없음 | 없음 | 전체 |
| 값 | 없음 | 해당 날짜 하루 |
| 값 | 값 | 시작일과 종료일 포함 |
| 없음 | 값 | 오류 |
Response 항목 정의
| Response 결과값 | |
|---|---|
items | List<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 설정
SERVICE_APP 모드에서 클릭의 목적지를 앱이 직접 결정할 때 필수입니다.Push 클릭 listener 설정
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
| listener | - | PushEventListener. null이면 등록을 해제합니다 | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
payload.title, payload.message | listener로 전달되는 알림 제목과 본문 |
payload.paramType | 클릭 동작 종류 |
payload.param | 클릭 동작에 설정된 값 |
| 오류 | 이 listener에는 오류 전달이 없습니다. |
마지막에 등록한 하나만 유지됩니다. Application.onCreate()에서 등록해야 종료 상태의 클릭을 놓치지 않으며, null이면 해제됩니다. PushEventListener는 fun interface가 아니므로 Kotlin에서도 람다를 쓸 수 없습니다. 기본 구성(usageMode = SERVICE_APP)에서 SDK는 화면을 이동시키지 않습니다. 목적지 결정은 앱의 몫입니다 → Push 개요.