안드로이드

*샘플 다운로드

참고

최신 샘플 및 라이브러리는 아래 링크를 통해, 다운로드 받을 수 있습니다.

샘플 다운로드

1. 개요

Morpheus Push 는 스마트폰 OS에서 지원하는 PNS(Push Notification Server)를 기반으로 한 메세지 전송 플랫폼이다. Android Client 에서는 UPMC WAS 에서 제공하는 Push API 를 각각 버전 규격에 맞춰 연동하여 원할하게 Push Service 를 운영하기 위한 라이브러리를 제공한다.

2. 용어

FCM

Firebase Cloud Messaging 의 줄임말.

Firebase 클라우드 메시징(FCM)은 무료로 메시지를 안정적으로 전송할 수 있는 교차 플랫폼 메시징 솔루션입니다.

https://firebase.google.com/docs/cloud-messaging/?hl=ko

UPMC

Uracle Push Message Center 의 줄임말.

Android FCM 서버와 HTTP 프로토콜을 이용하여, Server 대 Server 로 연계하여 구동하는 WAS(Web Application Server) 이다.

Receiver 라고도 불림

Service를 등록하는 절차

FCM 으로 부터 Token 을 할당받고, 사용자를 등록하는 절차

Service 해제

UPMC 로 Push 서비스를 사용하지 않겠다고 등록을 삭제하는 절차

수신 확인

통계를 위해, 메시지를 수신 후 UPMC 로 Ack를 주는 절차

읽음 확인

통계를 위해, 사용자가 App에서 메세지를 읽었을때 UPMC 로 Ack를 주는 절차

Project ID

서비스를 위해 생성된 ID

FCM Sender ID

– FCM 서비스 등록을 위한 ID로, Firebase console 을 통해 획득 할 수 있다.

Client ID

사용자로 등록 할 Client 의 고유한 ID (CUID 라고도 함)

제약은 없으며, 일반적으로, Email, UserID, Phone Number 또는 Device-UUID 등을 CUID 로 사용함.

Client Name

사용자로 등록할 Client 의 이름 (CNAME 라고도 함)

사용자의 이름이나 Nickname 또는 Device Name 을 CNAME 으로 사용

GROUPSEQ

Group Sequence Number 의 준말로 User Group의 고유한 Sequence Number

PSID

Push Service ID 의 줄임말

Push 서비스에 대한 고유 ID

FCM에서 할당 받은 Device Token을 사용

Packge Name

google play에서 안드로이드 앱을 구별하기 위한 unique 값으로, AndoridManifest.xml 에 선언한다.

3. FCM Sender ID 발급 따라하기

Firebase console에 프로젝트가 생성되어 있지 않은 경우, 아래 절차에 따라 프로젝틑 생성 후, Sender ID발급이 가능하다.

절차는 ‘3.1. Firebase Console ~ 3.19. Sender ID 확인’ 으로 구성된다.

이미 프로젝트를 생성한 경우, 3.16. 설정 메뉴 이동 로 이동한다.

3.1. Firebase Console 접속

https://console.firebase.google.com/ 을 입력하거나, Go to Console 을 클릭한다.

3.2. 프로젝트 추가

프로젝트 추가 메뉴를 클릭한다.

3.3. 프로젝트 이름 지정

새로운 프로젝트 생성을 하려면 1번 프로젝트 이름 입력 부분을 클릭하여, 프로젝트 이름을 입력한다.

기존에 구성된 프로젝트를 이용하려면, 2번 리스트에 나타나는 프로젝트를 선택한다.

3.4. 프로젝트 만들기

프로젝트명을 입력하고, 계속을 클릭한다.

이미지상 프로젝트명은 예시이므로, 사용하고자 하는 프로젝트명을 입력한다.

3.5. 유의 사항 확인

Firebase를 추가할때 유의할 사항들에 대해 검토한 후, 계속을 클릭한다.

3.6. 애널리틱스 사용여부

