¶ 1. 라이브러리 다운로드
Note
최신 라이브러리는 아래 링크를 통해, 다운로드 받을 수 있습니다.
| 버전 | 버전 | 내용 |
|---|---|---|
| 1.0.2 | 2024.08.19 | (Android)플러그인 외부 소스코드 내재화 morpheus_push_library_5.2.0.18 적용 |
| 1.0.1 | 2024.07.22 | 샘플 프로젝트 추가 (iOS) MPushLibrary 5.1.6 적용 (Android) morpheus_push_library_5.2.0.16 적용 |
| 1.0.0 | 2024.02.01 | 최초배포 |
¶ 2. 라이브러리 및 설정 파일
¶ 2.1. 다운로드 파일 구성
¶ 2.1.1. MPushPlugin
- UPNS/FCM Push 를 활용할 수 있는 Cordova용 라이브러리
¶ 2.1.2. CordovaDemo
- MPushPlugin 적용한 Cordova 기반 샘플 프로젝트
¶ 2.2. 설정 파일
설정 파일은 각 프로젝트 환경에 맞게 변경 적용이 필요
¶ 2.2.1. mcore.mobile.lic
- Push 라이센스 정보가 담긴 Push 라이센스 파일
- 라이센스 파일이 없을 경우 기술지원 게시판이나 영업을 통해 요청 문의
¶ 2.2.2. Manifest.xml
- Push 제품 구동을 위한 설정 파일
- 서버 URL, 제품 버전, 정책등을 설정하는데 사용
- Manifest.xml 파일은 직접 생성하여 사용하거나 샘플 프로젝트에서 참고하여 사용
¶ 2.3. API 테스트 샘플 UI
¶ 2.3.1. CordovaDemo/www/index.html
- Push API를 사용하는 Push 테스트용 샘플 파일
¶ 3. 적용 순서
¶ 3.1 Android
¶ 3.1.1. Cordova 프로젝트 경로에 다운로드 받은 라이브러리를 압축 해제 한 후 프로젝트에서 아래와 같이 호출하여 플러그인을 적용합니다.
(경로1) workspace > cordova-push-plugin - cordova plugin add ../cordova-push-plugin/MPushPlugin
(경로2) workspace > [프로젝트] > cordova-push-plugin - cordova plugin add ./cordova-push-plugin/MPushPlugin
[경로1 방법으로 라이브러리 적용 예시]
MacBook:Cordova user$ cordova create cProject
MacBook:Cordova user$ cd cProject
MacBook:cProject user$ cordova platform add android
MacBook:cProject user$ cordova plugin add ../cordova-push-plugin/MPushPlugin
Cordova 프로젝트에서 상대경로로 MPushPlugin을 설치해야 합니다.
¶ 3.1.2. [프로젝트]/platforms/android 프로젝트를 Android Studio로 열어 공통 설정파일을 추가합니다.
- [프로젝트]/platforms/android/app/src/main/asset/res/Manifest.xml
- [프로젝트]/platforms/android/app/src/main/asset/res/mcore.mobile.lic
- [프로젝트]/platforms/android/app/google-services.json ( FCM 사용시 )
¶ 3.1.3. [FCM 사용 시] cdv-gradle-config.json 파일 > IS_GRADLE_PLUGIN_GOOGLE_SERVICES_ENABLED를 true로 변경합니다
¶ 3.1.4. CordovaDemo 프로젝트의 MainActivity.java의 onNewIntent(),onMessage()를 참고하여 적용합니다.(CordovaActivity를 상속받는 영역에서 사용 가능)
//앱 실행중 notification 선택 이후처리
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
Log.e("onNewIntent::","onNewIntent");
String notification = intent.getStringExtra("JSON");
JSONObject payload = new JSONObject();
try {
payload.put("status", "SUCCESS");
payload.put("payload", notification);
loadUrl("javascript:getNotification(" + payload.toString() + ")");
} catch (JSONException e) {
}
}
//앱이 종료되었을 경우 notification 선택 이후처리
@Override
public Object onMessage(String id, Object data) {
Log.e("onmessage::",id);
if (id.equals("onPageFinished")){
Intent intent = getIntent();
String notification = intent.getStringExtra("JSON");
JSONObject tempJSON = new JSONObject();
try {
tempJSON.put("status", intent.getStringExtra("PUSH_STATUS"));
tempJSON.put("payload", notification);
loadUrl("javascript:getNotification(" + tempJSON.toString() + ")");
} catch (Exception e) {
e.printStackTrace();
}
}
return super.onMessage(id, data);
}
¶ 3.1.5. API 샘플로 assets/www/index.html 파일을 참고하여 테스트를 진행해보실수 있습니다.
¶ 3.1.6. 라이브러리 내에서 제공하는 Notification을 커스텀하여 사용하실 수 있습니다.
- basic notification을 custom 하는 경우 : FcmCustomNoti.java 적용 후 NotificationBuilder 참고하여 FcmCustomNoti.java에서 추가 옵션을 설정하실 수 있습니다.
- Launcher 액티비티(Startup.java)에서 아래와 같이 항목 적용
¶ Java 프로젝트 (Default)
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
PushManager.getInstance().setCustomInstance(this, FcmCustomNoti.class);
}
¶ kotlin 프로젝트
override fun onPostCreate(savedInstanceState: Bundle?) {
super.onPostCreate(savedInstanceState)
PushManager.getInstance().setCustomInstance(this, FcmCustomNoti::class.java)
}
예시로 제공한 FcmCustomNoti.java 파일을 적용했을 경우를 기반으로 작성되었으며 해당 파일명은 변경이 가능하며, 변경된 클래스로 설정을 변경할 수 있습니다.
Notification 옵션 항목 및 옵션 적용방법 예시
- NotificationBuilder class
- basic notification을 사용하는 경우 알림 아이콘은 Application 아이콘으로 지정되어 있으며, icon을 변경해야하는 경우 NotificationBuilder를 참고하여 style을 수정해서 전달하는 방법으로 사용하실 수 있습니다.
¶ 3.1.7. 라이브러리 내에서 제공하는 Notification을 이용하지 않고 수신 후의 전체 Notification 처리를 커스텀 하는 경우
발송한 메시지의 페이로드 데이터를 수신 한 이후에 별도로 처리해야 하는 영역으로, 아래 첨부파일을 참고하여 자체 비즈니스 규격에 따라 적용하실 수 있습니다.
압축 파일 내의 android 폴더 > FcmNotifyHelper, MessageArrivedReceiver, PushNotificationManager 파일 참고
- AndroidManifest.xml에서 아래와 같이 receiver 적용 (BroadCastReceiver 클래스를 상속받는 receiver클래스)
<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.6. 안드로이드 메시지 콜백
flowchart TD
PushActionReceiver --수신된 메시지에 대한 콜백을 handler로 전달 --> PushUiHandler
PushUiHandler --전달받은 result 데이터에서 콜백 메시지 생성/api로 전달-->UI_Script
¶ 3.2 iOS
¶ 3.2.1. Cordova 프로젝트와 같은 경로에 다운로드 받은 라이브러리를 압축 해제 합니다.
¶ 3.2.2. Cordova 프로젝트에서 아래와 같이 호출하여 라이브러리를 설치합니다.
-
'cordova plugin add ../cordova-push-plugin/MPushPlugin'
MacBook:Cordova user$ cordova create cProject MacBook:Cordova user$ cd cProject MacBook:cProject user$ cordova platform add ios MacBook:cProject user$ cordova plugin add ../cordova-push-plugin/MPushPluginCordova 프로젝트에서 상대경로로 MPushPlugin을 설치해야 합니다.
¶ 3.2.3. iOS 프로젝트를 XCode에서 열어 공통 설정 파일을 추가합니다.
- Manifest.xml, mcore.mobile.lic 파일을 첨부 이미지와 같이 iOS 프로젝트에 추가
¶ 3.2.4. API 테스트 샘플을 위한 index.html 파일을 참고하여 테스트를 진행해보실수 있습니다.
- CordovaDemo/www/index.html 파일 참고
¶ 3.2.5. iOS 메시지 수신 흐름도
flowchart TD
AppDelegate --수신된 메시지를 PushManager로 전달--> PushManager
PushManager --수신확인 전문을 서버로 전송--> PushManager
PushManager --PushManagerDeleage로 이벤트 전달-->PushReceiver
PushReceiver -- oniOSReceiveNotification script 콜백 호출 -->화면_Script
¶ 3.2.6. iOS10 이상 버전에서 수신확인, 이미지 Push처리
- iOS10 이상 버전에서는 Notification Service Extension을 사용하여 앱이 종료된 상태에서도 수신확인 처리를 할수 있습니다.
- Notification Service Extension는 iOS에서 notification을 처리하기 전에 알림 내용을 변경 처리 할 수 있도록 제공되는 서비스 앱 확장 기능입니다.
- MPush는 Notification Service Extension을 처리할수 있도록 기본적으로 Mutable-contents를 1로 설정하여 발송됩니다.
¶ 3.2.7. 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.remote.registerServiceAndUser( setting )
- 푸시 서비스와 사용자를 등록한다.
Arguments
- setting.cuid(String) - 푸시 사용자 아이디
- setting.name(String) - 푸시 사용자 이름
- setting.callback(String) - 푸시 서비스/사용자 등록 콜백 함수
Example:
MPush.remote.registerServiceAndUser({
cuid: 'tester',
name: 'testerName',
callback: function( result ) {
if (result.status == 'SUCCESS') {
console.log('서비스/유저 등록을 성공 하였습니다.');
}
else {
console.log('서비스/유저 등록을 실패 하였습니다.');
}
}
});
¶ 푸시 서비스 해제
¶ MPush.remote.unregisterService( setting )
- 푸시 서비스를 해제한다.
Arguments
- setting.callback(String) - 푸시 서비스 해제 콜백 함수
Example:
MPush.remote.unregisterService({
callback: function( result ) {
if(result.status == 'SUCCESS') {
console.log('서비스 해제가 성공 하였습니다.');
}
else {
console.log('서비스 해제가 실패 하였습니다.');
}
}
});
¶ 푸시 사용자 해제
¶ MPush.remote.unregisterUser( setting )
- 푸시 사용자를 해제하여 Guest로 변경한다.
Arguments
- setting.callback(String) - 푸시 사용자 해제 콜백 함수
Example:
MPush.remote.unregisterUser({
callback: function( result ) {
if(result.status == 'SUCCESS') {
console.log('사용자 해제가 성공 하였습니다.');
}
else {
console.log('사용자 해제가 실패 하였습니다.');
}
}
});
¶ 푸시 전송
¶ MPush.remote.send( setting )
- 푸시 메세지를 전송한다.
Arguments
- setting.cuid(String) - 수신 대상
- setting.code(String) - 푸시 서비스 코드 - admin에서 시나리오에 맞게 변경 가능(기본값: 'ALL/PRIVATE/PUBLIC')
- setting.message(String) - 푸시 메세지
- setting.ext(String) - 푸시 ext 정보
- setting.callback(String) - 푸시 송신 결과 콜백 함수
Example:
MPush.remote.send({
cuid:'tester',
code: 'ALL',
message: '기본알림입니다.',
callback: function( result ) {
if (result.status == 'SUCCESS') {
console.log('메세지를 발송하였습니다.');
}
else {
console.log('메세지발송을 실패하였습니다.');
}
}
});
¶ 푸시 읽음 확인
¶ MPush.remote.read( setting )
- 푸시 메세지 읽음 확인
Arguments
- setting.notification(Object) - 푸시 메세지
- setting.callback(Function) - 콜백 함수
MPush.remote.read({
notification: noti.payload, // noti는 전달된 푸시데이터이다.
callback: function (result) {
if (result.status !== 'SUCCESS') {
// 실패한 경우
console.log(result.error);
}
}
});
¶ badge count 변경
¶ MPush.remote.setBadge( settings )
- 서버에서 관린되는 푸시 badge count를 변경한다.
- iOS Only
Arguments
- setting.badge(Int) - badge count
- setting.callback(String) - badge count 변경 콜백 함수
Example:
MPush.remote.setBadge({
badge: 15,
callback: function( result ) {
if (result.status == 'SUCCESS') {
log('성공\n'+ JSON.stringify(result));
}
else {
log(result);
}
}
});
¶ App badge count 변경
¶ MPush.notificationCenter.badge( settings )
- 클라이언트 badge count를 변경한다.
- iOS Only
Arguments
- setting.badge(String) - badge count
- setting.callback(String) - badge count 변경 콜백 함수
Example:
MPush.notificationCenter.badge({
badge: 10,
callback: function( result ) {
console.log('클라이언트 뱃지 설정 성공\n'+ JSON.stringify(result));
}
});
¶ App badge count 가져오기
¶ MPush.notificationCenter.badge( Setting )
- 클라이언트 badge count 데이터를 가져온다.
- iOS Only
Arguments
- setting.callback(String) - badge count 콜백 함수
Example:
var result = M.plugin('push').notificationCenter.badge({
callback: function( result ) {
console.log('클라이언트 뱃지 값\n'+ JSON.stringify(result));
}
});
console.log('badge count : '+ result);