Push | Appbox iOS SDK 가이드

Push

전제내용
필요 ProductAppBoxPushSDK + 초기화 설정의 push
콘솔 전제topic은 AppBox 콘솔에 등록된 것만 구독할 수 있습니다. 등록되지 않은 topic은 -1012로 거부됩니다
웹 브릿지 대응message.getToken, message.setPushAgree, message.subscribeToTopic 등

Push runtime 확인

앱 target에 Push runtime이 포함되어 있는지 확인합니다.

Push runtime 확인

AppBox.isPushAvailable() -> Bool

Swift
1 if AppBox.isPushAvailable() {
2 // Push 기능 UI를 표시할 수 있습니다.
3 }
1 if ([AppBox isPushAvailable]) {
2 // Push 기능 UI를 표시할 수 있습니다.
3 }

Request 항목 정의

인자가 없습니다.

Response 항목 정의

Response 결과값
BoolPush runtime 포함 여부. 즉시 반환됩니다


true는 초기화 성공, OS 알림 권한 허용 또는 token 준비 상태를 의미하지 않습니다. 실제 호출 전 AppBoxInitResult.push.status도 확인합니다.

Push 권한 요청

iOS 알림 권한을 사용자에게 요청합니다.

Push 권한 요청

AppBox.requestPushPermission(completion: @escaping (Bool, NSError?) -> Void)

Swift
1 AppBox.requestPushPermission { granted, error in
2 guard error == nil, granted else { return }
3 _ = AppBox.registerForRemoteNotifications()
4 }
1 [AppBox requestPushPermissionWithCompletion:^(BOOL granted, NSError *error) {
2 if (error == nil && granted) {
3 [AppBox registerForRemoteNotifications];
4 }
5 }];

Request 항목 정의

Request 항목필수여부설명기본값
completion필수OS 알림 권한 요청 결과 callback-

Response 항목 정의

Response 결과값
granted사용자가 알림 권한을 허용했는지 여부
error권한 상태 조회 또는 요청 실패 원인


Push 초기화 성공 뒤 사용자가 요청 맥락을 이해할 수 있는 시점에 호출합니다. 권한이 허용되면 registerForRemoteNotifications()로 APNs 등록을 요청합니다. OS 권한과 서비스의 마케팅 Push 수신 동의는 서로 다른 상태입니다.

원격 알림 등록

UIApplication에 APNs 원격 알림 등록을 요청합니다.

원격 알림 등록

AppBox.registerForRemoteNotifications() -> Bool

Swift
1 let requested = AppBox.registerForRemoteNotifications()
2 if !requested {
3 print("APNs 등록 요청을 전달하지 못했습니다.")
4 }
1 BOOL requested = [AppBox registerForRemoteNotifications];
2 if (!requested) {
3 NSLog(@"APNs 등록 요청을 전달하지 못했습니다.");
4 }

Request 항목 정의

인자가 없습니다.

Response 항목 정의

Response 결과값
BoolAPNs 등록 요청을 SDK가 전달했는지 여부. 즉시 반환됩니다


반환값은 APNs 등록 완료나 token 발급 성공을 의미하지 않습니다. 권한 허용 뒤 호출합니다. 실제 token은 AppDelegate의 등록 성공 callback에서 handleAPNSToken(_:)으로 전달합니다.

APNs token 전달

AppDelegate가 받은 APNs device token을 SDK에 전달합니다.

APNs token 전달

AppBox.handleAPNSToken(_ deviceToken: Data) -> Bool

Swift
1 func application(
2 _ application: UIApplication,
3 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
4 ) {
5 _ = AppBox.handleAPNSToken(deviceToken)
6 }
1 - (void)application:(UIApplication *)application
2 didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
3 [AppBox handleAPNSToken:deviceToken];
4 }

Request 항목 정의

Request 항목필수여부설명기본값
deviceToken필수APNs 등록 성공 callback이 전달한 원본 Data-

Response 항목 정의

Response 결과값
Booltoken을 Push runtime에 전달했는지 여부. 즉시 반환됩니다


token을 문자열로 임의 변환하지 말고 원본 Data를 전달합니다. APNs token은 로그나 분석 도구에 기록하지 않습니다. AppDelegate callback을 한 경로에서만 전달합니다.

AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.

백그라운드 알림 전달

백그라운드 또는 silent Push의 payload를 SDK에 전달합니다.

백그라운드 알림 전달

AppBox.handleRemoteNotification(userInfo: [AnyHashable: Any])

Swift
1 func application(
2 _ application: UIApplication,
3 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
4 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
5 ) {
6 AppBox.handleRemoteNotification(userInfo: userInfo)
7 completionHandler(.newData)
8 }
1 - (void)application:(UIApplication *)application
2 didReceiveRemoteNotification:(NSDictionary *)userInfo
3 fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
4 [AppBox handleRemoteNotificationUserInfo:userInfo];
5 completionHandler(UIBackgroundFetchResultNewData);
6 }

