TOAST > TOAST SDK 사용 가이드 > TOAST Push > iOS

Prerequisites

1. TOAST SDK를 설치합니다. 2. TOAST 콘솔에서 Notification > Push를 활성화합니다. 3. Push에서 AppKey를 확인합니다.

APNS 가이드

APNS 가이드

TOAST Push 구성

iOS용 TOAST Push SDK의 구성은 다음과 같습니다.

Service Cocoapods Pod Name Framework Dependency Build Settings
TOAST Push ToastPush ToastPush.framework * UserNotifications.framework

[Optional]
* PushKit.framework
Mandatory ToastCore
ToastCommon
ToastCore.framework
ToastCommon.framework
OTHER_LDFLAGS = (
"-ObjC",
"-lc++"
);

TOAST Push SDK를 Xcode 프로젝트에 적용

1. Cococapods 적용

Podfile을 생성하여 TOAST SDK에 대한 Pod을 추가합니다.

platform :ios, '8.0'
use_frameworks!

target '{YOUR PROJECT TARGET NAME}' do
    pod 'ToastPush'
end

생성된 Workspace를 열어 사용하려는 SDK를 가져옵니다(import).

#import <ToastCore/ToastCore.h>
#import <ToastPush/ToastPush.h>

2. 바이너리를 다운로드하여 TOAST SDK 적용

SDK 가져오기(import)

TOAST의 Downloads 페이지에서 전체 iOS SDK를 다운로드할 수 있습니다.

Xcode Project에 ToastPush.framework, ToastCore.framework, ToastCommon.framework, UserNotifications.framework를 추가합니다.

UserNotifications.framework는 아래 방법으로 추가할 수 있습니다.

linked_usernotifications_frameworks

TOAST Push의 VoIP 기능을 사용하려면 PushKit.framework를 추가해야 합니다.

PushKit.framework는 아래 방법으로 추가할 수 있습니다.

linked_pushkit_frameworks

linked_frameworks_push

Project Settings

Build SettingsOther Linker Flags-lc++-ObjC 항목을 추가합니다.

Project Target > Build Settings > Linking > Other Linker Flags를 클릭해 추가할 수 있습니다.

other_linker_flags

프레임워크 가져오기

사용하려는 프레임워크를 가져옵니다(import).

#import <ToastCore/ToastCore.h>
#import <ToastPush/ToastPush.h>

Capabilities Setting

TOAST Push를 사용하려면 Capabilities에서 Push Notification, Background Modes 항목을 활성화해야 합니다.

Project Target > Capabilities > Push Notification > ON

capabilities_push_notification

Project Target > Capabilities > Background Modes > ON

APNS 기능을 사용하려면 Remote notifications 항목을 활성화해야 합니다. VoIP 기능을 사용하려면 Voice over IP 항목을 활성화해야 합니다.

capabilities_background_modes

서비스 로그인

  • TOAST SDK에서 제공하는 모든 상품(Push, IAP, Log & Crash등)은 같은 사용자 ID 하나만 사용합니다.

로그인

사용자 ID가 설정되지 않은 상태에서는 토큰 등록 및 조회 기능을 사용할 수 없습니다.

// 서비스 로그인 완료 후 사용자 ID 설정
[ToastSDK setUserID:@"INPUT_USER_ID"];

로그아웃

로그아웃 하여도 등록된 알림은 해제되지 않습니다.

// 서비스 로그아웃 완료 후 사용자 ID를 nil로 설정
[ToastSDK setUserID:nil];

TOAST Push SDK 초기화

Push에서 발급받은 AppKey를 설정합니다. 초기화를 하지 않은 상태에서는 토큰 등록 및 조회 기능을 사용할 수 없습니다. Delegate 설정이 된 후 메세지 수신에 대한 통지를 받을 수 있습니다. 원활한 메세지 수신을 위해 application:didFinishLaunchingWithOptions: 함수에서 Delegate 설정을 권장합니다. 개발환경에서는 반드시 ToastPushConfiguration 의 sandbox 프로퍼티를 YES 로 설정하셔야 사용 가능합니다.

초기화 API 명세


@interface ToastPush : NSObject

// 초기화 및 Delegate 설정
+ (void)initWithConfiguration:(ToastPushConfiguration *)configuration
                     delegate:(nullable id<ToastPushDelegate>)delegate;

// Delegate 설정
+ (void)setDelegate:(nullable id<ToastPushDelegate>)delegate;

// 초기화
+ (void)initWithConfiguration:(ToastPushConfiguration *)configuration;

// 카테고리 설정
+ (void)setCategories:(nullable NSSet<UNNotificationCategory *> *)categories;

