안드로이드

*샘플 다운로드

Note

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

샘플 다운로드

1. 개요

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

2. 용어

FCM

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 접속

../../_images/3-1.png

3.2. 프로젝트 추가

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

../../_images/3-2.png

3.3. 프로젝트 이름 지정

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

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

../../_images/3-3.png

3.4. 프로젝트 만들기

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

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

../../_images/3-4.png

3.5. 유의 사항 확인

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

../../_images/3-5.png

3.6. 애널리틱스 사용여부

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

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

../../_images/3-6.png

3.7. 애널리틱스 구성

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

../../_images/3-7.png

3.8. 프로젝트 생성 중

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

../../_images/3-8.png

3.9. 프로젝트 생성 완료

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

../../_images/3-9.png

3.10. 앱에 Firebase 추가

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

../../_images/3-10.png

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

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

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

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

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

../../_images/3-11.png

3.12. google-service.json 다운로드

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

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

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

../../_images/3-12.png

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

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

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

../../_images/3-13.png

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

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

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

../../_images/3-14.png

3.15. 앱 설치 확인

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

../../_images/3-15.png

3.16. 설정 메뉴 이동

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

../../_images/3-16.png

3.17. 설정 메뉴 클릭

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

../../_images/3-17.png

3.18. 설정 화면

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

../../_images/3-18.png

3.19. Sender ID 확인

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

../../_images/3-19.png

3.20. FCM 서버 키 확인

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

../../_images/3-20.png

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

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

4.1. 생성

  • Start a new Android Studio

../../_images/4-1.png

4.2. 템플릿 선택

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

../../_images/4-2.png

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

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

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

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

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

../../_images/4-3.png

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 파일을 복사

../../_images/5-1.png

5.2. View 를 Project 로 변환

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

../../_images/5-2.png

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

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

../../_images/5-3.png

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

  • 1번 : 프로젝트 단위의 build.gradle 파일을 연다.

  • 2번 : buildscript 에 dependencies 부분에, classpath 적용

classpath 'com.google.gms:google-services:4.3.3'
../../_images/5-4.png
  • 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'
../../_images/5-5.png
  • 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번을 이용하여, 동기화를 진행한다.

../../_images/5-6.png

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

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

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

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

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

../../_images/5-7.png

6. PUSH SDK 및 Manifest.xml 설정

6.1. 라이브러리 적용

  • app > libs 폴더에 아래 라이브러리를 적용한다.

. morpheus_push_library_fcm_xxx.jar
. mqtt-android-push_xxx.jar
../../_images/6-1.png

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

  • assets 폴더를 생성한다.

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

../../_images/6-2.png
  • Manifest.xml 파일은 app > src > main > assets > res > Manifest.xml 에 위치 한다.

../../_images/6-2-1.png

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를 생성한다.

../../_images/6-4.png

6.5. MessageArrivedReceiver.java class 생성

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

../../_images/6-5.png
../../_images/6-5-1.png
  • MessageArrivedReceiver 는 BroadcastReceiver 를 상속받아 생성한다.

../../_images/6-5-2.png
  • 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
../../_images/6-6.png
  • 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 를 실행한다.

../../_images/6-7.png

6.8. 로그 보기

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

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

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

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

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

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

../../_images/6-8.png