====== PushNotifications 디바이스API 가이드 프로그램 ======

===== 개요 =====

PushNotifications API 기능은 구글의 클라우드 메세지 서비스(GCM)를 이용하여 모바일 앱 사용자에게 다양한 푸시 메세지를 전달할 수 있는 기능을 제공함

==== 특징 ====
본 가이드 프로그램 에서는 Push알림 기능의 활용을 가이드 할 수 있도록 **기기등록**, **기기목록보기**, 
**송신내역보기** 를 제공하고 있다. \\

==== 시작 전 ====
본 가이드 프로그램을 시작 전 사전 GCM(Google Cloud Messaging)에서 사전 앱 등록 및 key 발급 후 진행 하셔야합니다.\\
[[https://developers.google.com/cloud-messaging/|GCM앱 등록 및 key 발급]]


==== 기능흐름도 ====
{{:egovframework:hyb3.6:guide:mbl:pushnotifications:pushnotifications_in.jpeg?700|}}

==== 전제 조건 ====

^           구분            ^             내용             ^
|Local 디바이스 개발 환경|전자정부표준프레임워크 개발환경3.6, Android SDK API 23(version 6.0 Marshmallow)|
|서버 사이드 개발 환경|전자정부표준프레임워크 개발환경3.6|
|Mash up Open API 연계|N/A|
|테스트 디바이스 |Galaxy S2, G5|
|테스트 플랫폼 |Android 2.3, Android 6.0 |
|추가 라이브러리 적용|android-support-v4.jar, com.google.zxing.client.android.captureactivity.jar, google-play-services.jar|

==== 제약사항 ====

^           구분            ^             내용             ^
|지원 디바이스 및 플랫폼|N/A|
|크로스 도메인 사용|폰갭에서 특정 외부 도메인이나 외부 도메인의 하위 도메인을 사용해야할 경우,\\ Res/xml/config.xml에서 <access origin="" />에 외부 도메인 주소를 추가 설정해야 외부 도메인에 접속할 수 있다.|
|라이선스|N/A|

===== 설명 ===== 
PushNotifications API 가이드 프로그램은 크게 **기기등록**, **기기목록보기**, **송신내역보기**  \\
기능으로 구성되어 있다.(관련기능 부분참조)

==== Device Application ====

=== 관련 소스 ===

^유형^대상소스명^비고^
|Activity|kr.go.egovframework.hyb.DeviceInfoapi.DeviceInfoAPIGuide_AndroidActivity|PushNotificationsAPI 가이드 프로그램 Activity Class|
|CSS|assets/www/css/egovframwork/mbl/hyb/PushNotificationsAPI.css |PushNotificationsAPI 가이드 프로그램 주요 Cascading Style Sheets|
|IMAGE |assets/www/images/egovframwork/mbl/hyb/ |PushNotificationsAPI 가이드 프로그램 주요 Image 폴더|
|JS |assets/www/js/egovframwork/mbl/hyb/PushNotificationsAPI.js |PushNotificationsAPI 가이드 프로그램 주요 JavaScript|
|RES |assets/www/res/ |PushNotificationsAPI 가이드 프로그램 주요 Resource 폴더|
|XML |AndroidManiFest.xml |안드로이드 어플리케이션 설정 XML|
|HTML|assets/www/PushNotifications.html|PushNotificationsAPI 메인 페이지|
|HTML|assets/www/intro.html|PushNotificationsAPI Intro 페이지|
|HTML|assets/www/license.html|PushNotificationsAPI 라이센스 페이지|
|HTML|assets/www/overview.html|PushNotificationsAPI 기능설명 페이지|

=== 활용 API ===

== device ==
  * 모바일 디바이스의 하드웨어 및 소프트웨어 관련 메타 정보를 조회한다.


<code>
	var uuid;
        var osVer;
        var token_id;
        var osType;      

</code>


^변수^설명^비고^
|uuid|디바이스 고유의 UUID를 반환한다.| |
|version|디바이스의 플랫폼 버전을 반환한다.| |
|token_id| 앱에 고유의 token_id를 반환한다.| |
|osType|디바이스 OS타입을 반환한다.| |


== Event[batterycritical] == 
  * 배터리 상태가 Critical 레벨에 도달 했을때 호출되는 콜백함수 정의
<code>
window.addEventListener("batterycritical", yourCallbackFunction, false);
</code>

== Event[batterylow] == 
  * 배터리 상태가 Low 레벨에 도달 했을때 호출되는 콜백함수 정의
<code>
window.addEventListener("batterylow", yourCallbackFunction, false);
</code>

== Event[batterystatus] == 
  * 배터리 상태에 변화가 감지되면 호출되는 콜백함수 정의
<code>
window.addEventListener("batterystatus", yourCallbackFunction, false);
</code>

==== Server Application ====

=== 관련 소스 ===

^유형^대상소스명^비고^
|Controller|egovframework.hyb.add.dvc.web.EgovPushDeviceAPIController.java|PushnotificationsAPI 가이드 프로그램 Controller Class|
|Service|egovframework.hyb.add.dvc.service.EgovPushDeviceAPIService.java|PushnotificationsAPI 가이드 프로그램  Service Class|
|ServiceImpl|egovframework.hyb.add.dvc.service.impl.EgovPushDeviceAPIServiceImpl.java|PushnotificationsAPI 가이드 프로그램  ServiceImpl Class|
|VO|egovframework.hyb.add.dvc.service.PushDeviceAPIVO.java|PushnotificationsAPI 가이드 프로그램 VO Class|
|DAO|egovframework.hyb.add.dvc.service.impl.PushDeviceAPIDAO.java|PushnotificationsAPI 가이드 프로그램 Dao Class|
|QUERY XML|resources/egovframework/sqlmap/hyb/mbl/pus/EgovPushDeviceAPIGuide_SQL_xxx.xml|PushnotificationsAPI 가이드 프로그램 QUERY XML|


=== 관련 테이블 ===
^테이블명^테이블명(영문)^비고^
|Push디바이스|push_device|Push디바이스 정보 관리|
|Push메세지|push_message|Push 메세지 정보 관리|



=== 테이블 정의서 ===

 * push_device

^No^컬럼ID^컬럼명^타입^길이^NULL^
|1|SN|일련번호|NUMERIC|6|NotNull|
|2|UUID|UUID|VARCHAR|50|NotNull|
|3|OS_VER|디바이스 버전|VARCHAR|2000|Null|
|4|DEVICE_NM|디바이스 코도바 버전|VARCHAR|20|Null|
|5|TOKEN_ID|앱 고유 번호|VARCHAR|250|NotNull|
|6|osType|디바이스 OS타입|VARCHAR|20|Null|
|7|USEYN|활성화여부|CHAR|1|Null|

 * push_message

^No^컬럼ID^컬럼명^타입^길이^NULL^
|1|SN|일련번호|NUMERIC|6|NotNull|
|2|UUID|UUID|VARCHAR|50|NotNull|
|3|MESSAGE|메세지|VARCHAR|2000|Null|
|4|SND_DT|메세지 발송 시간|VARCHAR|20|Null|
|5|TOKEN_ID|앱 고유 번호|VARCHAR|250|NotNull|
|6|osType|디바이스 OS타입|VARCHAR|20|Null|
|7|PG_VER|폰갭버전|VARCHAR|40|Null|
|8|DEVICE_NM|디바이스명|VARCHAR|200|Null|
|9|USEYN|활성화여부|CHAR|1|Null|


=== ERD ===
{{:egovframework:hyb3.6:guide:mbl:newapi_erd.jpg?800|}}

===== 환경설정 ===== 

PushNotifications API 가이드 프로그램에서 제공하는 모바일 디바이스의 메타 정보 조회 기능을 활용하기 위하여 필요한 항목 및 그 환경 설정은 다음과 같다.

==== Device Application ====

=== res/xml/config.xml ===

<code xml>
    <!--전자정부 Interface 디바이스 API를 사용하기 위한 Phonegap Plugin 클래스-->
    <plugin name="EgovInterfacePlugin" value="kr.go.egovframework.hyb.plugin.EgovInterfacePlugin" />
</code>

=== res/values/serverinfo.xml ===

<code xml>
    <!--전자정부 Interface 디바이스 API에서 사용하기 위한 서버경로 설정-->
    <?xml version="1.0" encoding="utf-8"?>
    <resources>
	<string name="SERVER_URL">http://192.168.100.222:8080/DeviceAPIGuideTotal_Web_V1.7.1</string>
    </resources>
</code>

=== AndroidManifest.xml ===

<code xml>
	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
	<uses-permission android:name="android.permission.GET_ACCOUNTS" />
	<uses-permission android:name="android.permission.WAKE_LOCK" />
	<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
	<permission android:name="kr.go.egovframework.hyb.example.permission.C2D_MESSAGE" android:protectionLevel="signature" />
	<uses-permission android:name="kr.go.egovframework.hyb.example.permission.C2D_MESSAGE" />

	<activity android:exported="true" android:name="com.plugin.gcm.PushHandlerActivity" />
	<receiver android:name="com.plugin.gcm.CordovaGCMBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND">
	        <intent-filter>
	            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
	            <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
	            <category android:name="kr.go.egovframework.hyb.example" />
	        </intent-filter>
	</receiver>
	<service android:name="com.plugin.gcm.GCMIntentService" />
</code>


==== Server Application ====

=== resource/egovframework/sqlmap/sql-map-config_[DB명].xml ===
<code xml>
<sqlMap resource="egovframework/sqlmap/hyb/add/dvc/EgovDeviceAndroidAPIGuide_SQL_[DB명].xml"/>
</code>

=== GCM Push 발급 Key 입력 ===
 * src/main/java/egovframework/com/push/GCMPush.java

<code java>
public class GCMPush {

	public static void main(String[] args) {
		// TODO Auto-generated method stub
		Sender sender = new Sender("발급 API Key 입력"); // 서버 API Key 입력
		String regId = "단말기 RegID 입력"; // 단말기 RegID 입력
		 
		Message message = new Message.Builder().addData("msg", "push notify!!! syh").build();
		List<String> list = new ArrayList<String>();
		list.add(regId);
		MulticastResult multiResult;
		
		try {
			multiResult = sender.send(message, list, 5);
			if (multiResult != null) {
				List<Result> resultList = multiResult.getResults();
				for (Result result : resultList) {
					System.out.println(result.getMessageId());
				}
			}
		} catch (IOException e) {
			// TODO Auto-generated catch block
			e.printStackTrace();
		}
	}
	
}

</code>



===== 관련기능 ===== 
PushnotificationsAPI 가이드 프로그램은 크게 디바이스 내 메타 정보 조회 기능과 조회된 메타 정보를 서버에 전송하고 조회할수 있는 기능으로 구성되어 있다.

==== 디바이스 정보 조회하기 ====

=== 비즈니스 규칙 ===
  * 네트워크를 체크하여 Wi-Fi가 아닐 경우에는 사용자 승인여부에 따라 동작한다.


=== 관련 코드 ===

== 디바이스 정보 VO ==
<code>
/** 디바이스 정보  VO */

    sn : "",
    uuid : "",
    deviceNm : "",
    osVer : "",
    useYn : "",
    osType : "",
    tokenId : "",
    message : "",
    sndDt : ""

</code>

== 디바이스 정보 화면 표시 ==
<code>
function fn_egov_deviceInfo(){
		
	
		
    $('.PushInfo:eq(0)').html(device.platform + " " + device.version);
    $('.PushInfo:eq(1)').html(device.uuid);
    $('.PushInfo:eq(2)').html(token_id);    
    
    $.mobile.changePage("#deviceInfo", "slide", false, false);
    
    detailScroll.refresh();
    
    
}
</code>



=== 관련 화면 및 수행매뉴얼 ===

^디바이스 정보조회 화면^
|{{:egovframework:hyb3.6:guide:mbl:pushnotifications:pushnotifications_2.jpeg?320|}}|

OS: 플랫폼 정보 및 버전 \\
UUID : 디바이스의 고유 아이디 \\
Token ID : 디바이스 앱의 고유 아이디 \\

==== 디바이스 정보 서버에 전송하기 ====

=== 관련 코드 ===

== 디바이스 정보 등록==
<code>
function fn_egov_save_push_deviceInfo() {

	
    useYn = "Y";
    
    var url = "/pus/addPushDeviceInfo.do"; 
    var accept_type = "json";
    
    var params = {
        uuid :  device.uuid , 
        osVer :  String(device.version) ,
        osType :  device.platform , 
        ntwrkDeviceInfo :  deviceInfoVO.ntwrkDeviceInfo , 
		deviceNm : device.cordova ,
		useYn : "Y" ,
		tokenId : token_id};
      
    window.plugins.EgovInterface.request(url, params, function(jsondata) {
        //var data = JSON.parse(jsondata);
        //alert("jsondata : "+jsondata);

        if(jsondata.resultState == "OK"){
            //fn_goDeviceInfoListXml();
        	        	
        	$.mobile.changePage("#main", "slide", false, false);
        	
        }else{
            $("#alert_dialog").click( function() {
                jAlert('데이터 전송 중 오류가 발생 했습니다.', '전송 오류', 'c');
                });
        }            
        
    }, function(result){
    	console.log("error > "+result);
    });
    
    console.log("DeviceAPIGuide fn_egov_regist_deviceInfo request Completed");
    
    
}
</code>

=== 관련 화면 및 수행매뉴얼 ===

^Action^URL^Controller method^QueryID^
|디바이스 정보 등록|/pus/addPushDeviceInfo.do|insertDeviceInfo|"pushDeviceAPIDAO.insertPushDevice"|

기기 등록: 디바이스 정보를 서버로 업로드 한다.
메인화면 이동 : 첫 화면으로 이동한다.

==== 디바이스 정보 목록 조회하기 ====

=== 관련 코드 ===

== 디바이스 정보 목록 조회 ==

<code>
function fn_egov_push_deviceInfoList() {
	
    var url = "/pus/pushDeviceInfoList.do";
    var accept_type = "json";
    var params = {uuid : device.uuid};
    
    // get the data from server
    window.plugins.EgovInterface.request(url, params, function(jsonData) {
        var list_html = "";
        
        console.log(">>> resultData = "+jsonData);
        
        $(jsonData["pushDeviceInfoList"]).each(function(idx,obj){
/*        	console.log("\n\n\n\n\n#>>>>>obj = "+idx + "/" + obj);
        	console.log("#>>>>>obj = "+obj.uuid+"\n\n\n\n");*/
        	
        	var sn = obj.sn;
        	var uuid = obj.uuid;
        	var osType = obj.osType;
        	var tokenId = obj.tokenId;
        	
        	
            list_html += "<li><a href='javascript:fn_egov_request_push_deviceInfoDetail(" + sn + ")'><h3>UUID : " +uuid + "</h3>";
            list_html += "<p><strong>Token ID" + tokenId + "</strong></p>";
            list_html += "<p>OS : " + osType + "</p></a></li>";
        });
        
        console.log("DeviceAPIGuide fn_egov_move_deviceInfoList request Completed");
                
        var theList = $('#theList');
        theList.html(list_html);
        $.mobile.changePage("#deviceInfoList", "slide", false, false);
        theList.listview("refresh");
        
        listScroll.refresh();
        
    });    
}
</code>


== 디바이스 정보 상세 조회 및 메세지 발송 ==

<code>
function fn_egov_send_devicePushInfo() {
   
    var url = "/pus/requestPushInfo.do"; 
    var p_message = $("#message").val();
    var p_osType = $(".pusdeviceInfoVO:eq(0)").text();
    var p_uuid = $(".pusdeviceInfoVO:eq(1)").text();
    var p_tokenid = $(".pusdeviceInfoVO:eq(2)").text();
        
    nowdate = new Date();
    date_str = nowdate.getFullYear() + "-" + (nowdate.getMonth()+1) + "-" + nowdate.getDate();
            
    var params = {
        uuid :  p_uuid , 
        message : p_message,
        osType : p_osType,
        sndDt :  date_str ,
		tokenId : p_tokenid};
      
    window.plugins.EgovInterface.request(url, params, function(jsondata) {
        //var data = JSON.parse(jsondata);
        //alert("jsondata : "+jsondata);
    	console.log("jsondata > "+jsondata);
    	
        if(jsondata.resultState == "OK"){
            //fn_goDeviceInfoListXml();
        	//alert("OK!");
        	console.log("send push ok");
        }else{
            $("#alert_dialog").click( function() {
                jAlert('데이터 전송 중 오류가 발생 했습니다.', '전송 오류', 'c');
                });
        }            
        
    }, function(result){
    	
    	console.log("error > "+result);
    });
    
    
    console.log("DeviceAPIGuide fn_egov_regist_deviceInfo request Completed");
    $("#message").val("내용을 입력하세요.");
    $.mobile.changePage("#main", "slide", false, false);
    detailScroll.refresh();
    
}
</code>

<code>
// 서버에서 반환한 디바이스 정보 및 메세지 리스트를 화면에 출력한다.
	function fn_egov_push_selectPushMessageList() {
		
	    var url = "/pus/PushMessageList.do";
	    var accept_type = "json";
	    var params = {uuid : device.uuid};
	    	    
	    // get the data from server
	    window.plugins.EgovInterface.request(url, params, function(jsonData) {
	        var list_html = "";
	        
	        //console.log(">>> resultData = "+jsonData);
	        
	        $(jsonData["PushMessageList"]).each(function(idx,obj){
	       	//console.log("\n\n\n\n\n#>>>>>obj = "+idx + "/" + obj);	
	        	
	        	var sn = obj.sn;
	        	var uuid = obj.uuid;
	        	var message = obj.message;
	        	var tokenId = obj.tokenId;
	        	var sndDt = obj.sndDt;
	        	    	
	        	 
	            list_html += "<li><h3>UUID : " +uuid + "</h3>";
	            list_html += "<p><strong>Token ID : " + tokenId + "</strong></p>";
	            list_html += "<p><strong>송신 날짜 : " + sndDt + "</strong></p>";
	            list_html += "<p>message : " + message + "</p></li>";
	        });

	        console.log("DeviceAPIGuide fn_egov_push_selectPushMessageList request Completed");
	                
	        var theList = $('#MessageList');
	        theList.html(list_html);
	        $.mobile.changePage("#PushMessageList", "slide", false, false);
	        theList.listview("refresh");
	        
	        detailScroll.refresh();
	        
	        
	    });    
	}	
</code>

=== 관련 화면 및 수행매뉴얼 ===

^Action^URL^Controller method^QueryID^
|디바이스 정보 목록 조회|/pus/pushDeviceInfoList.do|selectVibratorInfoList|"pushDeviceAPIDAO.selectPushDeviceList"|
|디바이스 정보 상세 조회|/dvc/deviceInfo.do|selectDeviceInfo|"deviceaddAPIDAO.selectDeviceInfo"|
|메세지 발송|/pus/requestPushInfo.do|insertVibratorInfo|"pushDeviceAPIDAO.insertVibratorInfo"|
|메세지 정보 목록 조회|/pus/PushMessageList.do|selectPushMessageList|"pushDeviceAPIDAO.selectPushMessageList"|

^Pushnotifications 메세지 발송 화면^Pushnotifications 메세지 송신 목록 화면^Pushnotifications 알림창 화면^Pushnotifications 알림 잠금 화면^
|{{:egovframework:hyb3.6:guide:mbl:pushnotifications:pushnotifications_3.jpeg?280|}}|{{:egovframework:hyb3.6:guide:mbl:pushnotifications:pushnotifications_4.png?280|}}|{{:egovframework:hyb3.6:guide:mbl:pushnotifications:pushnotifications_5.png?280|}}|{{:egovframework:hyb3.6:guide:mbl:pushnotifications:pushnotifications_6.png?280|}}|

 전송 : 메세지 전송\\
 목록 : 디바이스 정보 목록 페이지를 호출한다.\\
 메인화면이동 : 메인 페이지를 호출한다.

===== 컴파일 디버깅 배포 ===== 
==== 컴파일 ====

=== Pushnotifications Device Applicaton 컴파일 방법 === 

  * 프로젝트 선택 > 오른쪽 클릭 > Run As > Android Application

{{:egovframework:hyb:guide:add:카메라_컴파일1.png?740|}}

  * 상단의 메뉴 > Run As > Android Application

{{:egovframework:hyb:guide:add:카메라_컴파일2.png?740|}}

 
  * 실행할 타겟 선택 > 에뮬레이터, 디바이스(디버깅모드)

{{:egovframework:hyb:guide:add:디바이스컴파일.png?740|}}

  * 디바이스를 이용한 실행 화면

{{:egovframework:hyb3.6:guide:mbl:pushnotifications:push_run.png?320|}}

=== PushnotificationsAPI Server Applicaton 컴파일 방법 ===  


  * Pushnotifications API서버사이드 가이드 프로그램의 실행은 프로젝트를 마우스 오른쪽 버튼을 클릭 한후 Run As>Run On Server 버튼을 통해 실행 할 수 있다.

{{:egovframework:hyb:guide:ios:서버실행.png?640|}}

  * 빌드가 성공적으로 수행 되면 이클립스의 콘솔 창에서 'Server Startup in xxx ms' 메시지를 확인 할 수 있다.
{{:egovframework:hyb:guide:add:서버실행결과_콘솔.png?840|}}


==== 디버깅 ====

Pushnotifications 디바이스 어플리케이션에서 발생한 오류 내용 확인 및 디버깅을 위해서는 폰갭 프레임워크에서 제공하는 console.log를 이용할 수 있다. console.log 함수는 자바스크립트 구문에서 사용할 수 있는 디버그 코드로 이클립스 및 Xcode에서 확인 할 수 있다.
 

console.log의 작성 방법의 예시는 다음과 같다.
<code>
function fn_egov_network_check(doCheck)
{
    console.log('DeviceAPIGuide fn_egov_network_check');
    var networkState = navigator.network.connection.type;
    ...
}
</code>

 디버깅 코드가 실행 되면 아래와 같은 메시지를 개발도구의 콘솔 메시지 창에서 볼 수 있다.

 {{:egovframework:hyb:guide:add:FileReadWriteconsolelog.png?740|}}



Pushnotifications API 가이드 프로그램 에서는 디버깅을 위하여 다음과 같이 콘솔 정보를 출력한다.

==== 배포 ====
Pushnotifications API 가이드 다운로드 : [[http://www.egovframe.go.kr/cop/bbs/selectBoardArticle.do?bbsId=BBSMSTR_000000000161&nttId=1277&menu=3&submenu=9|Click]] \\


===== 참고자료 ===== 
  * Cordova 플러그인 정보 : cordova plugin add cordova-push-notifications[[https://www.npmjs.com/package/cordova-push-notifications|Click]] \\