애널리틱스 사용여부에 대해 설정 후, 계속을 클릭한다.

애널리틱스는 무료로 이용할 수 있다.

3.7. 애널리틱스 구성

3.6. 애널리틱스 사용을 선택한 경우 나타나는 화면이며, 애널리틱스 계정을 선택하거나 만든 후, Firebase 추가를 클릭한다.

3.8. 프로젝트 생성 중

3.7에서 Firebase 추가시 나타나는 화면이며, “새 프로젝트가 준비되었습니다.” 라는 문구가 표시 될때 까지 대기한다.

3.9. 프로젝트 생성 완료

프로젝트 생성 완료 화면이며, 계속을 클릭한다.

3.10. 앱에 Firebase 추가

안드로이드 앱에 FCM 을 연동하기 위해, 안드로이드 아이콘을 클릭한다.

3.11. 앱에 Firebase 추가를 위한 정보 입력

1번 항목에 패키지 명을 입력한다.

화면에 나타나는 정보는 예시이며, 서비스 하고자 하는 앱의 page name 을 입력한다.

2번 항목에 앱에 대한 nick name 을 입력한다.

nick name 은 Firebase console 에서 서비스 중인 앱의 명칭을 쉽게 확인 하기 위한 용도이다.

3.12. google-service.json 다운로드

앱 등록이 완료되면, google-service.json 파일이 생성된다.

google-service.json 파일은 FCM 연동시 필요하므로, 다운로드 받아 저장해 놓는다.

참고로, google-service.json 파일은 다른 화면에서도 다운로드가 가능하다.

3.13. build.gradle (프로젝트 수준) SDK 설정 정보

프로젝트 수준의 build.gradle 에 포함해야 할 정보로, 복사하기 버튼을 클릭하여 복사한다.

추후, 일괄 처리를 위해, NotePad 와 같은 프로그램을 이용하여, 복사한 정보를 저장해 놓는다.

3.14. build.gradle (앱 수준) SDK 설정 정보

앱 모듈 수준의 build.gradle 에 포함해야 할 정보로, 복사하기 버튼을 클릭하여 복사한다.

1, 2 번 모두 복사하여, 저장해 놓는다.

3.15. 앱 설치 확인

앱을 실행하여, 정상적인 적용상태를 확인 하는 화면으로, 앱이 구성되지 않았으므로, 이 단계 건너뛰기를 클릭하여 다음화면으로 이동한다.

3.16. 설정 메뉴 이동

설정 정보를 확인하기 위해, 앱 (안드로이드 아이콘)이나 더보기 아이콘 등을 선택한다.

3.17. 설정 메뉴 클릭

설정 정보를 확인하기 위해, 설정 아이콘을 선택한다.

3.18. 설정 화면

Sender ID 값을 확인하기 위해, 클라우드 메시징 탭을 클릭한다.

3.19. Sender ID 확인

발신자 ID 에 나타나는 12자리 숫자를 복사하여 저장해 놓는다.

3.20. FCM 서버 키 확인

서버 키 에 나타나는 값을 복사하여 저장해 놓는다.

4. 안드로이드 프로젝트 생성 따라하기

안드로이드 프로젝트를 생성하는 가이드로, ‘4.1. 생성 ~ 4.3. package name / 프로젝트명 입력’으로 구성된다.

4.1. 생성

Start a new Android Studio

4.2. 템플릿 선택

사용하고자 하는 템플릿을 선택한다.

4.3. package name / 프로젝트명 입력

1번 : 프로젝트 명을 입력한다.

2번 : 사용하고자 하는 page name 입력한다. (domain 형식, 소문자)

3번 : 프로젝트 저장 위치를 지정한다.

4번 : 프로젝트 생성을 완료 한다.

5. FCM 라이브러리 설정 따라하기

FCM 사용을 위한 라이브러리 및 gradle 환경설정에 대한 가이드로, ‘5.1. google-service.json 적용 ~ 5.7. 프로젝트 동기화 상태 확인’으로 구성된다.