// 알림 옵션 설정
// iOS 8.0+ : UIUserNotificationType
// iOS 10.0+ : UNAuthorizationOptions
// default : UNAuthorizationOptionSound | UNAuthorizationOptionBadge
+ (void)setOptions:(NSInteger)options;

@end

Configuration API 명세

@interface ToastPushConfiguration : NSObject

// 서비스 앱키
@property (nonatomic, copy, readonly) NSString *appKey;

// 서비스 존
@property (nonatomic) ToastServiceZone serviceZone;

// 푸시 타입(APNS, VoIP)
@property (nonatomic, copy) NSSet<ToastPushType> *pushTypes;

// 국가 코드 (예약 메세지 발송시 기준 시간이 되는 국가코드)
@property (nonatomic, copy) NSString *countryCode;

// 언어 코드 (다국어 메세지 발송시 언어 선택 기준)
@property (nonatomic, copy) NSString *languageCode;

// Sandbox(Debug) 환경 설정
@property (nonatomic) BOOL sandbox;


// 앱키만 설정하여 생성
- (instancetype)initWithAppKey:(NSString *)appKey;

// 앱키, 푸시타입을 설정하여 생성
- (instancetype)initWithAppKey:(NSString *)appKey
                     pushTypes:(NSSet<ToastPushType> *)pushTypes;

@end

Delegate API 명세

토큰 등록, 토큰 해제, 푸시 수신, 알림 액션 수신 이후 추가적인 기능을 제공하려면 Delegate를 등록해야합니다.

@protocol ToastPushDelegate <NSObject>

@optional

// 토큰 등록 성공
- (void)didRegisterWithDeviceToken:(NSString *)deviceToken
                           forType:(ToastPushType)type;

// 토큰 등록 실패
- (void)didFailToRegisterForType:(ToastPushType)type
                       withError:(NSError *)error;

// 토큰 해제 성공
- (void)didUnregisterWithDeviceToken:(nullable NSString *)deviceToken
                             forType:(ToastPushType)type;

// 토큰 해제 실패
- (void)didFailToUnregisterWithDeviceToken:(NSString *)deviceToken
                                   forType:(ToastPushType)type
                                     error:(NSError *)error;

// 메세지 수신
- (void)didReceivePushMessage:(ToastPushMessage *)message
                      forType:(ToastPushType)type;

// 액션 수신 (APNS, iOS 10.0+)
- (void)didReceivePushAction:(ToastPushAction *)action API_AVAILABLE(ios(10.0));

@end

메세지 객체 API 명세

// 메세지 객체
@interface ToastPushMessage : NSObject

@property (nonatomic, readonly) NSString *identifier;

@property (nonatomic, readonly, nullable) NSString *title;

@property (nonatomic, readonly, nullable) NSString *body;

@property (nonatomic, readonly) NSInteger badge;

@property (nonatomic, readonly, nullable) ToastPushRichMessage *richMessage;

@property (nonatomic, readonly) NSDictionary<NSString *, NSString *> *payload;

@end


// 리치 메세지 객체
@interface ToastPushRichMessage : NSObject

@property (nonatomic, readonly, nullable) ToastPushMedia *media;

@property (nonatomic, readonly, nullable) NSArray<ToastPushButton *> *buttons;

@end


// 미디어 객체
@interface ToastPushMedia : NSObject

@property (nonatomic, readonly) ToastPushMediaType mediaType;

@property (nonatomic, readonly) NSString *source;

@property (nonatomic, readonly) ToastPushSourceType sourceType;

@property (nonatomic, readonly) NSString *extension;

@end


// 버튼 객체
@interface ToastPushButton : NSObject

@property (nonatomic, readonly) NSString *identifier;

@property (nonatomic, readonly) ToastPushButtonType buttonType;

@property (nonatomic, readonly) NSString *name;

@property (nonatomic, readonly, nullable) NSString *link;

@property (nonatomic, readonly, nullable) NSString *hint;

@property (nonatomic, readonly, nullable) NSString *submit;

@end

액션 객체 API 명세

typedef NS_ENUM(NSInteger, ToastPushActionType) {
    ToastPushActionDismiss = 0,
    ToastPushActionOpenApp = 1,
    ToastPushActionOpenURL = 2,
    ToastPushActionReply = 3,
};

@interface ToastPushAction : NSObject

@property (nonatomic, readonly) NSString *actionIdentifier;

@property (nonatomic, readonly) NSString *categoryIdentifier;

@property (nonatomic, readonly) ToastPushActionType actionType;

@property (nonatomic, readonly, nullable) ToastPushButton *button;

@property (nonatomic, readonly, nullable) ToastPushMessage *message;

