=================================== 안드로이드 =================================== 1. 개요 ========= Morpheus Cloud Push 를 사용하기 위해, Client와 UPMC 서버간 통신을 원활하게 할 수 있도록 제공하는 라이브러리의 API 명세서 이다. 2. DataFlow Diagram ------------------- .. figure:: ../../_static/cloud/android/fcm-workflow.png :scale: 70 % 3. Push APIs ======================= .. _InitializePush: Initialize Push --------------------------- .. c:function:: PushManager.getInstance().initPushServer(Context context, JSONObject params); - Manifest.xml 설정 파일에서 라이브러리를 초기화하기 위한 정보를 가져온다 :param Context context: 현재 Context :param JSONObject params: 정보셋팅 - JSONObject key 값에 대한 설명 ============================================= ========== ============= Key Type Description ============================================= ========== ============= PushConstants.KEY_CNAME String 사용자 닉네임 PushConstants.KEY_DEVICE_ID String 디바이스id PushConstants.KEY_CUSTOM_RECEIVER_SERVER_URL String UPMC url ============================================= ========== ============= .. code-block:: java - 예시 : JSONObject params = new JSONObject(); // http://xxx.xxx.x.xx:xxxx 연결할 리시버 서버 url params.put(PushConstants.KEY_CUSTOM_RECEIVER_SERVER_URL, "http://xxx.xxx.x.xx:xxxx"); .. warning:: :ref:`InitializePush` 는 custom 정보를 입력하고자 하는 경우에만 호출 한다. Register Service and User --------------------------- .. c:function:: PushManager.getInstance().registerServiceAndUser(Context context, String cuid, String cname); - :ref:`CUID` 와 :ref:`CNAME` 으로 User 등록 - 푸시 서비스를 등록함. :param Context context: 현재 Context :param String cuid: :ref:`CUID` 값 :param String cname: :ref:`CNAME` 값 -결과값 : Reciver 를 통해, 처리 결과 통보 .. c:function:: PushManager.getInstance().registerServiceAndUser (Context context, JSONObject params); - :ref:`CUID` 와 :ref:`CNAME` 으로 User 등록 - 푸시 서비스를 등록함. - DEVICE ID를 CUSTOM 등록시 사용할 수 있음. :param Context context: 현재 Context :param JSONObject params: 정보셋팅 - JSONObject key 값에 대한 설명 ============================ ========== ============ ============= Key Type Necessary Description ============================ ========== ============ ============= PushConstants.KEY_CUID String 필수 :ref:`CUID` PushConstants.KEY_CNAME String 필수 :ref:`CNAME` PushConstants.KEY_DEVICE_ID String 선택 Device ID ============================ ========== ============ ============= -결과값 : Reciver 를 통해, 처리 결과 통보 .. _unregisterUser: UnRegister User --------------------------- .. c:function:: PushManager.getInstance().unregisterPushUser(Context context, String cuid, String cname); - :ref:`CUID` 와 :ref:`CNAME` 으로 User 등록해제 - 푸시 서비스를 이용할 사용자를 등록해제 한다 :param Context context: 현재 Context :param String cuid: :ref:`CUID` 값 :param String cname: :ref:`CNAME` 값 -결과값 : Reciver 를 통해, 처리 결과 통보 .. c:function:: PushManager.getInstance().unregisterPushUser (Context context, JSONObject params); - :ref:`CUID` 와 :ref:`CNAME` 으로 User 등록 해제 - 푸시 서비스를 이용할 사용자를 등록해제 한다. :param Context context: 현재 Context :param JSONObject params: 정보셋팅 - JSONObject key 값에 대한 설명 ============================ ========== ============ ============= Key Type Necessary Description ============================ ========== ============ ============= PushConstants.KEY_CUID String 필수 :ref:`CUID` PushConstants.KEY_CNAME String 필수 :ref:`CNAME` ============================ ========== ============ ============= -결과값 : Reciver 를 통해, 처리 결과 통보 .. note:: :ref:`unregisterUser` 후 :ref:`UPMC` 에 등록된 사용자의 CUID 값은 GUEST로 변경되며, GUEST 발송 시, 클라이언트에서 수신이 가능하다. .. _unregisterService: Unregister Service -------------------- .. c:function:: PushManager.getInstance().unregisterPushService(Context context); - FCM or UPNS에 푸시 서비스를 해제 한다. :param Context context: 현재 context -결과값 : Reciver 를 통해, 처리 결과 통보 .. c:function:: PushManager.getInstance().unregisterPushService(Context context, JSONObject params); - FCM or UPNS에 푸시 서비스를 해제 한다. :param Context context: 현재 Context :param JSONObject params: 정보셋팅 - JSONObject key 값에 대한 설명 ============================ ========== ============ ============= Key Type Necessary Description ============================ ========== ============ ============= PushConstants.KEY_CNAME String 선택 :ref:`CNAME` PushConstants.KEY_DEVICE_ID String 선택 Device ID ============================ ========== ============ ============= .. code-block:: java - 예시 : JSONObject params = new JSONObject(); params.put(PushConstants.KEY_DEVICE_ID, "DEVICE-A73E9E2E9C6B11E4AFAEC55006B96D3C"); .. note:: :ref:`unregisterService` 후 :ref:`UPMC` 에 등록된 사용자 정보는 delete 되며, 재 등록하지 않는 한, 발송이 불가능 하다. Read Push Message --------------------- .. c:function:: PushManager.getInstance().pushMessageReadConfirm (Context context, String notification); - 통계를 위한 API로, 사용자가 메시지를 읽은 경우, 메시지 확인 전문을 전송한다. :param Context context: 현재 context :param String notification: 수신한 push message(JSONObject의 string값) .. c:function:: PushManager.getInstance().pushMessageReadConfirm (Context context, String notification, int badgeCountType); - 통계를 위한 API로, 사용자가 메시지를 읽은 경우, 메시지 확인 전문을 전송하며, 서버와 badge count를 동기화 한다. :param Context context: 현재 context :param String notification: 수신한 push message(JSONObject의 string값) :param int badgeCountType: - badgeCountType key 값에 대한 설명 ================================ ========== =============================================================== Key Type Description ================================ ========== =============================================================== PushConstants.BADGE_TYPE_KEEP String 1개 읽음 처리, 다음 메시지 수신시, 동일한 값 유지(Default, -1 후 +1 이 됨) PushConstants.BADGE_TYPE_RESET String 입력 값으로 초기화, 다음 수신된 값은 입력값 +1로 처리됨 PushConstants.BADGE_TYPE_UPDATE String 카운트에 따라 업데이트 됨 (읽음여부에 상관없이, push 수신 ++) ================================ ========== =============================================================== Receive Push Message ------------------------ .. c:function:: PushManager.getInstance().pushMessageReceiveConfirm (Context context, String notification); - 통계를 위한 API로 FCM으로 메시지 수신 시, :ref:`UPMC`에 수신 확인 상태를 전송한다. :param Context context: 현재 context :param String notification: 수신한 push message(JSONObject의 string값) .. _registerGroup: Register Group -------------------- .. c:function:: PushManager.getInstance().registerUserGroup (Context context, String groupSeq); - 사용자 그룹에 등록한다. :param Context context: 현재 context :param String groupSeq: 등록하고자 하는 그룹의 sequence number .. note:: :ref:`registerGroup` 의 sequence number는 로그인 등 별도의 api를 통해, 확보되어 있어야 한다. UnRegister Group -------------------- .. c:function:: PushManager.getInstance().unregisterUserGroup (Context context, String groupSeq); - 사용자 그룹에서 등록을 해제 한다. :param Context context: 현재 context :param String groupSeq: 해제하고자 하는 그룹의 sequence number Init Badge Number -------------------------- .. c:function:: PushManager.getInstance().initBadgeNo (Context context, String badgeNo); - 서버의 Badge NO를 강제 셋팅 또는 초기화 (클라이언트와 동기화를 위해 사용한다.) - Badge NO 최소값 : 0 - Badge NO 최대값 : 1000 :param Context context: 현재 context :param String badgeNo: 서버에서 관리되는 뱃지 count에 대한 초기값 (0을 셋팅하는 경우, push수신시 1로 셋팅됨) Set DeviceBadge Count -------------------------- .. c:function:: PushManager.getInstance().setDeviceBadgeCount (Context context, String badgeNo); - 폰의 Badge NO를 표기함 - 폰의 설치된 런처에 따라, 작동하지 않을 수 있음 - Android 8.0 이상에서는, 제조사별로 상이하게 동작할 수 있다. - Badge NO 최소값 : 0 - Badge NO 최대값 : 1000 :param Context context: 현재 context :param String badgeNo: 서버에서 관리되는 뱃지 count에 대한 초기값 (0을 셋팅하는 경우, push수신시 1로 셋팅됨) 4. Push APIs 키값 정의 =================================== .. _BUNDLEKEY: API 호출에 따른 결과값 (BroadCastReceiver bundle key) ----------------------------------------------------------------------------- ======================================================= =============================================================== Key Description (결과값) ======================================================= =============================================================== PushConstantsEx.COMPLETE_BUNDLE.REG_USER 사용자 등록 PushConstantsEx.COMPLETE_BUNDLE.UNREG_USER 사용자 등록 PushConstantsEx.COMPLETE_BUNDLE.UPDATE_PUSHSERVICE_DATE push service 갱신 PushConstantsEx.COMPLETE_BUNDLE.REG_PUSHSERVICE 푸시 서비스 등록 PushConstantsEx.COMPLETE_BUNDLE.UNREG_PUSHSERVICE 푸시 서비스 해제 PushConstantsEx.COMPLETE_BUNDLE.READ_CONFIRM 읽음 ack PushConstantsEx.COMPLETE_BUNDLE.RECEIVE_CONFIRM 수신 ack (FCM only) PushConstantsEx.COMPLETE_BUNDLE.IS_REGISTERED_SERVICE 서비스 등록 여부 (register service 호출 시, 수신 될 수 있음) PushConstantsEx.COMPLETE_BUNDLE.INITBADGENO 뱃지 넘버 초기화 PushConstantsEx.COMPLETE_BUNDLE.REG_GROUP 그룹 등록 PushConstantsEx.COMPLETE_BUNDLE.UNREG_GROUP 그릅 해제 ======================================================= =============================================================== .. _STATUSCODE: BroadCastReceiver bundle key return 값 (STATUS CODE - 통신관련) --------------------------------------------------------------------------------- ======================================================= =============================================================== Key Description (결과값) ======================================================= =============================================================== PushConstants.RESULTCODE_OK 정상 PushConstants.RESULTCODE_HTTP_ERR 통신 오류 - UPMC서버에 접속할 수 없을때 - connection 관련 error PushConstants.RESULTCODE_AUTHKEY_ERR 인증키 획득 오류 PushConstants.RESULTCODE_RESPONSE_ERR 응답 오류 - 오류코드를 수신한 경우 PushConstants.RESULTCODE_INTERNAL_ERR 정의되지 않은 예기치 못한 오류가 발생한 경우 PushConstants.RESULTCODE_AUTHKEY_ERR2 인증키 획득 오류 ======================================================= =============================================================== .. _BROADCASTINTENT: BroadCastReceiver Intent 관련 키값 (처리 결과 ) ----------------------------------------------------------------- ======================================================= =============================================================== Key Description (결과값) ======================================================= =============================================================== PushConstants.KEY_RESULT ACTION_COMPLETED에 Extras용 전체 호출값 PushConstants.KEY_BUNDLE 번들용 KEY PushConstants.KEY_ISREGISTER 서비스 등록 여부에 대한 결과값 PushConstants.KEY_RESULT_CODE 결과 코드 (정상 : 200) PushConstants.KEY_RESULT_MSG upmc 통신 이후, 수신된 메시지 ======================================================= =============================================================== 5. FCM Push Payload [ :ref:`FCM` ] ==================================== - 아래 기술된 메시지는 샘플에 대한 예시이며, 프로젝트에서 표현하고자 하는 방식에 따라, Interface 정의서에 의해, 변경이 가능함. - JSONObject key 값에 대한 설명 [key가 소문자임] ================ =========================================================================== Key 활용방법 ================ =========================================================================== alert 메시지 타이틀로 이용 alert.aif 수신음 파일명 (적용여부는 상황에 맞게 판단) ext 일반 메시지인 경우, 메시지로 이용가능하며, Rich 메시지인 경우, 세부 정보를 추가로 획득하여, 표현 seqno Push message의 고유 키값 appid Push 서비스가 관리되는 앱 ID ( :ref:`ApplicationID`) sender 발송자 코드 (서버관점) senddate 발송된 시간 (서버관점) db_in DB에 저장 여부 (서버 관점) badge 뱃지값 pushkey public push의 토큰 유효성을 위해 관리되는 키 (서버관점) ================ =========================================================================== 일반(text) push 메시지 예시 ---------------------------------------------- .. code-block:: javascript { "aps":{ "badge":"14", "sound":"alert.aif", "alert":"일반 알림" }, "mps":{ "appid":"com.uracle.push.test", "ext":"메세지 테스트", "seqno":"288", "sender":"device-android", "senddate":"2016041409", "db_in":"Y", "pushkey":"2427efdf1b62cd9dbdf174bbdff048f8051461e1" } } 동영상 push 메시지 예시 --------------------------------------------- .. code-block:: javascript { "aps":{ "badge":"16", "sound":"alert.aif", "alert":"동영상 알림" }, "mps":{ "appid":"com.uracle.push.test", "ext":"7|기본동영상|http://lab.morpheus.kr/push/sample/image|https://youtu.be/IIu0VMdOe10", "seqno":"292", "sender":"device-android", "senddate":"2016041409", "db_in":"Y", "pushkey":"2427efdf1b62cd9dbdf174bbdff048f8051461e1" } } 이미지 push 메시지 예시 -------------------------------------------- .. code-block:: javascript { "aps":{ "badge":"17", "sound":"alert.aif", "alert":"이미지 알림" }, "mps":{ "appid":"com.uracle.push.test", "ext":"8|기본이미지|http://lab.morpheus.kr/push/sample/image", "seqno":"294", "sender":"device-android", "senddate":"2016041409", "db_in":"Y", "pushkey":"2427efdf1b62cd9dbdf174bbdff048f8051461e1" } } 6. 방화벽 OPEN [for Client] ==================================== - FCM:: fcm.googleapis.com 443,5228,5229,5230 - `FCM 참고 문서 `_ - FCM 포트 및 방화벽:: 조직에 인터넷 트래픽 송수신을 제한하는 방화벽이 있으면 모바일 기기의 FCM 연결을 허용하도록 구성해야 네트워크의 기기에서 메시지를 수신할 수 있습니다. FCM은 대개 포트 5228을 사용하지만 5229 및 5230을 사용하는 경우도 있습니다. 발신 연결의 경우 Google IP 범위가 매우 자주 변경되며 개발자의 방화벽 규칙이 오래되면 사용자 경험에 영향을 줄 수 있으므로 FCM에서 특정 IP를 제공하지 않습니다. IP 제한 없이 포트 5228~5230을 허용하는 것이 가장 좋습니다. 하지만 IP 제한이 있어야 한다면 Google ASN 15169에 나와 있는 IPv4 및 IPv6 블록의 모든 IP 주소를 허용해야 합니다. 목록의 크기가 크며 규칙을 매월 업데이트하도록 계획을 세워야 합니다. 방화벽 IP 제한으로 인해 발생하는 문제는 보통 간헐적이며 진단하기 어렵습니다. - 수신 메시지용으로 열어야 하는 포트:: 5228 5229 5230 - 발신 연결을 허용하는 포트:: 다음 중 하나(1번 옵션 권장): 1. IP 제한 없음 2. Google ASN 15169 에 나와 있는 IP 블록에 포함된 모든 IP 주소: 한 달에 한 번 이상 업데이트해야 합니다. - `Google ASN 15169 문서 `_ 7. 용어 =============== .. _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 을 할당 받고 :ref:`UPMC` 로 Push 서비스를 사용하고, 사용자에게 적용 하겠다고 등록하는 절차 .. _UnregisterService: Service 해제 ----------------------- - :ref:`UPMC` 로 Push 서비스를 사용하지 않겠다고 등록을 삭제하는 절차 .. _RegisterUser: User 등록 ------------- - :ref:`UPMC` 로 Push 서비스에 대한 사용자를 등록 또는 변경하는 절차 .. _receiveMessage: 수신 확인 ------------- - 메시지를 수신 후 :ref:`UPMC` 로 Ack를 주는 절차 - Android 6.0 Doze 모드에 따라, 라이브러리 자동 처리 방식에서, App에서 method를 호출하는 방식으로 변경됨 .. _ReadMessage: 읽음 확인 ------------- - App에서 메세지를 읽었을때 :ref:`UPMC` 로 Ack를 주는 절차 .. _ApplicationID: Application ID ---------------- - AppID라고도 함 - App의 lic 파일에 포함된 application_id 값으로 앱을 구분하기 위한 코드값. .. _FCMsenderid: FCM Sender ID ---------------- – FCM 서비스 등록을 위한 ID .. _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을 사용