Push 모듈 적용 가이드 (iOS)

Version	Date	SVN Revision	담당자	변경 사항
3.6.0	2019-10-16		최보경	Common Module v1.5.0 이상 필수 적용 주의 : 모든 개별모듈 동시 업데이트 필요 Push 내부 로직 개선 유저 식별 중심의 ‘공지/야간공지’ 정의 시스템이 Push 토큰 중심 ‘공지/야간공지’ 로 정의되도록 개선되었습니다. 내부적으로 토큰 정보 전달 프로토콜이 변경되었고 호출 시점이 변경되었습니다. iOS 13을 대상으로 한 앱에서의 정상적인 동작을 보장 클라이언트에 저장되는 모든 프로퍼티를 iCloud 백업 대상에서 제외
3.5.2	2019-06-25		최보경	iOS 12 이상에서 Trial 푸시 전송 후 유저가 푸시 전송 여부를 결정하는 기능인 Provisional Authorization 기능 추가
3.5.1	2019-04-15	2866	최보경	32bit 단말에서 device token을 Push 서버로 전달 시 게스트 UID가 int 최대값으로 전달되는 이슈 수정
3.5.0	2019-03-14	2859	최보경	Push v4 API 적용 Push Notification 설정 필수 수정 필요 (유의사항 참고) 로컬 푸쉬에서 title 값이 노출되도록 변경 (iOS 8.2 이상) (로컬 푸쉬 등록하기 참고) UnRegister 이후 다시 token이 등록되지 않는 이슈 수정
3.3.0	2018-06-27	2841	최보경	게임 진행 도중 로컬 푸시나 리모트 푸시를 수신했을 때 노출 여부를 설정하는 기능 추가 Push Notification 설정 수정 필요 (프로젝트 설정과 푸시 활성화 소스코드 참고) Foreground Notification API 추가
3.2.8	2018-02-07	2833	최보경	iCloud 동기화 기능에 의해 복원하는 기기가 백업한 기기의 Push token data를 사용하게 되는 현상 수정
3.2.7	2017-08-11	2814	최보경	모듈 내부 서버통신 데이터에 통합 식별자 추가 언어 설정은 게임 언어를 우선시하며 게임 언어를 설정하지 않을 경우 단말 언어를 따르도록 수정
3.2.6	2017-01-26	2802	정다운	데이터 요청에 대한 네트워크 타임아웃 로직 추가
3.2.5	2016-11-21	2794	정다운	ATS(App Transport Security) 관련 대응 (모듈 내부에서 호출하는 http 도메인을 https로 변경)
3.2.4	2016-05-26	2772	정다운	서버에서 야간, 공지 동의 데이터 받아오는 시점 변경
3.2.3	2016-04-19	2768	정다운	수신동의 API 스펙 변경 삭제 Push_UserSetting 삭제 CS_pushSetPush, CS_pushGetPush 함수 삭제 추가 Push_BoolType 추가 CS_pushSetAgree, CS_pushGetAgreeNotice, CS_pushGetAgreeNight 함수 추가
3.2.2	2016-03-17	2752	김규진	야간 / 공지알림 수신동의 관련 API 추가. (C2SPush.h 참고) typedef enum { //... (중략) USER_NOTICE = 0x04, // 추가됨 USER_NIGHT = 0x08 // 추가됨 //... (중략) } Push_UserSetting; void CS_pushSetPush(const int type); // 추가됨 int CS_pushGetPush(); // 추가됨
3.2.1	2016-02-01	2751	김규진	개별 서버 설정값이 반영되도록 수정
3.2.0	2016-01-04	2737	김규진	샌드박스 환경 지원 버전 코드 수정 (안드로이드 매칭) URL 변경 (com2us.net -> qpyou.cn)
2.4.4	2015-02-06	2639	김규진	CommonModule에서 MCC, MNC 가져옴 setVID할때 죽는 문제 수정 iOS8 알림센터 설정 메뉴에서 ‘알림허용’ Off하면 server에 disable로 갱신되도록 수정 최소 빌드 버젼 iOS 6.0 으로 변경 항상, Client 정보를 Push server에 보냄.
2.4.0	2015-01-07	2628	조태형	arm64 지원 TouchJson lib 제거 (TouchJson lib 삭제하세요)
2.3.1	2014/09/30	2577	조태형, 김상우	iOS8 대응
2.3.0	2013/08/22	2462	이진우	모듈 버전 수집 기능 추가 서버 프로토콜 DID 정보 추가
2.2.0	2013/06/03	2352	김혜란	Type 필드 서버 전송 로직 추가 Deprecated Function : CS_hlpPushRegisterToken, CS_hlpPushLoadOption, CS_hlpPushUseTestServer, CS_hlpPushGetVersion Available in 2.2.0 : CS_hlpPushRegisterTokenEx, CS_hlpPushSendPromoCodeEx, CS_hlpPushUseTestServerEx, CS_hlpPushGetVersionEx AppDelegate.m 리모트 푸쉬 적용 방식 변경. Push_Version_2.1.x_to_2.2.0_Migration 확인
2.0.2	2013/02/07	2183	김혜란	서버 접근 URL 변경 UseTestServerEx() 함수 추가 단말 푸쉬 비 활성화시 서버로 Unregister 전송

모든 버전의 역사 보기

유의사항

iOS Unity Push

Push V4 적용 (Push v3.5.0 이상)

Push v3.5.0 부터는 기존의 Push 시스템(Push v4, AS-IS)이 아닌 새 Push 시스템(Push v4, TO-BE)를 제공합니다.
기존의 Push v1은 리모트 푸시를 사용 시 단말 식별자인 DID를 통해서 메시지 타겟팅을 하였다면, Push v4 는 유저 식별자인 UID를 통하여 메시지 타겟팅이 가능합니다.

Push v4를 적용하기 위해 클라이언트 로직은 크게 수정할 필요 없습니다.
다만, Push v4를 사용하기 위해선 ActiveUser 모듈과 초기화 시점을 조정하고, 유저 식별자인 UID를 서버로 전송하는 새 API를 호출해야 합니다.
아래 'Push Notification 설정 필요' 사항은 확인 바랍니다.

Push Notification 설정 필수 수정 필요 (푸시 활성화 소스코드 와 iOS Push Delegate 메소드 참고)
- 약관 노출 이후 push token을 전송해야 하기 때문에 기존 deviceToken 요청 코드 삭제. ActiveUser 초기화 완료 콜백이 돌아온 이후 CS_pushStartEx 호출 (참고 플로우 자료 위치 (1))
- 로그인/로그아웃 이후, 현재 uid를 푸시 서버로 전송하는 로직 필요. 로그인 완료 시에는 uid를 넣어서(참고 플로우 자료 위치 (2)) or 로그아웃 시에는 uid를 빈칸("")으로 하여 CS_pushSetUid 호출 (참고 플로우 자료 위치 (3))
- CS_hlpPushSendPromoCodeEx API deprecated. CS_hlpPushSendOpen API로 변경
- 주의사항! CS_pushSetUid를 호출하여 UID에 푸시 관련 정보가 매칭된 후, CS_pushGetAgreeNotice/CS_pushGetAgreeNight를 호출하여 앱에서 푸신 여부 UI를 생성에 사용해주세요.
  - CS_pushSetUid 이전에 agree/night 값을 get하려는 경우 올바른 정보가 반환되지 않을 수 있습니다.

Push Notification 관련 동작 순서

App off
- 확인(OK) 후 실행: didFinishLaunchingWithOptions: (NSDictionary *)launchOptions => launchOptions == nil
- 보기(View): didFinishLaunchingWithOptions: (NSDictionary *)launchOptions => launchOptions != nil
App Suspended
- Resume: didReceiveRemoteNotification:(NSDictionary *)userInfo
App Active
- iOS10 이상에서 push 팝업을 클릭했을 때: didReceiveRemoteNotification:(NSDictionary *)userInfo / didReceiveLocalNotification:(UILocalNotification *)notification
- iOS10 미만 : didReceiveRemoteNotification:(NSDictionary *)userInfo / didReceiveLocalNotification:(UILocalNotification *)notification (push 팝업 나타나지 않음)
App in background
- 확인(OK) 후 실행: applicationDidBecomeActive
- 보기(View): didReceiveRemoteNotification -> applicationDidBecomeActive 순서로 호출
유의사항
- iTunes 동기화나 AppStore를 통하지 않고 강제로 해킹팟에 설치하는 경우 프로파일이 등록되지 않아 Push 기능을 사용할 수 없습니다.

개발 준비

Developer Identity 설정

\Pub.com2us.kr\Y2011\MATERIAL\해외 _International\DistributionCertificate&Key\테스트용\Apple10_17

Provisioning Portal A10~17에 사용되는 공용 private key: privateKey_common_appleTest.p12, private_key_PW.txt

그 외 테스트에 필요한 Provisioning Portal의 developer identity를 등록.

퍼블리싱의 경우 적절한 Provisioning 파일을 사용하도록 한다.

App ID, 프로파일 생성 및 설정

아래 과정은 개발용으로 준비하는 프로파일들이며, 납품용은 사업부에서 지정된 담당자가 생성해서 전달해줄 것입니다 (현 담당자: 사업개발팀 오형근)

[Keychain Access] 인증 요청서(.certSigningRequest) 생성

포탈별로 생성해야하기 때문에 쉽게 구분할 수 있는 이름을 사용할 것을 권장합니다

[Provisioning Portal] App ID 생성 & 설정

일반 프로젝트와 마찬가지로 Provisioning Portal -> App IDs -> New App ID 메뉴에서 App ID를 생성한 후 App ID 목록에서 사용할 App ID 우측의 Setting을 선택하면 아래와 같은 페이지로 이동됩니다

Push Notification 활성화 후 Development SSL Certificate의 Create Certificate를 선택.

App ID, 프로파일 생성 및 설정-[Keychain Access] 인증 요청서(.certSigningRequest) 생성 단계에서 Keychain Access를 이용하여 생성한 인증 요청서(.certSigningRequest) 를 선택하고 Generate}}

