[SKT Smart Zone Cast ] Android SDK 적용가이드 [2018. 01.16]
준비사항 1. [SKT Smart Zone Cast ] Agent 를통해컨탠츠를수신하기위해서는다음과같은 Android 개발환경이필요합니다. OS : Android 4.4(KitKat) 이상 API Level : 23 이상 Java version: JDK 1.7 이상 2. 광고신청과정산목적의회원정보가필요합니다. http://www.smartzonecast.com 에서회원가입후로그인 ID 를발급받으세요. 적용절차 위의준비사항을완료하신후아래순서에따라적용하세요. Android studio 2.1 버전을기준으로작성되었습니다 Jar 파일 등록 Manifest 설정 서비스 및 API 적용 시험 테스트 배포 준비 2
Step 1. jar 파일등록 (1) 1. 공식사이트 (http://www.smartzonecast.com) 에서왼쪽메뉴 개발지원센터 >SDK 다운로드 를클릭하여압축파일 (SKTSmartZoneCast SDK v3.0.x.zip) 을다운로드받습니다. 2. 다운로드받은압축파일의압축을풀어줍니다. Agent 파일 (jar) 개발가이드문서 Sample 코드및 Sample app 3. 프로젝트폴더의 lib 폴더에 CBSAgent_v2.0.x.jar 파일을복사합니다. 3
Step 2. Manifest Setting [Smart Zone Cast] SDK 를적용하기위해서는 AndroidManifest.xml 에 1 개의 Service 와 Receiver 를등록하고, 9 개의 Permission 을적용해야합니다. 1) AndroidManifest.xml 파일에 Service 와 Receiver 를등록합니다. <service android:name="kr.co.nitechs.lib.cbsjobservice android:permission= android.permission.bind_job_service /> <service android:name="kr.co.nitechs.lib.cbsservice"> </service> <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"/> </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"/> 4
Step 2. Manifest Setting 권한정보 [Smart Zone Cast] SDK 에서사용되는권한에대한용도는아래표와같습니다. 권한 android.permission.wake_lock idle 상태를해제하기위해사용합니다. android.permission.internet android.permission.access_network_state android.permission.access_coarse_location 용도 서버와의통신을위해사용합니다. - 수신받은메시지의 Cell ID가지정된 Cell ID와맞는지검사하기위해사용됩니다. - 등록된컨테츠를획득하기위해사용합니다. - Pilot정보를전달하기위해사용합니다. 네트워크상태체크를위해사용합니다. - 네트워크가사용가능한상태인지확인합니다. 네트워크기반위치확인를확인하기위해사용합니다. - TAC, Cell ID정보를가져오기위해사용합니다. android.permission.receive_sms CBS 메세지를수신위해사용합니다. android.permission.read_phone_state 디바이스상태를획득하기위해사용합니다. - OS 버전, 디바이스 ID 등 android.permission.read_external_storage 파일로그읽기, 환경설정파일읽기를위해사용합니다. android.permission.write_external_storage 파일로그쓰기, 환경설정파일쓰기를위해사용합니다. android.permission.bind_job_service JobService 를사용하기위해사용합니다. 5
Step 3. 서비스및 API 적용 리시버등록 1) Application을상속받은클래스에 Receiver를변수를등록합니다. 2) Alarm 수신을위해 Receiver를등록합니다. 3) AgentId 필요시요청하여사용한다. # 예시코드 //-------------------------------------------------------------------------------- 변수등록시작 private CBSLocalBroadcastReceiver receiver; // Agent 에서발생시킨이벤트를받기위한리시버 //-------------------------------------------------------------------------------- 변수등록끝 @Override 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()) { Log.d(TAG, " 필요한권한을모두획득하지못했습니다."); return; setoption(); initreceiver(); catch (Exception e) { Log.e(TAG, "Fail init receiver", e); //-------------------------------------------------------------------------------- 리시버등록끝 //** AgentId 필요시요청하여사용한다. String cbsagentid = CBSAPIs.requestAgentID(this); Log.d(TAG, "[RES_AGENT ID]=="+ cbsagentid); 6
Step 3. 서비스및 API 적용 리시버등록 1) CBS 메시지를수신받기위한 Receiver 를등록합니다. 2) 초기에옵션을설정이필요한경우 setoption 과같이적용할옵션을설정하는코드를작성합니다. # 예시코드 private void initreceiver() throws Exception { if (receiver == null) { Context context = getapplicationcontext(); // 알람이 LocalBroadcast 로전달되므로 LocalBroadcast 를받을수있도록개발필요 receiver = new CBSLocalBroadcastReceiver(); IntentFilter filter = new IntentFilter(); // 메세지수신알람등록 filter.addaction(appalarm.action_on_receive_msg); // 메세지삭제알람등록 filter.addaction(appalarm.action_on_remove_msg); LocalBroadcastManager.getInstance(context).registerReceiver(receiver, filter); Log.d(TAG, "Start receiver"); 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 를사용으로할경우반드시지정해야한다. 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 를사용할경우사용한다. // SKT 에서만사용이가능하다. // ex> 남자, 10 대의경우아래와같이설정한다. option.setreceivetarget(sex.man, Age.AGE10); CBSAPIs.setOption(getApplicationContext(), option); Log.d(TAG, "Set option :" + option.tostring()); 7
Step 3. 서비스및 API 적용 메시지수신처리 1) 아래예시와같이리시버클래스를생성하고 Intent 에서 Message 라는키를가지는값을가져와서사용할수있도록코드를작성합니다. # 리시버클래스예시 public class CBSLocalBroadcastReceiver extends BroadcastReceiver{ private final String TAG = CBSLocalBroadcastReceiver.class.toString(); private Context context; public CBSLocalBroadcastReceiver(Context context) { this.context = context; @Override 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; /** * 캠페인메세지수신시처리로직을구현합니다. * * @param intent */ private void onreceivecbsmessage(context context, Intent intent) { //... 생략 /** * 메세지가삭제되었을경우처리로직을구현합니다. * * @param intent */ private void onremovecbsmessage(intent intent) { //... 생략 8
Step 3. API 설명 CBS Agent 에서사용되는 API 는아래와같습니다. 클래스명 설명 CBSAPIs CBS Agent 에서제공하는 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 을요청한다. getid String Context context Context 저장된 ID 를가져온다 setid void Context context String key Context UserID 서드파티앱 UserID 를저장 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) : 셋팅하지않으면 smallicon 만노출. uselog Boolean Log 사용여부 개발이나테스트시만사용하기를권장합니다. 9
Step 3. 서비스및 API 적용 메시지형식 OnReceive 에서수신되는메시지의형태는 JSON 형태의메시지입니다. 내용은아래표와같습니다. Key Message 키값내용비고캠페인키 캠페인메시지 imgurl 노티이미지 URL 이미지푸쉬일경우 # CBS 메시지수신로그예시 {"Message":" 지금클릭하면선물이팡팡 ","Key":"2M0JLL8X9h, imgurl : http://temp.image.jpg 메시지수신후필요에따라서버로 Content 요청을사용하게됩니다. Content 요청시사용하는 API 는 requestcontent 입니다. 파라미터로 onreceive 에서받은 message 에포함된키 ( 캠페인키 ) 를넣어주면됩니다. 요청에따른결과값은 JSON 형태의문자열반환되며, ErrCode 가 SUCCESS 일경우요청성공이며다른경우는예외가발생한경우입니다. requestcontent 로수신되는메시지의형태는 JSON 형태의메시지입니다. 내용은아래표와같습니다. Key ErrCode Content 키값내용비고캠페인키 캠페인메시지 캠페인에사용하기위한컨텐츠 오류코드내용은아래 콘텐츠요청시오류코드정의 표를참고 오류발생시빈문자열 ( ) 이반환 # 요청시로그예시 07-12 11:09:57.191 19578-19578/kr.co.nitechs.cbssample I/[CBS_AGENT]: [REQ_GW] http://21 1.188.xxx.xxx/mobileGW/chkAdUrl.dochkAdUrl.do : {"campkey":"1b0ksnobxs","appid":"kr.co.ni techs.cbssample","appversion":"2.0.0","osversion":"6.0.1","cellid":"5143863","displaydate":"16.0 7.12 11:09","model":"SM-G930S" # 요청에대한응답로그예시 07-12 11:09:57.271 19578-19578/kr.co.nitechs.cbssample I/[CBS_AGENT]: [RES_GW] {"adurl":"h ttp://google.co.kr","imgurl":"","interval":"","message":"","repushcampkey":"","returncode":"suc CESS","returnMsg":" 성공 ","title":"","todate":"" # requestcontent 에서리턴되는값로그예시 07-12 11:09:57.271 19578-19578/kr.co.nitechs.cbssample D/class kr.co.nitechs.mainactivity: [R ES_CONTENT]{"Key":"1B0KSnOBxs","Content":"http:\/\/google.co.kr","ErrCode":"SUCCE SS" 10
Step 3. 서비스및 API 적용 오류코드 콘텐츠요청시오류코드정의 Code 메세지 비고 SUCCESS 성공 UNDEFINED_OPERATION 정의되지않은요청 INVALID_CP 유효하지않은 CP UNAUTHORIZED_CP 승인되지않은 CP INVALID_MSG 유효하지않은메시지 ( 파싱에러 ) DB_OPERATION_ERR 데이터베이스처리오류 INVALID_CELL_ID 승인되지않은 Cell ID UNKNOWN 알수없는오류 UNAUTHORIZED_CAMPAIGN 유효시간이지난캠페인 11
Step 4. 테스트수행 Agent 를적용한애플리케이션을테스트하기위해서는 [Smart Zone Cast] (http:// smartzonecast.co.kr) 에서캠페인메시지를해당애플리케이션으로발송해야합니다. 1. SKT담당자로부터 [Smart Zone Cast] 테스트 ID 발급받습니다. 2. 발급받은아이디로 [Smart Zone Cast] 사이트에로그인을합니다. 12
Step 4. 테스트수행 3. [Smart Zone Cast] 웹사이트에서개발지원센터 > 상용화 > 테스트발송메뉴를통해테스트발송화면으로이동합니다. 4. 캠페인정보및광고정보를입력후캠페인을등록합니다. 13
Step 4. 테스트수행 5. 등록한정보를확인한후확인버튼을클릭합니다. ( 캠페인시작시간에메시지가발송처리됩니다.) 14
Step 4. 테스트수행 6. 발송진행현황은 [ 테스트발송현황 ] 메뉴에서확인가능합니다. 15
Step 4. 테스트수행 7. 캠페인시작시간이되면메시지가수신됩니다. 아래는정상적으로메시지를수신받았을경우예시로그입니다. 아래와비슷한형태의로그가수신되면정상입니다. # 메시지수신시로그예시 메시지수신시 Cell ID 를체크합니다. 발송지역과셀아이디가일치해야정상메시지로처리합니다. 07-14 16:19:56.955 D/[CBS_AGENT]: [SET_CBS_ALARM] key=1c0ktw1dab, type=cbsevent.waitnot i, reqcod26114-30182/kr.co.nitechs.bssample I/[CBS_AGENT]: [REQ_GW] http://211.188.236.204/m obilegw/chkcellid.do : {"campkey":"1c0ktw1dab","cellid":"5143863","appid":"kr.co.nitechs.cbssam ple","osversion":"6.0.1","model":"sm-g930s 07-14 16:19:57.225 26114-30182/kr.co.nitechs.bssample I/[CBS_AGENT]: [RES_GW] {"imgurl":"","ret urncode":"success","returnmsg":" 성공 " 07-14 16:19:57.235 26114-30182/kr.co.nitechs.cbssample D/[CBS_AGENT]: [ADD MESSAGE] KEY=1 C0KTW1daB, DUE=1468486740000, CURRENT=1468480797248, CLOCK=21717981 07-14 16:19:57.245 26114-30182/kr.co.nitechs.cbssample D/[CBS_AGENT]: [SET_CBS_ALARM] key=1 C0KTW1daB, type=cbsevent.removemsg, reqcode=324567591, trigger time=5942750(ms) 07-14 16:19:57.255 26114-30182/kr.co.nitechs.cbssample e=1583067607, trigger time=1(ms) 07-14 16:19:57.255 26114-30182/kr.co.nitechs.cbssample D/[CBS_AGENT]: --------------------------- ---[ Process end : Campaign message process ] 07-14 16:19:58.425 26114-30379/kr.co.nitechs.cbssample D/[CBS_AGENT]: onhandleintent... 07-14 16:19:58.425 26114-30379/kr.co.nitechs.cbssample D/[CBS_AGENT]: onreceive : ACTION.EVE NT.CBSService 메시지 07-14 처리 16:19:58.425 후알람이26114-30379/kr.co.nitechs.cbssample 등록됩니다. D/[CBS_AGENT]: [ Process start : wait not APP i ]------------------------------------------------ 에서이알람을받아사용합니다. 07-14 16:19:58.465 26114-30379/kr.co.nitechs.cbssample D/[CBS_AGENT]: [Show agent noti] key:1 C0KTW1daB, type:cbs, intent:intent { cmp=kr.co.nitechs.cbssample/.mainactivity VirtualScreenPara m=params{mdisplayid=-1, null, mflags=0x00000000) (has extras) 07-14 16:19:58.475 26114-30379/kr.co.nitechs.cbssample D/[CBS_AGENT]: Default Text Noti..No Im age 07-14 16:19:58.495 26114-30379/kr.co.nitechs.cbssample D/[CBS_AGENT]: [SET_LOCALBROADCAST ] Type=OnReceive, Message={"Key":"1C0KTW1daB","Message":"CBS 캠페인일반 " 07-14 16:19:58.495 26114-30379/kr.co.nitechs.cbssample D/[CBS_AGENT]: --------------------------- ---------------------[ Process end : wait noti ] 07-14 16:19:58.515 26114-26114/kr.co.nitechs.cbssample D/class kr.co.nitechs.cbssample.cbslocal BroadcastReceiver: [ON_RECEIVE] onreceivecbsmessage 07-14 16:19:58.525 26114-26114/kr.co.nitechs.cbssample D/class kr.co.nitechs.cbssample.cbslocal BroadcastReceiver: [ON_RECEIVE] {"Key":"1C0KTW1daB","Message":"CBS 캠페인일반 " 16
Step 4. 테스트수행 8. 캠페인컨텐츠요청시예시로그입니다. 정상적으로요청과응답이진행되었을경우아래와비슷한형태의로그가수신됩니다. 캠페인등록시입력한 Url 정보가컨텐츠정보로응답됩니다. # 컨텐츠요청시로그예시 컨텐츠요청시통계목적의데이터가서버로전송됩니다. 07-14 16:28:34.415 26114-26114/kr.co.nitechs.cbssample I/[CBS_AGENT]: [REQ_GW] http://211.188. 236.204/mobileGW/chkAdUrl.do : {"campkey":"1c0ktw1dab","appid":"kr.co.nitechs.cbssample","ap pversion":"2.0.0","osversion":"6.0.1","cellid":"5143863","displaydate":"16.07.14 16:28","model":"SM- G930S" 07-14 16:28:34.415 26114-26114/kr.co.nitechs.cbssample I/System.out: (HTTPLog)-Static: issbsettin genabled false 07-14 16:28:34.415 26114-26114/kr.co.nitechs.cbssample I/System.out: (HTTPLog)-Static: issbsettin genabled false 07-14 16:28:34.705 26114-26114/kr.co.nitechs.cbssample I/[CBS_AGENT]: [RES_GW] {"adurl":"http:/ /m.naver.com","imgurl":"","interval":"","message":"","repushcampkey":"","returncode":"success","r eturnmsg":" 성공 ","title":"","todate":"" 07-14 16:28:34.705 26114-26114/kr.co.nitechs.cbssample D/class kr.co.nitechs.cbssample.mainactiv ity: [RES_CONTENT]{"Key":"1C0KTW1daB","Content":"http:\/\/m.naver.com","ErrCode":"SUCCESS " 07-14 16:28:34.705 26114-26114/kr.co.nitechs.cbssample D/class kr.co.nitechs.cbssample.mainactiv ity: 요청성공 : http://m.naver.com 캠페인등록화면에서 광고 URL 에입력한값입니다. 17
Step 4. 테스트 수행 9. Agent의 Option중 usenotificationbar를 true로 설정하였을 경우 아래 이미지와 같이 Push 메세지가 노출 됩니다. 만약 Agent에서 제공 되는 Notificationbar를 사용 할 경우 Agent에서 캠페인메세지를 Push합니다. App아이콘과, App명이 노출됩니다. 캠페인 등록 메뉴에서 등록 한 광고 메시지가 표시됩니다. 캠페인 등록 메뉴에서 등록 한 이미지URL의 이미지가 표시됩니다.
Step 5. 배포준비 Test 수행에문제가없었다면배포준비를합니다. jar 파일을적용후배포합니다. 라이브러리파일 설명 CBSAgent_v3.0.1.jar - CBS Agent 라이브러리파일 19
문의 문의 적용에문제가발생할경우아래문의처로문의해주세요 l Email : smartzonecast@nitechs.co.kr l 운영시간 : 평일오전 10 시 ~ 18 시 20