¶ 1. 라이브러리 다운로드
Note
최신 라이브러리는 아래 링크를 통해, 다운로드 받을 수 있습니다.
| 버전 | 버전 | 내용 |
|---|---|---|
| 1.0.1 | 2024.07.19 | (iOS) static_framework 설정 변경, MPushLibrary 5.1.6 적용 (Android) morpheus_push_library_5.2.0.16 적용 |
| 1.0.0 | 2024.02.16 | 최초배포 |
¶ 2. 라이브러리 및 설정 파일
¶ 2.1. 다운로드 파일 구성
¶ 2.1.1. react-native-mpush
- UPNS/FCM Push 를 활용할 수 있는 React Native 용 플러그인 라이브러리
¶ 2.1.2. Sample
- react-native-mpush을 사용할때 필요한 샘플 파일
¶ 2.1.3. ReactDemo
- react-native-mpush을 적용한 React Native 기반 샘플 프로젝트
- 직접 실행해보는 경우 ReactDemo/node_moduls/fsevents/fsevents.node 제거 후 실행
- 서버 환경에 따라 기능이 동작하지 않을 수 있습니다. 기능이 동작하지 않는 경우 Manifest.xml 설정을 자체 서버 환경으로 변경하여 확인해보실 수 있습니다.
¶ 2.2. 설정 파일
설정 파일은 각 프로젝트 환경에 맞게 변경 적용이 필요
¶ 2.2.1. mcore.mobile.lic
- Push 라이센스 정보가 담긴 Push 라이센스 파일
- 라이센스 파일이 없을 경우 기술지원 게시판이나 영업을 통해 요청 문의
¶ 2.2.2. Manifest.xml
- Push 제품 구동을 위한 설정 파일
- 서버 URL, 제품 버전, 정책등을 설정하는데 사용
- Manifest.xml 파일은 직접 생성하여 사용하거나 /Sample/[플랫폼별]/Manifest.xml 파일을 참고하여 사용
¶ 2.3. API 테스트 샘플 UI
¶ 2.3.1. /Sample/tsx/PushApp.tsx
- Push API를 사용하는 Push 테스트용 샘플 파일
¶ 3. 적용 순서
¶ 3.1 Android
¶ 3.1.1. React Native 프로젝트와 같은 경로에 다운로드 받은 라이브러리를 압축 해제 합니다.
¶ 3.1.2. React Native 프로젝트의 Root 경로에서 아래와 같이 호출하여 플러그인을 설치합니다.
-
' yarn add ../rn-push-plugin/react-native-mpush '
MacBook:react user$ npx react-native init ReactProject //ReactProject프로젝트 생성 MacBook:react user$ cd ReactProject MacBook:ReactProject user$ yarn add ../rn-push-plugin/react-native-mpush //모듈 추가 MacBook:ReactProject user$ npm run android //앱 실행React Native 프로젝트에서 상대경로로 react-native-mpush 플러그인을 설치해야 합니다.
¶ 3.1.3. [프로젝트]/android 프로젝트를 Android Studio로 열어 아래 경로에 공통 설정파일을 추가합니다.
- [프로젝트]/android/app/src/main/asset/res/Manifest.xml
- [프로젝트]/android/app/src/main/asset/res/mcore.mobile.lic
- [프로젝트]/android/app/google-services.json ( FCM 사용시 )
- [주의] FCM 앱 생성 시 앱 레벨의 build.gradle에 적용되어있는 applicationId와 동일한 패키지가 등록되어야 함.
¶ 3.1.4. 프로젝트 레벨의 build.gradle에 classpath 추가
buildscript {
...
dependencies {
...
classpath 'com.google.gms:google-services:4.4.0'
}
}
¶ 3.1.5. 앱 레벨의 build.gradle의 가장 하단에 google 플러그인 추가
//반드시, script 맨 하단에 작성
apply plugin: 'com.google.gms.google-services'
¶ 3.1.6. API 샘플로 PushApp.tsx 파일을 참고하여 테스트를 진행해보실수 있습니다.
Notification 아이콘은 Application 아이콘으로 지정되어 있어 별도의 아이콘으로 적용하기 위해서는 AndroidManifest.xml > application 아이콘 이미지를 변경하거나 sample/android/FcmCustomNoti.java를 참고하여 notification 전달값을 변경하여 전달.
¶ 3.1.7. Notification을 커스텀 개발하실 경우 NotificationBuilder.class 태그를 참고하여 별도로 개발하실 수 있습니다.
- Notificaiton만 custom 하는 경우 참고 : NotificationBuilder class
- Launcher 액티비티에서 아래와 같이 항목 적용
override fun onPostCreate(savedInstanceState: Bundle?) {
super.onPostCreate(savedInstanceState)
PushManager.getInstance().setCustomInstance(this, [커스텀Noti]::class.java)
}
- 수신 후 처리 전체를 custom 할 수 있는 영역 참고 : FcmNotifyHelper, MessageArrivedReceiver, PushMessageManager
- AndroidManifest.xml에서 아래와 같이 항목 적용
<application>
<receiver
android:name="[fulepath].MessageArrivedReceiver"
android:exported="false">
<intent-filter>
<!--FCM 사용시 intent-filter-->
<action android:name="${applicationId}.GCM_MESSAGE_ARRIVED" />
<!--------------->
<!--UPNS 사용시 intent-filter -->
<action android:name="${applicationId}.UPNS_MESSAGE_ARRIVED" />
<!--------------->
<!--UPNS+FCM 사용시(아래 intent-filter 모두적용)-->
<action android:name="${applicationId}.GCM_MESSAGE_ARRIVED" />
<action android:name="${applicationId}.UPNS_MESSAGE_ARRIVED" />
<!--------------->
</intent-filter>
</receiver>
</application>
¶ 3.1.8. 안드로이드 메시지 콜백
flowchart TD
PushActionReceiver --수신된 메시지에 대한 콜백을 handler로 전달 --> PushUiHandler
PushUiHandler --전달받은 result 데이터에서 콜백 메시지 생성/api로 전달-->UI_Script
¶ 3.1.9. 다크모드에서 텍스트 색이 모두 흰색으로 나오는 경우
- [프로젝트폴더]/android/app/src/main/res/values/styles.xml에 아래와 같이 적용
<style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
<!-- Customize your theme here. -->
<item name="android:editTextBackground">@drawable/rn_edit_text_material</item>
<item name="android:textColor">#000</item> // Text 태그의 폰트 색상
<item name="android:textColorHint">#999</item> // TextInput 태그의 힌트 폰트 색상
<item name="android:editTextColor">#000</item> // TextInput 태그의 폰트 색상
</style>
¶ 3.2 iOS
¶ 3.2.1. React Native 프로젝트와 같은 경로에 다운로드 받은 라이브러리를 압축 해제 합니다.
- 예시) 'workspace/ReactDemo' 가 프로젝트 경로라면 'workspace/rn-push-plugin' 폴더
- yarn add시 상대경로로 path를 지정하므로 다른 경로에 압축해제시 path를 변경하여 적용 가능
¶ 3.2.2. React Native 프로젝트에서 아래와 같이 호출하여 라이브러리를 설치합니다.
-
' yarn add ../rn-push-plugin/react-native-mpush '
//ReactNative framework 없이 프로젝트 생성 MacBook:react user$ npx @react-native-community/cli@latest init ReactProject //플러그인 추가 MacBook:react user$ cd ReactProject MacBook:ReactProject user$ yarn add ../rn-push-plugin/react-native-mpush // pod install MacBook:ReactProject user$ cd ios MacBook:ios user$ bundle install MacBook:ios user$ bundle exec pod installReact Native 프로젝트에서 상대경로로 react-native-mpush 플러그인을 설치해야 합니다.
¶ 3.3.3. iOS 프로젝트를 XCode에서 열어 설정 파일을 추가합니다.
- Manifest.xml, mcore.mobile.lic 파일을 첨부 이미지와 같이 iOS 프로젝트에 추가
¶ 3.3.4. APNS 사용을 위해 Capability를 설정합니다.
- 프로젝트 -> Targets -> Signing & Capabilities -> + Capability -> Push Notifications 추가
¶ 3.3.5. PushManager 초기화 및 앱 구동시의 푸시 메시지를 전달하기 위해 AppDelegate에 초기화 코드를 추가합니다.
[[PushManager defaultManager] application:application didFinishLaunchingWithOptions:launchOptions];
- AppDelegate.mm 파일 적용 예시
#import "AppDelegate.h"
#import <React/RCTBundleURLProvider.h>
#import <MPushLibrary/MPushLibrary.h>
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
self.moduleName = @"ReactProject";
// You can add your custom initial props in the dictionary below.
// They will be passed down to the ViewController used by React Native.
self.initialProps = @{};
//PushManager 초기화 및 메시지를 전달
[[PushManager defaultManager] application:application didFinishLaunchingWithOptions:launchOptions];
#ifdef DEBUG
/* APNS_MODE설정을 위한 값(4.0이상)
* 여러 위치 사용 가능 설명을 위해 PushReceiver.m 파일에도 샘플 코드가 있음 *
- APNS_MODE는 서버에서 메시지 발송시 APNS서버를 TEST로 발송할지 REAL로 발송할지의 대한 여부값이 됨
- RegisterService API호출시 서버에 해당값을 전달
- PushManager 초기화시 값이 설정되며 default 값은 REAL
- 개발용 인증서로 빌드시 APNS TOKEN값은 TEST토큰값이므로 DEV설정 필요
*/
[[PushManager defaultManager].info changeMode:@"DEV"];
#endif
return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
return [self getBundleURL];
}
- (NSURL *)getBundleURL
{
#if DEBUG
return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
#else
return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
#endif
}
@end
¶ 3.2.6. API 테스트 샘플을 위한 PushApp.tsx 파일을 참고하여 테스트를 진행해보실수 있습니다.
- Sample/tsx/PushApp.tsx 파일 참고
¶ 3.2.7. iOS 메시지 수신 흐름도
flowchart TD
AppDelegate --수신된 메시지를 PushManager로 전달--> PushManager
PushManager --수신확인 전문을 서버로 전송--> PushManager
PushManager --PushManagerDeleage로 이벤트 전달-->mPush
mPush -- oniOSReceiveNotification 화면쪽 이벤트 호출 -->화면에서_메시지처리
¶ 3.2.8. iOS10 이상 버전에서 수신확인, 이미지 Push처리
- iOS10 이상 버전에서는 Notification Service Extension을 사용하여 앱이 종료된 상태에서도 수신확인 처리를 할수 있습니다.
- Notification Service Extension는 iOS에서 notification을 처리하기 전에 알림 내용을 변경 처리 할 수 있도록 제공되는 서비스 앱 확장 기능입니다.
- MPush는 Notification Service Extension을 처리할수 있도록 기본적으로 Mutable-contents를 1로 설정하여 발송됩니다.
¶ 3.2.9. iOS 메시지 payload 샘플
{
"aps": {
"alert": {
"body":"body"
"title":"title"
},
"badge": 1,
"mutable-content": 1,
"sound": "alert.aif"
},
"mps": {
"cuid":"testCUID"
"ext": "8||https://umsapi.morpheus.kr/data/nas/image.png|",
"appid": "com.uracle.push.test",
"psid": "eddf0fb943b8b13e4ee9b3268e7854b59a43f2c63d99f1a405b0a2383cf55718"
"pushkey": "fa0ef0f129cb4cd1addbdb2984fb655d042eb74d"
"seqno": "1247292",
"sender": "admin",
"senddate": "2024022309",
"db_in": "Y"
}
}
¶ 4. MPush API
푸시 관련 기능을 제공한다.
¶ 푸시 서비스 & 사용자 등록
¶ mPush.registerServiceAndUser( param, callback )
- 푸시 서비스와 사용자를 등록한다.
Arguments
- param.cuid(String) - 푸시 사용자 아이디
- param.name(String) - 푸시 사용자 이름
- callback(Function) - 푸시 서비스/사용자 등록 콜백 함수
Example:
mPush.registerServiceAndUser({
cuid:"tester",
name:"testerName"
},
(callback :any) => {
console.log("registerServiceAndUser result \n\n"+callback);
});
¶ 푸시 서비스 해제
¶ mPush.unregisterService( callback )
- 푸시 서비스를 해제한다.
Arguments
- callback(Function) - 푸시 서비스 해제 콜백 함수
Example:
mPush.unregisterService(
(callback :any) => {
console.log("unRegisterService result \n\n "+callback);
}
);
¶ 푸시 사용자 해제
¶ mPush.unregisterUser( callback )
- 푸시 사용자를 해제하여 Guest로 변경한다.
Arguments
- callback(Function) - 푸시 사용자 해제 콜백 함수
Example:
mPush.unregisterUser(
(callback :any) => {
console.log("unRegisterUser result \n\n "+callback);
}
);
¶ 푸시 전송
¶ mPush.sendNotification( param, callback )
- 푸시 메세지를 전송한다.
Arguments
- param.cuid(String) - 수신 대상
- param.code(String) - 푸시 서비스 코드 - admin에서 시나리오에 맞게 변경 가능(기본값: 'ALL/PRIVATE/PUBLIC')
- param.message(String) - 푸시 메세지
- param.ext(String) - 푸시 ext 정보
- callback(Function) - 푸시 송신 결과 콜백 함수
Example:
mPush.sendNotification({
cuid : 'tester',
serviceCode: 'ALL',
message:'기본알림입니다.'
},
(callback :any) => {
console.log("sendNotification result \n\n "+callback);
}
);
¶ 푸시 읽음 확인
¶ mPush.readNotification( param, callback )
- 푸시 메세지 읽음 확인
Arguments
- param.notification(Object) - 푸시 메세지
- callback(Function) - 콜백 함수
mPush.readNotification({
notification: noti
},
(callback :any) => {
console.log("readNotification result \n\n "+callback);
}
);
¶ badge count 변경
¶ mPush.remoteSetBadge( param, callback )
- 서버에서 관린되는 푸시 badge count를 변경한다.
- iOS Only
Arguments
- param.badge(Int) - badge count
- callback(Function) - badge count 변경 콜백 함수
Example:
mPush.remoteSetBadge({
badge:10
},
(callback :any) => {
setResult("remoteSetBadge result \n\n "+callback);
}
);
¶ App badge count 변경
¶ mPush.notificationCenterSetBadgeNumber( param, callback )
- 클라이언트 badge count를 변경한다.
- iOS Only
Arguments
- param.badge(String) - badge count
- callback(Function) - badge count 변경 콜백 함수
Example:
mPush.notificationCenterGetBadgeNumber(
(callback :any) => {
setResult("notificationCenterGetBadge = " + callback);
}
);
¶ App badge count 가져오기
¶ mPush.notificationCenterGetBadgeNumber( callback )
- 클라이언트 badge count 데이터를 가져온다.
- iOS Only
Arguments
- callback(Function) - badge count 콜백 함수
Example:
mPush.notificationCenterGetBadgeNumber(
(callback :any) => {
setResult("notificationCenterGetBadge = " + callback);
}
);