@property (nonatomic, readonly, nullable) NSString *userText;

@end

초기화 과정 예

#import <ToastPush/ToastPush.h>

@interface AppDelegate () <UIApplicationDelegate, ToastPushDelegate>

@end


@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 앱키만 설정할 경우 pushTypes 는 기본으로 APNS 만 설정됩니다.
    ToastPushConfiguration *configuration = [[ToastPushConfiguration alloc] initWithAppKey:@"INPUT_YOUR_APPKEY"];

    // VoIP 사용 혹은 APNS 와 함께 사용할 경우 아래와 같이 NSSet 으로 설정합니다.
    configuration.pushTypes = [NSSet setWithObjects:ToastPushTypeAPNS, ToastPushTypeVoIP, nil];

#if DEBUG
    // 개발환경(Debug) 에서는 꼭 아래 sandbox 프로퍼티를 YES로 설정해야 합니다.
    configuration.sandbox = YES;
#endif

    // delegate 를 함께 설정 합니다.
    [ToastPush initWithConfiguration:configuration delegate:self];

    return YES;
}

#pragma mark - ToastPushDelegates
// 토큰 등록 성공
- (void)didRegisterWithDeviceToken:(NSString *)deviceToken
                           forType:(ToastPushType)type {
    // ...
}

// 토큰 등록 실패
- (void)didFailToRegisterForType:(ToastPushType)type
                       withError:(NSError *)error {
    // ...
}

// 토큰 해제 성공
- (void)didUnregisterWithDeviceToken:(nullable NSString *)deviceToken
                             forType:(ToastPushType)type {
    // ...
}

// 토큰 해제 실패
- (void)didFailToUnregisterWithDeviceToken:(NSString *)deviceToken
                                   forType:(ToastPushType)type
                                     error:(NSError *)error {
    // ...
}

// 메세지 수신
- (void)didReceivePushMessage:(ToastPushMessage *)message
                      forType:(ToastPushType)type {
    // ...
}

// 알림 액션(버튼) 수신 (iOS 10.0+)
- (void)didReceivePushAction:(ToastPushAction *)action {
    // ...
}

알림 옵션 설정

알림 옵션은 다음과 같이 설정되어 있습니다. 앱 실행 중 알림을 표시하기 위해서는 옵션을 변경해야 합니다.

UNAuthorizationOptionBadge | UNAuthorizationOptionSound

알림 옵션 설정 예

// default : UNAuthorizationOptionBadge | UNAuthorizationOptionSound
// 사용자가 앱을 실행 중일 때도 알림이 노출되려면 옵션을 설정을 변경해주세요.
if (@available(iOS 10.0, *)) {
    [ToastPush setOptions:UNAuthorizationOptionBadge | UNAuthorizationOptionSound | UNAuthorizationOptionAlert];

} else {
    [ToastPush setOptions:UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert];
}

토큰 등록

초기화시에 설정된 푸시 타입별로 OS 에 등록하고, 발급 받은 토큰 정보를 토스트 클라우드 서버에 등록합니다. 토큰 등록 결과는 초기화시에 설정된 Delegate를 통해 전달됩니다.

토큰 등록 API 명세

@interface ToastPush : NSObject

// ...

// 토큰 등록
+ (void)registerWithAgreement:(ToastPushAgreement *)agreement;

// ...

@end

Agreement API 명세

@interface ToastPushAgreement : NSObject

// 알림 표시 동의 여부
@property (nonatomic, assign) BOOL allowNotifications;

// 광고성 알림 표시 동의 여부
@property (nonatomic, assign) BOOL allowAdvertisements;

// 야간 광고성 알림 동의 여부
@property (nonatomic, assign) BOOL allowNightAdvertisements;

// 초기화
- (instancetype)init;

- (instancetype)initWithAllowNotifications:(BOOL)allowNotifications;

@end

토큰 등록 예

ToastPushAgreement *agreement = [[ToastPushAgreement alloc] initWithAllowNotifications:YES];

// 광고성 메세지 수신 동의 여부 설정
agreement.allowAdvertisements = YES;
// 야간 광고성 메세지 수신 동의 여부 설정
agreement.allowNightAdvertisements = NO;

[ToastPush registerWithAgreement:agreement];

토큰 조회

현재 사용자 아이디로 등록된 가장 최근 토큰과 설정정보를 조회 합니다.

토큰 조회 API 명세

@interface ToastPush : NSObject

// ...

// 토큰 조회
+ (void)requestTokenInfoForPushType:(ToastPushType)type
                  completionHandler:(nullable void (^) (ToastPushTokenInfo * _Nullable tokenInfo, NSError * _Nullable error))completionHandler;

