Push | Appbox iOS SDK 가이드
Push
| 전제 | 내용 |
|---|---|
| 필요 Product | AppBoxPushSDK + 초기화 설정의 push |
| 콘솔 전제 | topic은 AppBox 콘솔에 등록된 것만 구독할 수 있습니다. 등록되지 않은 topic은 -1012로 거부됩니다 |
| 웹 브릿지 대응 | message.getToken, message.setPushAgree, message.subscribeToTopic 등 |
Push runtime 확인
Push runtime 확인
Request 항목 정의
Response 항목 정의
| Response 결과값 | |
|---|---|
Bool | Push runtime 포함 여부. 즉시 반환됩니다 |
true는 초기화 성공, OS 알림 권한 허용 또는 token 준비 상태를 의미하지 않습니다. 실제 호출 전 AppBoxInitResult.push.status도 확인합니다.
Push 권한 요청
Push 권한 요청
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
completion | 필수 | OS 알림 권한 요청 결과 callback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
granted | 사용자가 알림 권한을 허용했는지 여부 |
error | 권한 상태 조회 또는 요청 실패 원인 |
Push 초기화 성공 뒤 사용자가 요청 맥락을 이해할 수 있는 시점에 호출합니다. 권한이 허용되면 registerForRemoteNotifications()로 APNs 등록을 요청합니다. OS 권한과 서비스의 마케팅 Push 수신 동의는 서로 다른 상태입니다.
원격 알림 등록
UIApplication에 APNs 원격 알림 등록을 요청합니다.
원격 알림 등록
Request 항목 정의
Response 항목 정의
| Response 결과값 | |
|---|---|
Bool | APNs 등록 요청을 SDK가 전달했는지 여부. 즉시 반환됩니다 |
반환값은 APNs 등록 완료나 token 발급 성공을 의미하지 않습니다. 권한 허용 뒤 호출합니다. 실제 token은 AppDelegate의 등록 성공 callback에서 handleAPNSToken(_:)으로 전달합니다.
APNs token 전달
APNs token 전달
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
deviceToken | 필수 | APNs 등록 성공 callback이 전달한 원본 Data | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
Bool | token을 Push runtime에 전달했는지 여부. 즉시 반환됩니다 |
token을 문자열로 임의 변환하지 말고 원본 Data를 전달합니다. APNs token은 로그나 분석 도구에 기록하지 않습니다. AppDelegate callback을 한 경로에서만 전달합니다.
AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.
백그라운드 알림 전달
백그라운드 알림 전달
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
userInfo | 필수 | AppDelegate가 받은 원격 알림 payload | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
| 없음 | 반환값과 SDK callback이 없습니다 |
시스템의 fetchCompletionHandler는 앱에서 반드시 호출합니다. 같은 알림 payload를 여러 lifecycle 경로에서 중복 전달하지 않습니다. payload 전체를 운영 로그에 출력하지 않습니다.
AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.
포그라운드 알림 전달
포그라운드 알림 전달
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
request | 필수 | willPresent callback이 전달한 UNNotificationRequest | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
Bool | 알림 요청을 Push runtime에 전달했는지 여부. 즉시 반환됩니다 |
UNUserNotificationCenterDelegate를 앱에서 지정해야 합니다. 알림 표시 옵션은 SDK가 아니라 앱의 completionHandler에서 결정합니다. 시스템 completion handler를 반드시 호출합니다.
AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.
알림 클릭 전달
알림 클릭 전달
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
response | 필수 | 알림 클릭 callback이 전달한 UNNotificationResponse | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
| 없음 | 반환값과 SDK callback이 없습니다 |
시스템 completion handler를 반드시 호출합니다. 동일한 클릭 이벤트를 AppDelegate와 SceneDelegate 양쪽에서 중복 전달하지 않습니다.
AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.
Push token 조회
Push token 조회
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
completion | 필수 | token 조회 결과 callback | - |
Response 항목 정의
| Response 결과값 | |
|---|---|
token | 저장된 Push token. 아직 준비되지 않았으면 nil일 수 있음 |
error | 조회 실패 원인 |
Push 초기화와 APNs 등록이 완료되기 전에는 token이 없을 수 있습니다. token을 로그, crash report 또는 분석 도구에 남기지 않습니다.
Push token과 수신 동의 저장
Push token과 수신 동의 저장
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
token | 필수 | getPushToken 등으로 얻은 현재 Push token | - |
pushEnabled | 필수 | 서비스 Push 수신 동의 상태 | - |
completion | 선택 | 저장 요청 처리 결과 | nil |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | 서버 저장 요청 처리 성공 여부 |
error | 저장 요청 실패 원인 |
OS 알림 권한과 서비스 수신 동의는 별도로 관리합니다.
- token이 준비된 뒤 호출합니다.
success == true를 APNs의 실제 알림 도달 보장으로 해석하지 않습니다.- 동의하지 않은 기기도 고객사 서버가 토큰을 직접 지정하는 서버 API 개별 발송은 받습니다. 이 경로의 동의 확인은 호출하는 서버의 책임입니다.
Push segment 저장
Push segment 저장
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
segment | 필수 | Push 분류에 사용할 문자열 key-value 사전 | - |
completion | 선택 | 저장 요청 처리 결과 | nil |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | segment 저장 요청 처리 성공 여부 |
error | 저장 요청 실패 원인 |
key와 value의 실제 의미는 AppBox 콘솔의 발송 조건과 일치시킵니다. 개인정보나 인증 정보를 segment에 넣지 않습니다. success == true는 이후 모든 발송 대상 선정 완료를 보장하지 않습니다.
Topic 구독
Topic 구독
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
topic | 필수 | 구독할 topic 문자열 | - |
completion | 선택 | 구독 요청 처리 결과 | nil |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | topic 구독 요청 처리 성공 여부 |
error | 구독 요청 실패 원인 |
앞뒤 공백 제거 후 영문, 숫자, _, -만 허용하며 최대 200자입니다.
- AppBox 콘솔에 등록된 topic만 구독할 수 있습니다. 등록되지 않은 topic을 넘기면
-1012로 실패합니다. success == true는 구독 요청이 접수됐다는 의미입니다. 단말이 곧바로 알림 수신 대상이 되는 것을 보장하지 않습니다.IOS-<PROJECT_ID>같은 시스템 topic(AOS-,IOS-,INAPP-)은 서버가 처리하지 않아-1012로 실패합니다.-1011은 1.4.0에서 없어졌습니다.
Topic 구독 해제
Topic 구독 해제
Request 항목 정의
| Request 항목 | 필수여부 | 설명 | 기본값 |
|---|---|---|---|
topic | 필수 | 구독을 해제할 topic 문자열 | - |
completion | 선택 | 구독 해제 요청 처리 결과 | nil |
Response 항목 정의
| Response 결과값 | |
|---|---|
success | topic 구독 해제 요청 처리 성공 여부 |
error | 구독 해제 요청 실패 원인 |
구독과 같은 topic 형식 규칙이 적용됩니다. success == true는 해제 요청이 접수됐다는 의미입니다. IOS-<PROJECT_ID> 같은 시스템 topic(AOS-, IOS-, INAPP-)은 서버가 처리하지 않아 -1012로 실패합니다. -1011은 1.4.0에서 없어졌습니다.