Request 항목 정의

Request 항목필수여부설명기본값
userInfo필수AppDelegate가 받은 원격 알림 payload-

Response 항목 정의

Response 결과값
없음반환값과 SDK callback이 없습니다


시스템의 fetchCompletionHandler는 앱에서 반드시 호출합니다. 같은 알림 payload를 여러 lifecycle 경로에서 중복 전달하지 않습니다. payload 전체를 운영 로그에 출력하지 않습니다.

AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.

포그라운드 알림 전달

앱이 foreground에 있을 때 받은 알림 요청을 SDK에 전달합니다.

포그라운드 알림 전달

AppBox.handleForegroundNotification(_ request: UNNotificationRequest) -> Bool

Swift
1 func userNotificationCenter(
2 _ center: UNUserNotificationCenter,
3 willPresent notification: UNNotification,
4 withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
5 ) {
6 _ = AppBox.handleForegroundNotification(notification.request)
7 completionHandler([.badge, .alert, .sound])
8 }
1 - (void)userNotificationCenter:(UNUserNotificationCenter *)center
2 willPresentNotification:(UNNotification *)notification
3 withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
4 [AppBox handleForegroundNotification:notification.request];
5 completionHandler(
6 UNNotificationPresentationOptionBadge |
7 UNNotificationPresentationOptionAlert |
8 UNNotificationPresentationOptionSound
9 );
10 }

Request 항목 정의

Request 항목필수여부설명기본값
request필수willPresent callback이 전달한 UNNotificationRequest-

Response 항목 정의

Response 결과값
Bool알림 요청을 Push runtime에 전달했는지 여부. 즉시 반환됩니다


UNUserNotificationCenterDelegate를 앱에서 지정해야 합니다. 알림 표시 옵션은 SDK가 아니라 앱의 completionHandler에서 결정합니다. 시스템 completion handler를 반드시 호출합니다.

AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.

알림 클릭 전달

사용자가 알림을 눌렀을 때 받은 response를 SDK에 전달합니다.

알림 클릭 전달

AppBox.movePush(_ response: UNNotificationResponse)

Swift
1 func userNotificationCenter(
2 _ center: UNUserNotificationCenter,
3 didReceive response: UNNotificationResponse,
4 withCompletionHandler completionHandler: @escaping () -> Void
5 ) {
6 AppBox.movePush(response)
7 completionHandler()
8 }
1 - (void)userNotificationCenter:(UNUserNotificationCenter *)center
2 didReceiveNotificationResponse:(UNNotificationResponse *)response
3 withCompletionHandler:(void (^)(void))completionHandler {
4 [AppBox movePushWithResponse:response];
5 completionHandler();
6 }

Request 항목 정의

Request 항목필수여부설명기본값
response필수알림 클릭 callback이 전달한 UNNotificationResponse-

Response 항목 정의

Response 결과값
없음반환값과 SDK callback이 없습니다


시스템 completion handler를 반드시 호출합니다. 동일한 클릭 이벤트를 AppDelegate와 SceneDelegate 양쪽에서 중복 전달하지 않습니다.

AppDelegate 연결 예제는 AppBoxSampleiOS에서 확인할 수 있습니다.

Push token 조회

SDK에 저장된 Push token을 조회합니다.

Push token 조회

AppBox.getPushToken(completion: @escaping (String?, NSError?) -> Void)

Swift
1 AppBox.getPushToken { token, error in
2 guard let token, error == nil else { return }
3 // token을 필요한 SDK 함수에 전달합니다.
4 }
1 [AppBox getPushTokenWithCompletion:^(NSString *token, NSError *error) {
2 if (token == nil || error != nil) {
3 return;
4 }
5 // token을 필요한 SDK 함수에 전달합니다.
6 }];

Request 항목 정의

Request 항목필수여부설명기본값
completion필수token 조회 결과 callback-

Response 항목 정의

Response 결과값
token저장된 Push token. 아직 준비되지 않았으면 nil일 수 있음
error조회 실패 원인


Push 초기화와 APNs 등록이 완료되기 전에는 token이 없을 수 있습니다. token을 로그, crash report 또는 분석 도구에 남기지 않습니다.

Push token과 수신 동의 저장

Push token과 서비스 수신 동의 상태를 저장합니다.

Push token과 수신 동의 저장

AppBox.savePushToken(_ token: String, pushEnabled: Bool, completion: ((Bool, NSError?) -> Void)?)

Swift
1 AppBox.savePushToken(token, pushEnabled: true) { success, error in
2 if !success {
3 print(error?.localizedDescription ?? "Push 설정 저장 실패")
4 }
5 }
1 [AppBox savePushToken:token
2 pushEnabled:YES
3 completion:^(BOOL success, NSError *error) {
4 if (!success) {
5 NSLog(@"%@", error.localizedDescription ?: @"Push 설정 저장 실패");
6 }
7 }];

Request 항목 정의