// ...

@end

토큰 정보 API 명세

@interface ToastPushTokenInfo : NSObject

// 사용자 아이디
@property (nonatomic, readonly) NSString *userID;

// 토큰
@property (nonatomic, readonly) NSString *deviceToken;

// 국가 코드
@property (nonatomic, readonly) NSString *countryCode;

// 언어 설정
@property (nonatomic, readonly) NSString *languageCode;

// 푸시 타입
@property (nonatomic, readonly) NSString *pushType;

// 알림 표시 동의 여부
@property (nonatomic, readonly) BOOL allowNotifications;

// 광고성 알림 표시 동의 여부
@property (nonatomic, readonly) BOOL allowAdvertisements;

// 야간 광고성 알림 표시 동의 여부
@property (nonatomic, readonly) BOOL allowNightAdvertisements;

// 표준시간대
@property (nonatomic, readonly) NSString *timezone;

// 토큰 업데이트 시간
@property (nonatomic, readonly) NSString *updateDateTime;

@end

토큰 조회 예

+ (void)requestTokenInfoForPushType:(ToastPushType)type
                  completionHandler:(void (^) (ToastPushTokenInfo *tokenInfo, NSError *error))completionHandler {
                                      if (error == nil) {
                                          NSLog(@"Success : %@", tokenInfo);

                                      } else {
                                          NSLog(@"Fail : %@", error);
                                      }
                                  }];

토큰 해제

초기화시에 설정된 정보(푸쉬 타입, 샌드박스 유무)를 토대로 등록된 토큰을 해제합니다. 서비스 로그아웃 후에 메세지 수신을 원치 않으시면 토큰을 해제해 주세요. 만약 설정된 정보에 해당하는 토큰이 존재하지 않거나 해제에 성공한다면 해제 성공 Delegate를 호출합니다. 토큰 해제 결과는 초기화시에 설정된 Delegate를 통해 전달됩니다.

토큰 해제 API 명세


@interface ToastPush : NSObject

// ...

// 토큰 해제
+ (void)unregisterToken;

// ...

@end

토큰 해제 예


// ...

[ToastPush unregisterToken];

// ...

- (void)didUnregisterWithDeviceToken:(NSString *)deviceToken
                             forType:(ToastPushType)type {

    NSLog(@"Success to unregister token : %@", deviceToken);
}

- (void)didFailToUnregisterWithDeviceToken:(NSString *)deviceToken
                                   forType:(ToastPushType)type
                                     error:(NSError *)error {

    NSLog(@"Failed to unregister token, error : %@", error);
}

토큰 정보 업데이트

사용자 아이디, 국가코드, 언어코드, 메세지 동의 설정 등의 토큰 정보를 업데이트합니다. 등록되어있는 모든 토큰에 일괄 적용됩니다. 토큰 정보 업데이트 요청은 앱 실행 후 토큰 등록이 된 상태에서만 가능합니다.

토큰 정보 업데이트 API 명세

@interface ToastPush : NSObject

// ...

// 토큰 정보 업데이트
+ (void)updateTokenInfo:(ToastPushTokenInfo *)tokenInfo
      completionHandler:(nullable void (^) (NSArray<ToastPushTokenInfo *> * _Nullable results, NSError * _Nullable error))completionHandler;

// ...

@end

토큰 정보 업데이트 예


ToastPushMutableTokenInfo *tokenInfo = [[ToastPushMutableTokenInfo alloc] init];
// 업데이트하고자하는 항목만 설정
tokenInfo.languageCode = languageCode;
tokenInfo.agreement = agreement;

[ToastPush updateTokenInfo:tokenInfo
            completionHandler:^(NSArray<ToastPushTokenInfo *> *results, NSError *error) {
                if (error == nil) {
                    for (ToastPushTokenInfo *tokenInfo in results) {
                        // ...
                    }
                }
            }];

리치 메세지 수신

리치 메세지 수신은 iOS 10.0+ 이상부터 지원합니다. 알림 메세지에 미디어(이미지, 비디오, 오디오)와 버튼을 표현하기 위해서는 어플리케이션에 Notification Service Extension 이 추가되어 있어야만 합니다. Extension 의 Development Target 은 어플리케이션과 동일하게 설정하시길 권장합니다.

리치 메세지 수신 설정 예

NotificationService 클래스에 ToastPushServiceExtension 을 확장구현 해야 합니다.

#import <UserNotifications/UserNotifications.h>
#import <ToastPush/ToastPush.h>

@interface NotificationService : ToastPushServiceExtension

@end

지표 수집