[Keychain Access] 다운로드 받은 인증서 등록 및 Export

위의 단계에서 다운로드 받은 Certificate를 더블클릭하여 등록하면 Keychain Access에서 아래 그림과 같이 보이게 됩니다

우클릭 후 보내기 메뉴 선택 (혹은 파일 -> 항목 보내기)

여러 Profile을 한꺼번에 등록하는 과정에서 어느 항목이 어느 Profile에 매칭되는 항목인지 헷갈릴 수 있는데, 더블클릭 하셔서 세부 사항을 확인하시면 App ID가 표시되서 쉽게 구분하실 수 있습니다.

포털별로 생성해야하기 때문에 쉽게 구분할 수 있는 이름을 사용할 것을 권장

비번 없이 그냥 확인

본인 시스템 비밀번호를 입력하여 Export 완료

[Terminal] 인증서로 .pem 파일 생성

openssl pkcs12 -in FILENAME.p12 -out FILENAME.pem -nodes -clcerts
- B - 3 단계에서 export한 .p12 파일이 있는 경로로 이동
- FILENAME 을 위의 B - 3 과정에서 입력한 이름으로 대체하시면 됩니다.
- 위에서 Export시에 비번 입력하지 않았기 때문에 Enter Import Password: 에서 그냥 엔터 누르면 됩니다.
- .pem 파일은 App ID, 만료날짜 와 함께 Push 서버 담당자(플랫폼연구팀 MI 서상영)에게 전달