5.1. google-sevice.json 적용

Firebase console 을 통해, 다운로드 받은 google-service.json 파일위치로 이동

생성한 안드로이드 프로젝트의 app module 에 google-service.json 파일을 복사

5.2. View 를 Project 로 변환

ProjectViews 에서 Group Tab 을 클릭하여, Project 선택

5.3. google-service.json 적용 상태 체크

app module 하위에 google-service.json 파일이 적용되어 있는지 확인

5.4. 프로젝트 단위 build.gradle 적용

1번 : 프로젝트 단위의 build.gradle 파일을 연다.
2번 : buildscript 에 dependencies 부분에, classpath 적용

classpath 'com.google.gms:google-services:4.3.3'

Sample

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.2.2"
        classpath 'com.google.gms:google-services:4.3.14'
        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

5.5. app module 단위 build.gradle 적용

1번 : app module 단위의 build.gradle 파일을 연다.
2번 : dependencies에 라이브러리를 적용한다.

// Add the SDK for Firebase Cloud Messaging
implementation 'com.google.firebase:firebase-messaging:20.2.1'

implementation 'com.nostra13.universalimageloader:universal-image-loader:1.9.5'
implementation 'com.google.code.gson:gson:2.8.5'
implementation 'com.firebase:firebase-jobdispatcher:0.8.5'

3번 : google-services plugin 적용

apply plugin: 'com.google.gms.google-services'

Sample

apply plugin: 'com.android.application'

