안드로이드

샘플 다운로드

참고

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

샘플 다운로드

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. 안드로이드 프로젝트 생성 따라하기

• 안드로이드 프로젝트를 생성하는 가이드로, 현 매뉴얼에서는 Android Studio 2024.3.1 버전에서 진행한다.

3.1. 생성

• Start a new Android Studio

3.2. 템플릿 선택

• 템플릿을 선택한다. 샘플에서는 Empty Views Activity로 진행한다.

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

• 프로젝트명, 패키지명(domain 형식, 소문자), 최소SDK 버전 등을 입력후 프로젝트를 생성한다.

4. FCM Sender ID 발급 따라하기

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

• 이미 프로젝트를 생성한 경우, 5. 프로젝트 설정 따라하기 로 이동한다.

4.1. Firebase Console 접속

• https://console.firebase.google.com/ 로 이동후 Firebase 프로젝트 시작하기를 클릭한다.

4.2. 프로젝트 이름 지정

• 프로젝트에서 사용할 이름을 입력한다.

4.3. 프로젝트 생성 중

• 이후 Firebase 프로젝트를 위한 AI 지원, Firebase 프로젝트를 위한 Google 애널리틱스는 필요에 따라 선택 후 프로젝트를 생성한다.

4.4. 프로젝트 생성 완료

• 프로젝트가 생성이 완료되면 메인 화면에서 생성한 프로젝트를 확인할 수 있다.

• 프로젝트를 눌러서 다음 단계로 이동한다.

4.5. 안드로이드 설정

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

4.6. 추가 정보 입력

• 안드로이드 패키지 이름, 앱 닉네임(선택)을 입력 후 앱을 등록한다.

4.7. google-service.json 다운로드

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

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

4.8. Firebase SDK 설정(프로젝트 수준, 앱 수준)

• 프로젝트 수준, 앱 수준의 build.gradle 설정은 가이드 하단에서 설정 예정이므로 다음으로 넘어간다.

4.9. 설정 메뉴 이동

• 설정정보를 확인하기 위해 콘솔 메인에서 안드로이드 로고를 클릭후 설정 버튼을 클릭한다.

4.10. Sender ID 확인

• 상단 메뉴에서 클라우드 메시징을 선택후 발신자 ID를 복사하여 저장해 놓는다.

5. 프로젝트 설정 따라하기

• FCM 사용을 위한 라이브러리, gradle, PUSH SDK, Manifest.xml 설정에 관한 내용이다.

5.1. google-service.json 적용

• 프로젝트의 View가 Project로 안되어있는 경우 Project로 전환한다.

• Firebase Console을 통해 다운로드 받은 google-service.json 파일을 생성한 안드로이드 프로젝트의 app module에 복사한다.

5.2. 라이브러리 파일 추가

• 프로젝트에서 사용할 라이브러리 파일을 다운로드 받아 적용한다.

• 샘플에서는 message-ai 폴더를 생성후 라이브러리를 넣어서 적용하였음.

  라이브러리 다운로드

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

• 프로젝트의 루트에 있는 build.gradle에 다음과 같은 내용을 추가하고 Sync Now를 진행한다.

id("com.google.gms.google-services") version "4.4.2" apply false

5.4. 앱 모듈 단위 build.gradle 적용

• 앱 모듈 단위에 있는 build.gradle에 다음과 같은 내용을 추가하고 Sync Now를 진행한다.

id("com.google.gms.google-services")

// Message AI
implementation('com.google.firebase:firebase-messaging:24.1.0')
implementation('com.google.firebase:firebase-iid:21.1.0')
implementation("androidx.work:work-runtime:2.9.1")
implementation("com.google.code.gson:gson:2.11.0")
implementation fileTree(dir: "message-ai", includes: ["*.jar","*.aar"])

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

• assets 폴더를 생성한다.

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

• 이후 Manifest.xml 파일을 생성한다.

5.6. Manifest.xml 파일 설정

• 설정을 위해 4.10. Sender ID 확인 에서 확인한 Sender ID를 확인한다.

• Message-AI의 서비스 그룹 상세보기에서 서비스 그룹 아이디 를 확인한다.

• 적용순서

가.  Message-AI의 서비스 그룹에서 확인한 서비스 그룹 아이디를 <project-id> </project-id>에 입력
나. 접속할 서버 정보를 <server> </server> 에 입력. 여기서는 https://upmc.message-ai.net 고정
다. 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>
        <!-- key 교환 방식 암호화 : 라이선스 발급시 요청 (hexa코드 16자리) -->
        <security-indexes>0x35b 0x6a3 0x759 0x77d 0x301 0x10a 0x644 0x78d 0x374 0x2f6 0x1b5 0x22 0x310 0x138 0x595 0x547</security-indexes>
        <receiver>
            <project-id>testtesttesttesttesttesttesttest</project-id>
            <log>y</log>
            <file-log>n</file-log>
            <!-- UPMC 서버 버전 5.0-->
            <version>5.0</version>
            <!-- UPMC 서버 URL-->
            <server>https://upmc.message-ai.net</server>
            <!-- 타임아웃 시간 -->
            <timeout>20000</timeout>
            <fcm-sender-id>1234123412341234</fcm-sender-id>
            <android-push-type>FCM</android-push-type>
            <!-- 브로드캐스트 리시버에서 퍼미션 사용 여부를 설정 (Y/N) -->
            <use-permission>Y</use-permission>
        </receiver>
    </push>
</settings>

• 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. PUSH SDK 테스트

6.1. 푸시유저 등록 테스트

• 해당 샘플에서는 간단하게 푸시유저 등록을 하는 테스트를 하기 위한 코드를 작성하여 사용하였다.

private void pushUserAdd() {
    JSONObject userInfo = PushManager.getInstance().getUserInfo(getApplicationContext());

    String cuid = userInfo.optString("CLIENT_UID");
    String name = userInfo.optString("CLIENT_NAME");

    if(TextUtils.isEmpty(cuid)){
        // 구분 가능한 ID
        cuid = PushUtils.getDeviceId(getApplicationContext());
    }
    if(TextUtils.isEmpty(name)){
        // 이름
        name = "TEST";
    }

    // 유저 등록
    PushManager.getInstance().registerServiceAndUser(getApplicationContext(), cuid, name);
}

6.2. 빌드 및 테스트

• 테스트를 위한 안드로이드 단말을 연결후 빌드를 한 뒤 테스트를 진행한다.

• 하단 로그캣과 같이 정상적으로 푸시유저 등록이 되었는지 확인한다.

6.3. 푸시 발송 테스트

• 등록이 된 푸시유저는 Message-AI의 서비스 그룹 -> Console -> 발송 대상 -> 푸시 등록 회원 관리에서 확인이 가능하다.

• 샘플에서는 이름을 TEST, CUID를 디바이스 아이디로 설정하였음.

• 해당 푸시유저를 대상으로 푸시 발송을 하게되면 다음과 같이 푸시 알림을 수신하는 것을 확인할 수 있다.

7. 푸시 수신 테스트

7.1. receiver package 생성

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

7.2. 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();
                        }
                }
        }
}

7.3. 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>

7.4. 빌드

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

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

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

7.5. 로그 보기

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

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

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

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

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

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