Provisioning Profile이 정상적으로 생성되었는지 검증

생성된 Provisioning Profile을 문서 편집기로 열어서 위의 스크린샷과 유사한 내용이 확인되는 경우, 해당 Provisioning Profile은 정상적으로 Push Notification 기능을 사용할 수 있음을 의미합니다. 납품용인 경우, development 대신에 production이 들어가게 됩니다. 엔터프라이즈 빌드의 경우 production 서버로 되어 있어야 합니다.

튜토리얼

프로젝트 설정

UserNotification.framework를 Optional로 추가한다. (push v3.3.0 update)

<작성법 참고>

Search Paths

프로젝트의 타겟을 클릭한 후 우측 상단의 검색창에 Search Paths를 입력합니다.
Header Search Paths와 Library Search Paths를 더블 클릭 한 후 필요한 모듈의 경로를 입력합니다.
사용자마다 모듈의 경로가 다를 수 있습니다. 자신의 경로에 맞게 적절히 입력해주세요.

Push Notification 설정

프로젝트의 Capabilities에서 Push Notification 항목을 ON 합니다.
해당 설정이 되어 있지 않을 시, 아래와 같은 문제가 발생합니다.
- iOS10 단말에서 푸시 토큰 발송되지 않음 : Missing Push Notification Entitlement 항목으로 리젝

