안드로이드¶

*샘플 다운로드¶

Note

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

샘플 다운로드

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. Firebase Cloud Massaging API(V1) 설정하기¶

서비스 계정 관리 링크를 클릭한다.

3.20. 서비스 계정 확인¶

목록의 표시되는 firebase 고유 이메일 링크를 클릭한다.

3.21. 서비스 계정 키 생성¶

키 추가 버튼을 클릭하고, 새 키 만들기를 클릭한다.

3.21. 비공개 키 만들기¶

비공개 키가 포함된 파일을 생성하고, 다운로드한다.

키 유형은 JSON 으로 선택하고, 만들기를 클릭하면 json 파일이 다운로드 된다.

다운받은 json 파일의 내용을 "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://upmcapi.morpheus.kr</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>

Note

project-id 는: Cloud Console 에서 발급받은 PROJECT ID 를 통해, 확인 할 수 있다.

Note

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번 : 디바이스에서 출력하는 로그를 확인 할 수 있다.