클라이언트에서 푸시 메시지 수신 및 알림에 의한 애플리케이션 실행 여부가 서버에 전송됩니다. 이 내용은 통계 탭에서 확인할 수 있습니다.

수신(Received) 지표 수집 설정

수신 지표 수집은 iOS 10.0+ 이상부터 지원합니다. 수신 지표 수집을 위해서는 어플리케이션에 Notification Service Extension 이 추가되어 있어야만 합니다. Extension 의 Development Target 은 어플리케이션과 동일하게 설정하시길 권장합니다. Toast Push SDK 초기화 혹은 NotificationServiceExtension의 info.plist 파일 내부에 앱키를 설정하셔야만 지표 전송이 가능합니다.

Toast Push SDK 초기화를 통한 수신 지표 수집 설정 예

@implementation NotificationService

- (instancetype)init {
    self = [super init];

    if (self) {
        // 지표 전송에만 사용되므로 앱키만 설정하셔도 됩니다.
        ToastPushConfiguration *configuration = [[ToastPushConfiguration alloc] initWithAppKey:@"INPUT_YOUR_APPKEY"];

        [ToastPush initWithConfiguration:configuration delegate:nil];
    }

    return self;
}

@end

info.plist 설정을 통한 수신 지표 수집 설정 예

  • Property List

plist_ext

  • Source Code
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

<key>ToastSDK</key>
<dict>
    <key>ToastPush</key>
    <dict>
        <key>AppKey</key>
        <string>[INPUT_YOUR_APPKEY]</string>
    </dict>
</dict>

실행(Opened) 지표 수집 설정

실행 지표의 수집과 전송은 SDK 내부에서 자동으로 진행됩니다. Toast Push SDK 초기화 혹은 Application의 info.plist 파일 내부에 앱키를 설정하셔야만 지표 전송이 가능합니다.

info.plist 설정을 통한 수신 지표 수집 설정 예

  • Property List

plist_app

  • Source Code
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

<key>ToastSDK</key>
<dict>
    <key>ToastPush</key>
    <dict>
        <key>AppKey</key>
        <string>[INPUT_YOUR_APPKEY]</string>
    </dict>
</dict>

Notification Service Extension

iOS 10.0+ 부터 지원합니다. 리치 메세지 수신, 수신 지표 수집을 위해서는 어플리케이션에 NotificationServiceExtension을 반드시 생성 및 설정해야만 합니다.

Notification Service Extension 생성

File New > Target > iOS > Notification Service Extension

create_ext

Notification Service Extension 설정

NotificationService 클래스에 ToastPushServiceExtension 을 확장구현 해야 합니다.

#import <UserNotifications/UserNotifications.h>
#import <ToastPush/ToastPush.h>

@interface NotificationService : ToastPushServiceExtension

@end

에러 코드

// Push 기능 관련 에러 코드
static NSString *const ToastPushErrorDomain = @"com.toast.push";

typedef NS_ENUM(NSUInteger, ToastPushErrorCode) {
    ToastPushErrorUnknown               = 0,    // 알수 없음
    ToastPushErrorNotInitialize         = 1,    // 초기화하지 않음
    ToastPushErrorUserInvalid           = 2,    // 사용자 아이디 미설정
    ToastPushErrorPermissionDenied      = 3,    // 권한 획득 실패
    ToastPushErrorSystemFailed          = 4,    // 시스템에 의한 실패
    ToastPushErrorTokenInvalid          = 5,    // 토큰 값이 없거나 유효하지 않음
    ToastPushErrorAlreadyInProgress     = 6,    // 이미 진행중
    ToastPushErrorParameterInvalid      = 7,    // 매계변수 오류
};

// 네트워크 관련 에러 코드
static NSString *const ToastHttpErrorDomain = @"com.toast.http";

typedef NS_ENUM(NSUInteger, ToastHttpErrorCode) {
    ToastHttpErrorNetworkNotAvailable = 100,        // 네트워크 사용 불가
    ToastHttpErrorRequestFailed = 101,              // HTTP Status Code 가 200이 아니거나 서버에서 요청을 제대로 읽지 못함
    ToastHttpErrorRequestTimeout = 102,             // 타임아웃
    ToastHttpErrorRequestInvalid = 103,             // 잘못된 요청 (파라미터 오류 등)
    ToastHttpErrorURLInvalid = 104,                 // URL 오류
    ToastHttpErrorResponseInvalid = 105,            // 서버 응답 오류
    ToastHttpErrorAlreadyInprogress = 106,          // 동일 요청 이미 수행중
    ToastHttpErrorRequiresSecureConnection = 107,   // Allow Arbitrary Loads 미설정
};
TOP