리모트 푸쉬 활성화

Push V4 추가 적용 사항

약관 동의 이전에 deviceToken을 전송 불가. 따라서 반드시 ActiveUser 초기화 콜백을 받은 이후에 CS_pushStartEx 호출
CS_pushStartEx 를 초기화 이후에 호출하게 되어 하단처럼 기존 registerForRemoteNotifications 호출 코드 제거 필요

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
//---------- Push Notification
// Push V4 (Push 3.5.0) 에서는 아래 소스코드를 CS_pushStartEx(); 함수로 호출 가능 (기존 registerForRemoteNotifications 호출 코드 제거 필요)
// CS_pushStartEx()는 반드시 ActiveUser 초기화 콜백을 받은 이후에 호출
/*
if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0) // push v3.3.0 부터 iOS10 이상에서 앱이 실행중일 때 push 노출이 가능하다.
{
CS_pushSetUNUserNotification(); // added push v3.3.0
}
else if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 8.0)
{
[application registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge) categories:nil]];
[application registerForRemoteNotifications];

}
else
{
[application registerForRemoteNotificationTypes:
(UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert)];
}
*/

#if defined(DEBUG)
CS_hlpPushUseTestServerEx();
#endif
CS_pushRegisterCallbackHandler(callbackFunc);
CS_hlpPushDefaultActionOnLaunch((void*)launchOptions);
//---------- Push Notification

// moved by song 2012.06.15
//call applicationDidFinishLaunching to continue initialization
_glView.multipleTouchEnabled = YES;

#if defined(__APP_USE_ACCELEROMETER)
// Configure and start accelerometer.
[[UIAccelerometer sharedAccelerometer] setUpdateInterval:0.02f];
[[UIAccelerometer sharedAccelerometer] setDelegate:self];
#endif // __APP_USE_ACCELEROMETER

// start.
[_glView start:_window argc:0 argv:nil];

return YES;
}

#if defined(DEBUG)
CS_hlpPushUseTestServerEx();
#endif

디버그 모드일 경우 테스트 서버로 연결 하여 테스트 하실 수 있습니다. (초기화 이전 미리 호출 필요)
주의!) enterprise 계정은 release(ADHOC)빌드 후 상용서버로 테스트 하셔야 합니다. CS_hlpPushUseTestServerEx(); 사용하시면 안됩니다.

CS_pushRegisterCallbackHandler(callbackFunc);
CS_hlpPushDefaultActionOnLaunch((void*)launchOptions);

푸쉬 콜백을 등록을 합니다.
리모트 푸쉬를 이용하여 앱을 실행 한 경우 서버로 실행 정보를 전달하게 됩니다.

push notification 사용 승인 팝업

