SMART ZONE CAST ANDROID SDK 적용가이드 NIT

Transcription

1 SMART ZONE CAST ANDROID SDK 적용가이드 NIT

2 I. 준비 1. Smart Zone Cast Agent( 이하 CBSAgent) 를통해메시지를수신하기위해서는다음과같은 Android 개발환경이필요합니다. OS: Android 4.4(KitKat) 이상 Target SDK Level: 26 이상 Compile SDK Level: 26이상 Java version: JDK 1.7이상 2. 메시지발송을위한회원정보가필요합니다. 개발과정에서의테스트는 을통해관리자에게문의하시기바랍니다. 3. 이상의준비가완료되었다면다음의단계별안내에따라진행해주십시오. 이문서는 Android studio 버전을기준으로작성되었습니다. 이중 Step 4. 까지는 CBSAgent를탑재하기위한기본적인내용이며, Step 5. 는선택적으로적용할수있는내용입니다. 1 페이지

3 II. 단계별가이드 STEP 1. jar 파일등록 1. 공식사이트 ( 에서 CBSAgent SDK 를다운로드받습니다. 2. 다운로드받은파일의압축을풀어 CBSAgent_vX.X.X.jar 를확인합니다. 3. 프로젝트폴더의 libs 폴더에 CBSAgent_vX.X.X.jar 를복사합니다. 2 페이지

4 STEP 2. Manifest 작성 Smart Zone Cast SDK 를적용하기위해서는 AndroidManifest.xml 에 2 개의 Service 와 Receiver 를등록하고, 10 개의 Permission 을적용해야합니다. 1. AndroidManifest.xml 파일에 Service 와 Receiver 를등록합니다. <service android:name="kr.co.nitechs.lib.cbsjobservice android:permission= android.permission.bind_job_service android:enabled="true" /> <service android:name="kr.co.nitechs.lib.cbsservice /> <receiver android:name="kr.co.nitechs.lib.cbsreceiver" android:enabled="true" > <intent-filter> <action android:name="android.provider.telephony.sms_cb_received"/> <action android:name="android.intent.action.boot_completed" /> <action android:name="kr.co.nitechs.lib.action_on_remove_msg"/> <action android:name="kr.co.nitechs.lib.lib.action_on_receive_msg"/> <action android:name= kr.co.nitechs.lib.cb /> <category android:name= android.intent.category.default /> </intent-filter> </receiver> 2. AndroidManifest.xml 파일에 Agent 사용하기위한권한을추가합니다. <uses-permission android:name="android.permission.wake_lock" /> <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.access_network_state" /> <uses-permission android:name="android.permission.access_coarse_location" /> <uses-permission android:name="android.permission.receive_sms" /> <uses-permission android:name="android.permission.receive_boot_completed" /> <uses-permission android:name="android.permission.write_external_storage"/> <uses-permission android:name="android.permission.read_phone_state" /> <uses-permission android:name="android.permission.read_external_storage"/> <uses-permission android:name="android.permission.bind_job_service"/> 3 페이지

5 Smart Zone Cast SDK 에서사용되는권한에대한용도는아래표와같습니다. 권한용도 WAKE_LOCK idle 상태를해제하기위해사용합니다. INTERNET 서버와의통신을위해사용합니다. - 수신된메시지의 Cell ID 가지정된 Cell ID 와맞는지검사하기위해사용됩니다. - 광고등의사용자컨텐츠를획득하기위해사용합니다. - Pilot 정보를전달하기위해사용합니다. ACCESS_NETWORK_STATE 네트워크상태체크를위해사용합니다. - 네트워크가사용가능한상태인지확인합니다. ACCESS_COARSE_LOCATION 네트워크기반위치확인를확인하기위해사용합니다. - TAC, Cell ID 정보를가져오기위해사용합니다. RECEIVE_SMS CBS 메세지를수신위해사용합니다. READ_PHONE_STATE 디바이스상태를획득하기위해사용합니다. - OS 버전, 디바이스 ID 등 READ_EXTERNAL_STORAGE 파일로그읽기, 환경설정파일읽기를위해사용합니다. WRITE_EXTERNAL_STORAGE 파일로그쓰기, 환경설정파일쓰기를위해사용합니다. BIND_HOB_SERVICE JobService 를사용하기위해사용합니다. 4 페이지

6 STEP 3. 서비스및 API 적용 : 리시버등록 CBSAgent 라이브러리는 Smart Zone Cast 에서발송되는메시지를수신하였을때, 기본적으로광고 URL 을포함하여자동으로 Notification Bar( 이미지배너포함 ) 를생성하여노출하는기능을제공하고있습니다. ( 아래예시는 Application 을상속받은클래스에서 setoption Method 를호출하고있습니다. setoption Method 는최초한번설정하신이후다른변경사항이없을경우더이상호출하지않으셔도됩니다.) # 예시코드 1 // 변수등록시작 private CBSLocalBroadcastReceiver receiver; // Agent 에서발생시킨이벤트를받기위한리시버 // protected void oncreate() { super.oncreate(); app = this; // 리시버등록시작 Log.d(TAG, "On create sample app"); try { // 마시멜로우이상버전에서는퍼미션을모두획득했는지체크후 // 모든권한이있을경우에만에이전트를실행해주어야합니다. if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) { if (!checkallpermission()) { setoption(); initreceiver(); catch (Exception e) { Log.e(TAG, "Fail init receiver", e); Log.d(TAG, " 필요한권한을모두획득하지못했습니다."); return; // 리시버등록끝 //** AgentId 필요시요청하여사용합니다. String cbsagentid = CBSAPIs.requestAgentID(this); Log.d(TAG, "[RES_AGENT ID]=="+ cbsagentid); 5 페이지

7 이옵션들은다음 setoption Method 처럼같이사용될수있습니다. # 예시코드 2 private void setoption() throws Exception { Context context = getapplicationcontext(); // 옵션을설정합니다. Option option = CBSAPIs.getOption(context); Log.d(TAG, "[Get option] " + option.tostring()); // 로그사용여부를설정합니다. // 상용배포시에는 false 로설정해야합니다. option.setuselog(true); // NotificationBar 를사용할클래스를지정한다. // NotificationBar 를사용할경우반드시지정해야합니다. option.setnoticlass(mainactivity.class.getname()); //Push 아이콘설정 : 아이콘을설정하지않으면기본앱아이콘으로노출됩니다. option.setpushsmallicon(context.getresources().getresourcename(r.drawable.icon)); option.setpushlargeicon(context.getresources().getresourcename(r.drawable.icon_large)); // Target Push 를사용할경우사용합니다. // ex> 남자, 10 대의경우아래와같이설정합니다. option.setreceivetarget(sex.man, Age.AGE10); CBSAPIs.setOption(getApplicationContext(), option); Log.d(TAG, "Set option :" + option.tostring()); 6 페이지

8 STEP 4. 서비스및 API 적용 : 광고 URL 처리 CBSAgent 에서자동으로생성된 Notification Bar 를클릭했을때, 호출되는 Activity 에 requestcontent 를 넣어주시면됩니다. // 캠페인메시지랜딩 URL 요청예제, 토큰아이디를받는부분은무시하십시오. 사용하지않는기능입니다.. Intent intent = getintent(); campaignkey = intent.getstringextra(appalarm.key_key); String getpush = intent.getstringextra("getpush"); String tokenid = ""; if ((campaignkey!= null &&!campaignkey.isempty()) && getpush == null) { 7 페이지 // 컨텐츠요청시캠페인키값을전달해야합니다. // 서버에서키값으로등록된캠페인여부를확인합니다. // 컨텐츠요청결과도 JSON 형태의 String 으로전달됩니다. // getpush 는 null 로고정되어있습니다. String rescontent; try { if (!TextUtils.isEmpty(FirebaseInstanceId.getInstance().getToken())) { tokenid = FirebaseInstanceId.getInstance().getToken(); Log.d(TAG, "[REQ_CONTENT]" + campaignkey + ", " + tokenid); // tokenid 관련부분과 FirebaseInstanceId 부분은코드를삭제해주시기바랍니다. 사용하지않는기능입니다. 인자값 2 개로직만고정적으로사용해주시길바랍니다 if (!TextUtils.isEmpty(tokenID)) { rescontent = CBSAPIs.requestContent(this, campaignkey, tokenid); Log.d(TAG, "tokenid requestcontent"); else { rescontent = CBSAPIs.requestContent(this, campaignkey); Log.d(TAG, "[RES_CONTENT]" + rescontent); if (!TextUtils.isEmpty(resContent)) { Uri.parse(content)); // 에러코드가 [SUCCESS] 일경우성공이며그이외의경우는실패한경우입니다. JSONObject jsonresponsecontent = new JSONObject(resContent); if ("SUCCESS".equals(jsonResponseContent.getString("ErrCode"))) { // 컨텐츠는 [Content] 키값을가집니다. String content = jsonresponsecontent.getstring("content"); showmessage(" 요청성공 : " + content); showmessage("uri.parse(content) : " + Uri.parse(content)); Intent landingintent = new Intent(Intent.ACTION_VIEW, startactivity(landingintent); else { // 요청이실패할경우에러코드가전달됩니다. showmessage(" 요청실패 : " + jsonresponsecontent.getstring("errcode")); 원한다면 finish() 를사용합니다 //finish(); catch (Exception e) { Log.w(TAG, e); else { Log.d(TAG, "campaignkey is null"); STEP 4 까지적용되면기본적인동작이가능합니다. // 랜딩페이지를가져오지못했을경우해당 Activity 를종료시키길

9 STEP 5. Customizing: API 를이용한리시버등록 CBSAgent 가기본적으로제공하는 Notification Bar 를사용하지않고어플리케이션내에서직접 Notification 기능을제어하고자할경우, 다음과같이 CBSAgent 에서 Local Broadcasting 을이용하여 App 으로전달해주는 메시지를이용할수있습니다. 1. Application 을상속받은클래스에 Receiver 를변수로등록합니다. 2. Alarm 수신을위해 Receiver 를등록합니다. 3. AgentId 가필요할경우요청하여사용합니다. # 예시코드 1 // 변수등록시작 private CBSLocalBroadcastReceiver receiver; // Agent 에서발생시킨이벤트를받기위한리시버 // protected void oncreate() { super.oncreate(); app = this; // 리시버등록시작 Log.d(TAG, "On create sample app"); try { // 마시멜로우이상버전에서는퍼미션을모두획득했는지체크후 // 모든권한이있을경우에만에이전트를실행해주어야합니다. if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) { if (!checkallpermission()) { setoption(); initreceiver(); catch (Exception e) { Log.e(TAG, "Fail init receiver", e); Log.d(TAG, " 필요한권한을모두획득하지못했습니다."); return; // 리시버등록끝 //** AgentId 필요시요청하여사용합니다. String cbsagentid = CBSAPIs.requestAgentID(this); Log.d(TAG, "[RES_AGENT ID]=="+ cbsagentid); 4. 아래예시와같이리시버클래스를생성하고 Intent 에서 Message 라는키를가지는값을가져와서사용할수 있도록코드를작성합니다. 8 페이지

10 # 예시코드 2 # 리시버클래스예시 public class CBSLocalBroadcastReceiver extends BroadcastReceiver{ private final String TAG = CBSLocalBroadcastReceiver.class.toString(); private Context context; public CBSLocalBroadcastReceiver(Context context) { this.context = context; /** /** * Agent 에서수신한 CBS 메시지가 APP 으로전달됩니다. * message 는 JSON 형태의 String 값으로되어있습니다. * ex: { Key : a100ewa, Message : CBS 테스트 intent public void onreceive(context context, Intent intent) { String action = intent.getaction(); switch (action) { // 캠페인메세지가수신되었을경우에대한처리로직을정의합니다. case APPAlarm.ACTION_ON_RECEIVE_MSG: onreceivecbsmessage(context, intent); break; // 메시지유효기간이만료되어메시지가삭제되었을경우처리를정의합니다. case APPAlarm.ACTION_ON_REMOVE_MSG: onremovecbsmessage(intent); break; * 캠페인메시지수신시처리를구현합니다. * intent */ private void onreceivecbsmessage(context context, Intent intent) { /** // 이하생략 // 이어지는내부코드는생략되어있습니다 * 메시지가삭제되었을경우처리를구현합니다. * intent */ private void onremovecbsmessage(intent intent) { 9 페이지

11 III. API 및옵션가이드 1. CBSAgent 가제공하는 API 는다음과같습니다. 클래스 설명 CBSAPIs CBSAgent 에서제공하는 API 함수명 반환형 형식 파라미터 설명 설명 requestagentid String Context context Context Agent Id 를반환한다. setoption void Context context Option option Context 옵션 옵션을설정한다. getoption Option Context context Context 설정된옵션을가져온다.. requestcontent String Context context String key Context 캠페인키 광고 URL 을요청한다. requestcontent String Context context String key String tokenid Context 캠페인키 FCM 토큰 ID 광고 URL 을요청하고토큰 ID 를게이트웨이에보내준다. retargetcontent String Context context String key Context 캠페인키 이기능은사용하지않는기능입니다. 10 페이지

12 2. CBS Agent 에서사용되는옵션은아래와같습니다. 클래스명 설명 Option CBS Agent 에서사용되는옵션정보 속성형식설명 usecampaign boolean 캠페인사용여부 usenotificationbar boolean Notification bar 사용여부 True 로설정할경우반드시 noticlass 를설정해주어야한다. ban Ban 방해금지사용여부 usesound Boolean NotificationBar 를표시할때사운드사용여부 usevibrate Boolean NotificationBar 를표시할때진동사용여부 noticlass String NotificationBar 를사용할클래스 usenotificationbar 가 true 일경우반드시설정해주어야한다. pushsmallicon String 푸시아이콘 (SmallIcon) : 설정하지않으면기본앱아이콘노출. pushlargeicon String 푸시아이콘 (LargeIcon) : 설정하지않으면 Small icon 만노출. uselog Boolean Log 사용여부 개발이나테스트시만사용하고, 상용배포시에는반드시 false 로설정 11 페이지

13 IV. 메시지정보 onreceive() Intent 정보 BroadcastReceiver 의 OnReceive 에서수신되는메시지의형태는 JSON 형태의메시지입니다. 내용은아래표와 같습니다. 키값내용비고 Key Message 캠페인키 캠페인메시지 imgurl 노티이미지 URL 이미지푸시일경우 # CBS 메시지수신로그예시 {"Message":" 지금클릭하면선물이팡팡 ","Key":"2M0JLL8X9h, imgurl : 캠페인컨텐츠정보 메시지수신후서버로 Content 요청을사용하게됩니다. Content 요청시사용하는 API 는 requestcontent() 입니다. 파라미터로 onreceive 에서받은 message 에포함된키 ( 캠페인키 ) 를넣어주면됩니다. 요청에따른 결과값은 JSON 형태의문자열로반환됩니다. 반환되는경우는예외가발생한경우입니다. ErrCode 가 SUCCESS 일경우요청성공이며다른문자열이 requestcontent 로수신되는메시지의형태는 JSON 형태의메시지입니다. 내용은아래표와같습니다. 키값내용비고 Key ErrCode 캠페인키 캠페인메시지 오류코드내용은아래 컨텐츠요청시 오류코드정의 표를참고 Content 캠페인에사용하기위한컨텐츠오류발생시빈문자열 ( ) 이반환 # 요청로그예시 :09: /kr.co.nitechs.cbssample I/[CBS_AGENT]: [REQ_GW] : {"campkey":"1b0ksnobxs","appid":"kr.co.nitechs.cbssample","appversion":"2.0.0","osversion":"6. 0.1","cellId":" ","displayDate":" :09","model":"SM-G930S" # 요청에대한응답로그예시 :09: /kr.co.nitechs.cbssample I/[CBS_AGENT]: [RES_GW] {"adurl":" rncode":"success","returnmsg":" 성공 ","title":"","todate":"" # requestcontent 에서반환되는값로그예시 :09: /kr.co.nitechs.cbssample D/class kr.co.nitechs.mainactivity: [RES_CONTENT]{"Key":"1B0KSnOBxs","Content":" 12 페이지

14 V. 오류코드 Code 메시지 비고 SUCCESS 성공 UNDEFINED_OPERATION 정의되지않은요청 INVALID_CP 유효하지않은 CP UNAUTHORIZED_CP 승인되지않은 CP INVALID_MSG 유효하지않은메시지 ( 파싱에러 ) DB_OPERATION_ERR 데이터베이스처리오류 INVALID_CELL_ID 승인되지않은 Cell ID UNKNOWN 알수없는오류 UNAUTHORIZED_CAMPAIGN 유효시간이지난캠페인 13 페이지

15 VI. Debug Log 예시 1. 메시지수신로그 14 페이지

16 2. 컨텐츠요청및응답로그 15 페이지

17 VII. Q/A 개발과정에서모든옵션이정상적으로설정되었음에도불구하고메시지가수신되지않을경우다음과같은부분을점검하시기바랍니다. - 테스트단말이발신하는이동통신사의 usim 으로정상개통되어있는가 - 단말이현재 4G/LTE 상태로연결되어있는가 - 필요한권한의획득은정상적으로처리되었는가 - 대상단말의 위치 는사용가능한상태로설정되어있는가 - 재난문자수신설정은정상적으로수신설정되어있는가 - 적용될 App 에서 notification 제어와관련하여이상이없는가 기술지원및문의 : smartzonecast@nitechs.co.kr 16 페이지