Request 항목필수여부설명기본값
token필수getPushToken 등으로 얻은 현재 Push token-
pushEnabled필수서비스 Push 수신 동의 상태-
completion선택저장 요청 처리 결과nil

Response 항목 정의

Response 결과값
success서버 저장 요청 처리 성공 여부
error저장 요청 실패 원인


OS 알림 권한과 서비스 수신 동의는 별도로 관리합니다.

  • token이 준비된 뒤 호출합니다.
  • success == true를 APNs의 실제 알림 도달 보장으로 해석하지 않습니다.
  • 동의하지 않은 기기도 고객사 서버가 토큰을 직접 지정하는 서버 API 개별 발송은 받습니다. 이 경로의 동의 확인은 호출하는 서버의 책임입니다.

Push segment 저장

현재 기기의 Push 대상 분류에 사용할 segment key-value를 저장합니다.

Push segment 저장

AppBox.setPushSegment(_ segment: [String: String], completion: ((Bool, NSError?) -> Void)?)

Swift
1 AppBox.setPushSegment(
2 ["membership": "gold", "region": "seoul"]
3 ) { success, error in
4 if !success {
5 print(error?.localizedDescription ?? "Segment 저장 실패")
6 }
7 }
1 [AppBox setPushSegment:@{
2 @"membership": @"gold",
3 @"region": @"seoul"
4 } completion:^(BOOL success, NSError *error) {
5 if (!success) {
6 NSLog(@"%@", error.localizedDescription ?: @"Segment 저장 실패");
7 }
8 }];

Request 항목 정의

Request 항목필수여부설명기본값
segment필수Push 분류에 사용할 문자열 key-value 사전-
completion선택저장 요청 처리 결과nil

Response 항목 정의

Response 결과값
successsegment 저장 요청 처리 성공 여부
error저장 요청 실패 원인


key와 value의 실제 의미는 AppBox 콘솔의 발송 조건과 일치시킵니다. 개인정보나 인증 정보를 segment에 넣지 않습니다. success == true는 이후 모든 발송 대상 선정 완료를 보장하지 않습니다.

Topic 구독

현재 기기를 지정한 Push topic에 구독시킵니다.

Topic 구독

AppBox.subscribeTopic(_ topic: String, completion: ((Bool, NSError?) -> Void)?)

Swift
1 AppBox.subscribeTopic("news") { success, error in
2 if !success {
3 print(error?.localizedDescription ?? "Topic 구독 실패")
4 }
5 }
1 [AppBox subscribeTopic:@"news"
2 completion:^(BOOL success, NSError *error) {
3 if (!success) {
4 NSLog(@"%@", error.localizedDescription ?: @"Topic 구독 실패");
5 }
6 }];

Request 항목 정의

Request 항목필수여부설명기본값
topic필수구독할 topic 문자열-
completion선택구독 요청 처리 결과nil

Response 항목 정의

Response 결과값
successtopic 구독 요청 처리 성공 여부
error구독 요청 실패 원인


앞뒤 공백 제거 후 영문, 숫자, _, -만 허용하며 최대 200자입니다.

  • AppBox 콘솔에 등록된 topic만 구독할 수 있습니다. 등록되지 않은 topic을 넘기면 -1012로 실패합니다.
  • success == true는 구독 요청이 접수됐다는 의미입니다. 단말이 곧바로 알림 수신 대상이 되는 것을 보장하지 않습니다.
  • IOS-<PROJECT_ID> 같은 시스템 topic(AOS-, IOS-, INAPP-)은 서버가 처리하지 않아 -1012로 실패합니다. -1011은 1.4.0에서 없어졌습니다.

Topic 구독 해제

현재 기기의 지정 Push topic 구독을 해제합니다.

Topic 구독 해제

AppBox.unsubscribeTopic(_ topic: String, completion: ((Bool, NSError?) -> Void)?)

Swift
1 AppBox.unsubscribeTopic("news") { success, error in
2 if !success {
3 print(error?.localizedDescription ?? "Topic 구독 해제 실패")
4 }
5 }
1 [AppBox unsubscribeTopic:@"news"
2 completion:^(BOOL success, NSError *error) {
3 if (!success) {
4 NSLog(@"%@", error.localizedDescription ?: @"Topic 구독 해제 실패");
5 }
6 }];

Request 항목 정의

Request 항목필수여부설명기본값
topic필수구독을 해제할 topic 문자열-
completion선택구독 해제 요청 처리 결과nil

Response 항목 정의

Response 결과값
successtopic 구독 해제 요청 처리 성공 여부
error구독 해제 요청 실패 원인


구독과 같은 topic 형식 규칙이 적용됩니다. success == true는 해제 요청이 접수됐다는 의미입니다. IOS-<PROJECT_ID> 같은 시스템 topic(AOS-, IOS-, INAPP-)은 서버가 처리하지 않아 -1012로 실패합니다. -1011은 1.4.0에서 없어졌습니다.

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