설치 후 최초 실행 시에 위와 유사한 승인 팝업이 뜨게 됩니다.
게임 제목을 제외한 나머지 내용은 Apple의 기본 설정대로 나옵니다.
팝업이 나오지 않는 경우
1. 동일 단말기에 동일 App ID로 설치해서 사용 승인한 적이 있거나
2. 해킹팟에 강제 설치하여 프로비저닝이 설치되지 않았거나
3. 인증서가 만료되어 Push 기능을 사용할 수 없거나
4. 잘못된 프로비저닝을 사용하여 빌드되었을 것입니다.

iOS Push Delegate 메소드

AppDelegate에 아래의 메소드가 없는 경우 추가한다.

Push V4 추가 적용 사항

CS_hlpPushSendPromoCodeEx API deprecated. CS_hlpPushSendOpen API로 변경

- (void)application:(UIApplication*)application didReceiveRemoteNotification:(NSDictionary*)userInfo
{
// CS_hlpPushSendPromoCodeEx((void*)userInfo);

// 3.5.0 update
// iOS 10 이상일 때(UNUserNotification 적용)는 알람 클릭시에만 didReceiveRemoteNotification 진행하므로 상관 없음
// iOS 10 미만에서는 앱이 background에 있을 때 알람 클릭 시
if((application.applicationState != UIApplicationStateActive) || ([[[UIDevice currentDevice] systemVersion] floatValue] >= 10.0)){
CS_hlpPushSendOpen((void*)userInfo);
}
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))handler
{
[self application:application didReceiveRemoteNotification:userInfo];
}

위의 메소드는 리모트 푸쉬를 통하여 앱을 실행 할 경우 호출되는 델리게이트 메소드 이다. (푸시를 클릭 했을 때만 호출해야 한다.)
CS_hlpPushSendOpen를 통하여 서버로 리모트 푸쉬 응답으로 여부를 서버로 전송 한다. 통계용 함수 이다.

- (void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
CS_hlpPushRegisterTokenEx((void*)deviceToken);
}

위의 메소드는 리모트 푸쉬가 정상적으로 등록된 경우 OS에서 디바이스 토큰을 앱으로 전달해 주는 델리게이트 메소드 이다.
해당 메소드에서 CS_hlpPushRegisterTokenEx 함수를 실행하여 서버로 토큰을 등록해야 정상적으로 리모트 푸쉬를 받을 수 있다.

Debug모드로 빌드시 아래와 같은 log를 볼 수 있다

PushTest1[9273:907] <Push> Push Module Version 2.0.2
PushTest1[9273:907] <Push> TokenSender response from server: 0|OK
PushTest1[9273:907] <Push> Save Token data
PushTest1[9273:907] <Push> Data : {"appid":"com.com2us.A18.PushTestApp1","mac":"8C:7B:9D:4A:DE:DA",
"device":"iPod4,1","token":"23fbba19e7560067e77f81a0cb0943e39cd24505156ad83af62d425ea23d25e1",
"country":"KR", "language":"ko", "appver":"1.0", "libver":"2.0.2"}

- (void) application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
NSLog( @"registration error: %@", [error localizedDescription]);
}

위의 메소드는 리모트 푸쉬가 정상적으로 등록되지 못한 경우 호출되는 델리게이트 메소드 이다.
로그를 통하여 에러를 확인 할 수 있다.

- (void) application:(UIApplication *) application didReceiveLocalNotification:(UILocalNotification *)notification
{
NSLog(@"notification: %@", [notification description]);

// ToDo - handle LocalNotification while app is running

if(__suspended == 1) // Wrapper Code
{

}
CS_pushRunCallback((void*)notification);
}

로컬 푸쉬를 통하여 앱으로 진입하게 되는 경우 해당 메소드가 호출된다.
CS_pushRunCallback((void*)notification); 를 호출 하게 되면 C 콜백으로 어떠한 로컬 푸쉬를 이용하여 앱을 시작하였는지 알 수 있다.

콜백 함수