android {
    compileSdkVersion 31
    //buildToolsVersion "29.0.3"

    defaultConfig {
        applicationId "com.push.cloud"
        minSdkVersion 19
        targetSdkVersion 31
        versionCode 1
        versionName "1.0"

        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar"])
    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation 'com.google.android.material:material:1.0.0'
    implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
    implementation 'androidx.navigation:navigation-fragment:2.1.0'
    implementation 'androidx.navigation:navigation-ui:2.1.0'


    // Add the SDK for Firebase Cloud Messaging
    implementation 'com.google.firebase:firebase-messaging:23.1.0'

    implementation 'androidx.work:work-runtime:2.7.1'


    //샘플 프로젝트를 위한 image loader libray
    implementation 'com.nostra13.universalimageloader:universal-image-loader:1.9.5'
    implementation 'com.google.code.gson:gson:2.8.5'


    testImplementation 'junit:junit:4.12'
    androidTestImplementation 'androidx.test.ext:junit:1.1.1'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'

}

apply plugin: 'com.google.gms.google-services'

5.6. gradle sync

build.gradle 파일을 수정하면, 항상 동기화 작업을 진행해야 한다.

1번 : 메뉴바에 있는 Sync Project With Gragle File 아이콘을 통해 동기화 할 수 있다.

2번 : 또는 gradle 파일이 수정되면 나타나는 ‘Sync Now’ 기능을 통해 동기화 할 수 있다.

1 또는 2번을 이용하여, 동기화를 진행한다.

5.7. 프로젝트 동기화 상태 확인

아래 3 가지 정보가 일치해야, 셋팅이 정상적으로 된 것으로 판단할 수 있다.

1번 : build.gradle 파일 위치 점검

2번 : Run ‘app’ 버튼이 활성화

3번 : Build console 에서, ‘CONFIGURE SUCCESSFUL’ 문구 확인

6. PUSH SDK 및 Manifest.xml 설정

6.1. 라이브러리 적용

app > libs 폴더에 아래 라이브러리를 적용한다.
가. morpheus_push_library_fcm_xxx.jar
나. mqtt-android-push_xxx.jar

6.2. assets 폴더 및 Manifest.xml 파일 생성

assets 폴더를 생성한다.

assets 폴더는 app > src > main > assets 위치한다.

Manifest.xml 파일은 app > src > main > assets > res > Manifest.xml 에 위치 한다.

6.3 Manifest.xml 설정

PUSH SDK에서 사용하기 위한 Manifest.xml 을 생성한다. (AndroidManfiest.xml 과는 다른 파일임)
3.19. Sender ID 확인 을 통해, 획득한 sender id 확인한다.
PROJECT ID 를 확인하다.
적용순서

가. Cloud Console 에서 발급받은  project id를 <project-id> </project-id>에 입력
나. 접속할 서버 정보를 <server> </server> 에 입력
다. Firebase Console 에서 획득한 발신자 id (sender id) 를 <fcm-sender-id> </fcm-sender-id> 에 입력한다.
라. log 와 file log 는 필요시 수정한다.

Manifest.xml 예시

<?xml version="1.0" encoding="UTF-8"?>
<settings>
        <push>
                <receiver>

                        <project-id>123456589</project-id>
                        <log>y</log>
                        <file-loy>y</file-loy>

                        <!-- UPMC 서버 버전 5.0-->
                        <version>5.0</version>

                        <!--UPMC 서버 URL : 아래 도메인 정보 fixed -->
                        <server>https://umpc.message-ai.net</server>

                        <!-- 타임아웃 시간 -->
                        <timeout>20000</timeout>

                        <!-- firebase console 에서 획득한 발신자 id -->

                        <fcm-sender-id>123456789101</fcm-sender-id>

                        <!-- fixed -->
                        <android-push-type>FCM</android-push-type>

                        <!-- 브로드캐스트 리시버에서 퍼미션 사용 여부를 설정 (Y) : fixed  -->
                        <use-permission>Y</use-permission>
                </receiver>
        </push>
</settings>

참고

project-id 는: 서비스그룹 생성 시 발급되는 서비스그룹아이디 PROJECT ID 를 통해, 확인 할 수 있다.

참고

file log를 활성화 하는 경우 파일 위치 : 메인저장소 > Android > data > [page name] > log > pushlog.log

settings.push.receiver 에 대한 설정값

Key	Type	Description
log	String	디버깅 로그 출력 여부 ( y / n )
file-log	String	파일 로그 출력 여부 ( y / n )
version	String	UPMC Version (5.0, 5.1)
server	String	UPMC WAS 서버 URL
timeout	String	UPMC 접속 timeout
fcm-sender-id	String	Firebase Console 에서 획득한 발송자 ID
android-push-type	String	push type 선언 (FCM 으로 선언함)
use-permission	String	Broadcast 퍼미션 사용여부 (Y : 필수)

6.4. receiver package 생성

푸시 수신을 위한 receiver 용 package를 생성한다.

6.5. MessageArrivedReceiver.java class 생성

푸시를 받을 MessageArrivedReceiver class 를 생성한다.

MessageArrivedReceiver 는 BroadcastReceiver 를 상속받아 생성한다.

MessageArrivedReceiver 예시

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import com.uracle.push.test.helper.PushNotifyHelper;
import org.json.JSONObject;
import m.client.push.library.common.Logger;
import m.client.push.library.common.PushConstants;

public class MessageArrivedReceiver extends BroadcastReceiver {

        @Override
        public void onReceive(Context context, Intent intent) {
                if (intent.getAction().equals(context.getPackageName() + PushConstants.ACTION_GCM_MESSAGE_ARRIVED)) {
                        try {

                                // 수신된 payload data 는 아래 3가지 방식으로 획득 할 수 있다.
                                String data = intent.getExtras().getString(PushConstants.KEY_JSON);
                                String rawData = intent.getExtras().getString(PushConstants.KEY_ORIGINAL_PAYLOAD_STRING);
                                byte[] rawDataBytes = intent.getExtras().getByteArray(PushConstants.KEY_ORIGINAL_PAYLOAD_BYTES);

                                Logger.i(new JSONObject(data).toString(2));
                                Logger.i("received raw data : " + rawData);
                                Logger.i("received bytes data : " + new String(rawDataBytes, "utf-8"));
                                // 노티피케이션 생성
                                PushNotifyHelper.showNotification(context, new JSONObject(data));

                        } catch (Exception e) {
                                e.printStackTrace();
                        }
                }
        }
}

6.6. AndroidManifest.xml 설정

푸시를 위한 서비스 등록 및 메시지 수신을 위한 설정을 한다.

가. service 등록 : FCMIntentService
나. receiver 등록 : MessageArrivedReceiver, FcmActionReceiver
다. permission 등록 : ${applicationId}.permission.MPUSH_PERMISSION
라. uses-permission 등록 : ${applicationId}.permission.MPUSH_PERMISSION, android.permission.WAKE_LOCK

AndroidManifest.xml 예시

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools"
          package="com.push.cloud">

        <application
                android:requestLegacyExternalStorage="true"
                android:allowBackup="false"
                android:icon="@mipmap/ic_launcher"
                android:label="@string/app_name"
                android:roundIcon="@mipmap/ic_launcher_round"
                android:supportsRtl="true"
                android:theme="@style/AppTheme"
                android:usesCleartextTraffic="true">
                <activity
                        android:name=".MainActivity"
                        android:label="@string/app_name"
                        android:theme="@style/AppTheme.NoActionBar">
                        <intent-filter>
                                <action android:name="android.intent.action.MAIN" />
                                <category android:name="android.intent.category.LAUNCHER" />
                        </intent-filter>
                </activity>

                <!-- =================== PUSH SERVICE SETTINGS START============= -->
                <!-- FirebaseMessagingService 를 상속받아 구현 됨 -->
                <service
                        android:name="m.client.push.library.service.FCMIntentService"
                        android:exported="false"
                        tools:ignore="Instantiatable">
                        <intent-filter>
                                <action android:name="com.google.firebase.MESSAGING_EVENT" />
                        </intent-filter>
                </service>

                <!-- 푸시 payload data 수신 class -->
                <receiver android:name=".receiver.MessageArrivedReceiver">
                        <intent-filter>
                                <action android:name="${applicationId}.GCM_MESSAGE_ARRIVED" />
                        </intent-filter>
                </receiver>

                <!-- UPMC 서비스 등록 / 해제 등을 위한 class  -->
                <receiver android:name="m.client.push.library.receiver.FcmActionReceiver">
                        <intent-filter>
                                <action android:name="${applicationId}.ACTION_GCM" />
                        </intent-filter>
                </receiver>
        </application>

        <!-- 푸시 BroadCast 수신 권한 용 Permission -->
        <permission
                android:name="${applicationId}.permission.MPUSH_PERMISSION"
                android:protectionLevel="signature" />
        <uses-permission android:name="${applicationId}.permission.MPUSH_PERMISSION" />

        <!-- 푸시 수신 후, screen on 을 위한 permission-->
        <uses-permission android:name="android.permission.WAKE_LOCK" />
        <uses-permission android:name="android.permission.INTERNET"/>
        <uses-permission android:name="android.permission.VIBRATE"/>
        <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
        <!-- =================== PUSH SERVICE SETTINGS END ============= -->

</manifest>

6.7. 빌드

디바이스 개발자 옵션 활성화 를 진행한다.

PC와 디바이스를 USB로 연결한다.

빌드할 디바이스를 선택하고, 활성화된 Run 버튼을 이용하여, Build 를 실행한다.

6.8. 로그 보기

Android Studio 하단에 Logcat 탭을 선택한다.

Manifest.xml 의 log 를 y로 설정한다.

빌드를 통해, 앱을 실행한다.

1번 : 로그를 보고자 하는 Device, package name 을 선택하고, log level 을 설정한다.

2번 : Show only selected applicatoin 을 선택하면, 선택한 package name 에 해당하는 앱의 로그만 볼 수 있다.

3번 : 디바이스에서 출력하는 로그를 확인 할 수 있다.