=================================== 안드로이드 =================================== *샘플 다운로드 ================= .. note:: 최신 샘플 및 라이브러리는 아래 링크를 통해, 다운로드 받을 수 있습니다. :download:`샘플 다운로드 <../../_static/cloud/android/SDK35_PUSH_5.1_Sample.zip>` 1. 개요 ========= Morpheus Push 는 스마트폰 OS에서 지원하는 PNS(Push Notification Server)를 기반으로 한 메세지 전송 플랫폼이다. Android Client 에서는 UPMC WAS 에서 제공하는 Push API 를 각각 버전 규격에 맞춰 연동하여 원할하게 Push Service 를 운영하기 위한 라이브러리를 제공한다. 2. 용어 ========= .. _FCM: FCM -------- - Firebase Cloud Messaging 의 줄임말. - Firebase 클라우드 메시징(FCM)은 무료로 메시지를 안정적으로 전송할 수 있는 교차 플랫폼 메시징 솔루션입니다. - https://firebase.google.com/docs/cloud-messaging/?hl=ko .. _UPMC: UPMC -------- - Uracle Push Message Center 의 줄임말. - Android FCM 서버와 HTTP 프로토콜을 이용하여, Server 대 Server 로 연계하여 구동하는 WAS(Web Application Server) 이다. - Receiver 라고도 불림 .. _RegisterServiceAndUser: Service를 등록하는 절차 ----------------------------- - :ref:`FCM` 으로 부터 Token 을 할당받고, 사용자를 등록하는 절차 .. _UnregisterService: Service 해제 ------------------------------ - :ref:`UPMC` 로 Push 서비스를 사용하지 않겠다고 등록을 삭제하는 절차 .. _receiveMessage: 수신 확인 ------------------------- - 통계를 위해, 메시지를 수신 후 :ref:`UPMC` 로 Ack를 주는 절차 .. _ReadMessage: 읽음 확인 ------------------------- - 통계를 위해, 사용자가 App에서 메세지를 읽었을때 :ref:`UPMC` 로 Ack를 주는 절차 .. _Project ID: Project ID ---------------- - 서비스를 위해 생성된 ID .. _FCMsenderid: FCM Sender ID ---------------- – FCM 서비스 등록을 위한 ID로, Firebase console 을 통해 획득 할 수 있다. .. _CUID: Client ID ---------- - 사용자로 등록 할 Client 의 고유한 ID (CUID 라고도 함) - 제약은 없으며, 일반적으로, Email, UserID, Phone Number 또는 Device-UUID 등을 CUID 로 사용함. .. _CNAME: Client Name ------------ - 사용자로 등록할 Client 의 이름 (CNAME 라고도 함) - 사용자의 이름이나 Nickname 또는 Device Name 을 CNAME 으로 사용 .. _GROUPSEQ: GROUPSEQ ------------- - Group Sequence Number 의 준말로 User Group의 고유한 Sequence Number .. _PSID: PSID ------ - Push Service ID 의 줄임말 - Push 서비스에 대한 고유 ID - FCM에서 할당 받은 Device Token을 사용 .. _packagename: Packge Name ------------------------ - google play에서 안드로이드 앱을 구별하기 위한 unique 값으로, AndoridManifest.xml 에 선언한다. 3. FCM Sender ID 발급 따라하기 =========================================== - Firebase console에 프로젝트가 생성되어 있지 않은 경우, 아래 절차에 따라 프로젝틑 생성 후, Sender ID발급이 가능하다. - 절차는 '3.1. Firebase Console ~ 3.19. Sender ID 확인' 으로 구성된다. - 이미 프로젝트를 생성한 경우, :ref:`SETTINGS` 로 이동한다. 3.1. Firebase Console 접속 -------------------------------------- - https://console.firebase.google.com/ 을 입력하거나, `Go to Console `_ 을 클릭한다. .. figure:: ../../_static/cloud/android/3/3-1.png :scale: 70 % 3.2. 프로젝트 추가 ------------------------------- - 프로젝트 추가 메뉴를 클릭한다. .. figure:: ../../_static/cloud/android/3/3-2.png :scale: 70 % 3.3. 프로젝트 이름 지정 ------------------------------- - 새로운 프로젝트 생성을 하려면 1번 프로젝트 이름 입력 부분을 클릭하여, 프로젝트 이름을 입력한다. - 기존에 구성된 프로젝트를 이용하려면, 2번 리스트에 나타나는 프로젝트를 선택한다. .. figure:: ../../_static/cloud/android/3/3-3.png :scale: 70 % 3.4. 프로젝트 만들기 ------------------------------- - 프로젝트명을 입력하고, 계속을 클릭한다. - 이미지상 프로젝트명은 예시이므로, 사용하고자 하는 프로젝트명을 입력한다. .. figure:: ../../_static/cloud/android/3/3-4.png :scale: 70 % 3.5. 유의 사항 확인 ------------------------------- - Firebase를 추가할때 유의할 사항들에 대해 검토한 후, 계속을 클릭한다. .. figure:: ../../_static/cloud/android/3/3-5.png :scale: 70 % 3.6. 애널리틱스 사용여부 -------------------------------------- - 애널리틱스 사용여부에 대해 설정 후, 계속을 클릭한다. - 애널리틱스는 무료로 이용할 수 있다. .. figure:: ../../_static/cloud/android/3/3-6.png :scale: 70 % 3.7. 애널리틱스 구성 -------------------------------------- - 3.6. 애널리틱스 사용을 선택한 경우 나타나는 화면이며, 애널리틱스 계정을 선택하거나 만든 후, Firebase 추가를 클릭한다. .. figure:: ../../_static/cloud/android/3/3-7.png :scale: 70 % 3.8. 프로젝트 생성 중 -------------------------------------- - 3.7에서 Firebase 추가시 나타나는 화면이며, "새 프로젝트가 준비되었습니다." 라는 문구가 표시 될때 까지 대기한다. .. figure:: ../../_static/cloud/android/3/3-8.png :scale: 70 % 3.9. 프로젝트 생성 완료 -------------------------------------- - 프로젝트 생성 완료 화면이며, 계속을 클릭한다. .. figure:: ../../_static/cloud/android/3/3-9.png :scale: 70 % 3.10. 앱에 Firebase 추가 ----------------------------------------- - 안드로이드 앱에 FCM 을 연동하기 위해, 안드로이드 아이콘을 클릭한다. .. figure:: ../../_static/cloud/android/3/3-10.png :scale: 70 % 3.11. 앱에 Firebase 추가를 위한 정보 입력 ------------------------------------------------------- - 1번 항목에 패키지 명을 입력한다. - 화면에 나타나는 정보는 예시이며, 서비스 하고자 하는 앱의 page name 을 입력한다. - 2번 항목에 앱에 대한 nick name 을 입력한다. - nick name 은 Firebase console 에서 서비스 중인 앱의 명칭을 쉽게 확인 하기 위한 용도이다. .. figure:: ../../_static/cloud/android/3/3-11.png :scale: 70 % 3.12. google-service.json 다운로드 ----------------------------------------------------- - 앱 등록이 완료되면, google-service.json 파일이 생성된다. - google-service.json 파일은 FCM 연동시 필요하므로, 다운로드 받아 저장해 놓는다. - 참고로, google-service.json 파일은 다른 화면에서도 다운로드가 가능하다. .. figure:: ../../_static/cloud/android/3/3-12.png :scale: 70 % 3.13. build.gradle (프로젝트 수준) SDK 설정 정보 --------------------------------------------------------------------------------- - 프로젝트 수준의 build.gradle 에 포함해야 할 정보로, 복사하기 버튼을 클릭하여 복사한다. - 추후, 일괄 처리를 위해, NotePad 와 같은 프로그램을 이용하여, 복사한 정보를 저장해 놓는다. .. figure:: ../../_static/cloud/android/3/3-13.png :scale: 70 % 3.14. build.gradle (앱 수준) SDK 설정 정보 ---------------------------------------------------------- - 앱 모듈 수준의 build.gradle 에 포함해야 할 정보로, 복사하기 버튼을 클릭하여 복사한다. - 1, 2 번 모두 복사하여, 저장해 놓는다. .. figure:: ../../_static/cloud/android/3/3-14.png :scale: 70 % 3.15. 앱 설치 확인 -------------------------------------- - 앱을 실행하여, 정상적인 적용상태를 확인 하는 화면으로, 앱이 구성되지 않았으므로, 이 단계 건너뛰기를 클릭하여 다음화면으로 이동한다. .. figure:: ../../_static/cloud/android/3/3-15.png :scale: 70 % .. _SETTINGS: 3.16. 설정 메뉴 이동 -------------------------------------- - 설정 정보를 확인하기 위해, 앱 (안드로이드 아이콘)이나 더보기 아이콘 등을 선택한다. .. figure:: ../../_static/cloud/android/3/3-16.png :scale: 70 % 3.17. 설정 메뉴 클릭 ------------------------------------- - 설정 정보를 확인하기 위해, 설정 아이콘을 선택한다. .. figure:: ../../_static/cloud/android/3/3-17.png :scale: 70 % 3.18. 설정 화면 ------------------------------------- - Sender ID 값을 확인하기 위해, 클라우드 메시징 탭을 클릭한다. .. figure:: ../../_static/cloud/android/3/3-18.png :scale: 70 % .. _FCM_SENDER_ID: 3.19. Sender ID 확인 --------------------------------------- - 발신자 ID 에 나타나는 12자리 숫자를 복사하여 저장해 놓는다. .. figure:: ../../_static/cloud/android/3/3-19.png :scale: 70 % .. _FCM_SERVER_KEY: 3.20. FCM 서버 키 확인 -------------------------------------- - 서버 키 에 나타나는 값을 복사하여 저장해 놓는다. .. figure:: ../../_static/cloud/android/3/3-20.png :scale: 70 % 4. 안드로이드 프로젝트 생성 따라하기 ======================================================== 안드로이드 프로젝트를 생성하는 가이드로, '4.1. 생성 ~ 4.3. package name / 프로젝트명 입력'으로 구성된다. 4.1. 생성 ------------------------------------- - Start a new Android Studio .. figure:: ../../_static/cloud/android/4/4-1.png :width: 800 4.2. 템플릿 선택 ------------------------------------- - 사용하고자 하는 템플릿을 선택한다. .. figure:: ../../_static/cloud/android/4/4-2.png :width: 800 4.3. package name / 프로젝트명 입력 --------------------------------------------------- - 1번 : 프로젝트 명을 입력한다. - 2번 : 사용하고자 하는 page name 입력한다. (domain 형식, 소문자) - 3번 : 프로젝트 저장 위치를 지정한다. - 4번 : 프로젝트 생성을 완료 한다. .. figure:: ../../_static/cloud/android/4/4-3.png :width: 800 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 파일을 복사 .. figure:: ../../_static/cloud/android/5/5-1.png :width: 800 5.2. View 를 Project 로 변환 -------------------------------------- - ProjectViews 에서 Group Tab 을 클릭하여, Project 선택 .. figure:: ../../_static/cloud/android/5/5-2.png :width: 800 5.3. google-service.json 적용 상태 체크 -------------------------------------------------------------------- - app module 하위에 google-service.json 파일이 적용되어 있는지 확인 .. figure:: ../../_static/cloud/android/5/5-3.png :width: 800 5.4. 프로젝트 단위 build.gradle 적용 --------------------------------------------------------------- - 1번 : 프로젝트 단위의 build.gradle 파일을 연다. - 2번 : buildscript 에 dependencies 부분에, classpath 적용 .. code-block:: javascript classpath 'com.google.gms:google-services:4.3.3' .. figure:: ../../_static/cloud/android/5/5-4.png :width: 800 - Sample .. code-block:: javascript 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에 라이브러리를 적용한다. .. code-block:: javascript // 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 적용 .. code-block:: javascript apply plugin: 'com.google.gms.google-services' .. figure:: ../../_static/cloud/android/5/5-5.png :width: 800 - Sample .. code-block:: javascript 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번을 이용하여, 동기화를 진행한다. .. figure:: ../../_static/cloud/android/5/5-6.png :width: 800 5.7. 프로젝트 동기화 상태 확인 -------------------------------------------------- - 아래 3 가지 정보가 일치해야, 셋팅이 정상적으로 된 것으로 판단할 수 있다. - 1번 : build.gradle 파일 위치 점검 - 2번 : Run 'app' 버튼이 활성화 - 3번 : Build console 에서, 'CONFIGURE SUCCESSFUL' 문구 확인 .. figure:: ../../_static/cloud/android/5/5-7.png :width: 800 6. PUSH SDK 및 Manifest.xml 설정 ========================================= 6.1. 라이브러리 적용 ------------------------------------------ - app > libs 폴더에 아래 라이브러리를 적용한다. .. code-block:: javascript 가. morpheus_push_library_fcm_xxx.jar 나. mqtt-android-push_xxx.jar .. figure:: ../../_static/cloud/android/6/6-1.png :width: 800 6.2. assets 폴더 및 Manifest.xml 파일 생성 ------------------------------------------------------- - assets 폴더를 생성한다. - assets 폴더는 app > src > main > assets 위치한다. .. figure:: ../../_static/cloud/android/6/6-2.png :width: 800 - Manifest.xml 파일은 app > src > main > assets > res > Manifest.xml 에 위치 한다. .. figure:: ../../_static/cloud/android/6/6-2-1.png :width: 800 6.3 Manifest.xml 설정 ---------------------------------- - PUSH SDK에서 사용하기 위한 Manifest.xml 을 생성한다. (AndroidManfiest.xml 과는 다른 파일임) - :ref:`FCM_SENDER_ID` 을 통해, 획득한 sender id 확인한다. - `PROJECT ID `_ 를 확인하다. - 적용순서 .. code-block:: javascript 가. Cloud Console 에서 발급받은 project id를 에 입력 나. 접속할 서버 정보를 에 입력 다. Firebase Console 에서 획득한 발신자 id (sender id) 를 에 입력한다. 라. log 와 file log 는 필요시 수정한다. - Manifest.xml 예시 .. code-block:: xml 123456589 y y 5.0 https://umpc.message-ai.net 20000 123456789101 FCM Y .. note:: project-id 는 서비스그룹 생성 시 발급되는 서비스그룹아이디 `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를 생성한다. .. figure:: ../../_static/cloud/android/6/6-4.png :width: 800 6.5. MessageArrivedReceiver.java class 생성 ------------------------------------------------------- - 푸시를 받을 MessageArrivedReceiver class 를 생성한다. .. figure:: ../../_static/cloud/android/6/6-5.png :width: 800 .. figure:: ../../_static/cloud/android/6/6-5-1.png :width: 800 - MessageArrivedReceiver 는 BroadcastReceiver 를 상속받아 생성한다. .. figure:: ../../_static/cloud/android/6/6-5-2.png :width: 800 - MessageArrivedReceiver 예시 .. code-block:: java 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 설정 ----------------------------------------- - 푸시를 위한 서비스 등록 및 메시지 수신을 위한 설정을 한다. .. code-block:: javascript 가. service 등록 : FCMIntentService 나. receiver 등록 : MessageArrivedReceiver, FcmActionReceiver 다. permission 등록 : ${applicationId}.permission.MPUSH_PERMISSION 라. uses-permission 등록 : ${applicationId}.permission.MPUSH_PERMISSION, android.permission.WAKE_LOCK .. figure:: ../../_static/cloud/android/6/6-6.png :width: 800 - AndroidManifest.xml 예시 .. code-block:: xml 6.7. 빌드 ------------------ - `디바이스 개발자 옵션 활성화 `_ 를 진행한다. - PC와 디바이스를 USB로 연결한다. - 빌드할 디바이스를 선택하고, 활성화된 Run 버튼을 이용하여, Build 를 실행한다. .. figure:: ../../_static/cloud/android/6/6-7.png :width: 800 6.8. 로그 보기 ------------------ - Android Studio 하단에 Logcat 탭을 선택한다. - Manifest.xml 의 log 를 y로 설정한다. - 빌드를 통해, 앱을 실행한다. - 1번 : 로그를 보고자 하는 Device, package name 을 선택하고, log level 을 설정한다. - 2번 : Show only selected applicatoin 을 선택하면, 선택한 package name 에 해당하는 앱의 로그만 볼 수 있다. - 3번 : 디바이스에서 출력하는 로그를 확인 할 수 있다. .. figure:: ../../_static/cloud/android/6/6-8.png :width: 800