void callbackFunc(Push_CallbackType callbackType, int pushID, int remainPushCallback)
{
NSLog(@"from sample callbackFunc");
NSLog(@"Push ID : %d , remainPushCallback : %d",pushID, remainPushCallback);
}

로컬 푸쉬를 이용하여 앱으로 진입하게 된 경우 호출되는 콜백 이다. CS_pushRunCallback 참조.
해당하는 로컬 푸쉬의 ID와 남은 로컬 푸쉬의 갯수를 확인 할 수 있다.

로컬 푸쉬 등록하기

CS_pushRegisterLocalpush(InputPushID, "Local Push Title",
"Local Push Message", "", "", "",
"Local Push Sound", "",
second);

로컬 푸쉬 등록은 간단하다. iOS의 경우 4가지의 필드만 지원한다.
InPutPushID : 정수형의 푸쉬 아이디값을 지정한다.
Local Push Title : 알림창에 나타날 텍스트 타이틀이다. iOS 8.2 이상에서 지원가능하다. (Push v3.5.0)
Local Push Message : 알림창에 나타날 텍스트 스트링이다.
Local Push Sound : 푸쉬 알림의 사운드를 설정할 수 있다. 공백 스트링일 경우 default 사운드가 재생이 된다. 지원 가능한 자세한 사항은 http://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/IPhoneOSClientImp.html#//apple_ref/doc/uid/TP40008194-CH103-SW1 을 참고한다.
second: 몇초 후의 알람이 울릴 것인가 이다.

테스트

Remote Push Notification Test

Debug 모드 및 CS_hlpPushUseTestServerEx를 호출하여 빌드한다. (Enterprise 빌드인 경우 CS_hlpPushUseTestServerEx를 주석처리 한다)
- Simulator에서는 기능이 동작하지 않기 때문에 실제 단말기에서 실행 후,
- 로그에서 "TokenSender response from server: OK" 문구를 확인 후에
- 게임을 종료하거나 홈키를 눌러서 백그라운드 모드로 전환.
하이브 콘솔(구 백 오피스)에서 푸쉬 전송
- 하이브 콘솔로 접속합니다.
- ~~개발계정 (EX: A10~A21) 인 경우 토큰 확인(TEST/staging)을, Enterprise인 경우 토큰 확인(REAL/Production) 메뉴를 선택합니다.~~ 하이브 콘솔은 샌드박스와 테스트 서버로 설정이 나뉘어 있습니다. 테스트가 하고자 하는 서버의 하이브 콘솔 페이지에서 진행바랍니다.
- OS를 iOS로 선택한 뒤 did와 appID를 입력하여 토큰이 등록 되었는지 확인 합니다.
- 검색 후 나타나는 리스트에서 테스트 할 기기의 SEND 버튼을 클릭합니다.
- 테스트할 단말의 MacAddress, Message를 입력하고 (소리와 뱃지는 옵션) SEND를 클릭합니다.
메시지 수신 확인

HIVE Console

!! 백 오피스의 명칭이 하이브 콘솔로 변경되었습니다. 그리고 주소는 https://console.withhive.com 으로 변경되었습니다 !!

이전 백 오피스 에서는 토큰 등록 확인이 되지 않습니다.

단일 푸시 테스트 기능
- 푸시 테스트를 하기 위해서는 토큰이 등록되어야 합니다.

토큰 등록 확인 기능
- 자사 서버에 토큰이 정상적으로 등록되어야 Apple 서버로 요청을 보낼 수 있습니다. 토큰 등록은 앱에서 한 번만 실행하면 자동으로 등록됩니다.
- 만약, 토큰이 등록되지 않고 Log에서도 이상이 발견되지 않는다면 아래의 사항을 확인하시기 바랍니다.
  - 지정된 기간 중에 특정 AppID를 사용하여 등록된 토큰, UDID 및 기종 정보 조회
  - 지정된 기간 중에 특정 UDID의 단말기로부터 등록된 토큰 및 정보 조회