Android Agent
Android
이 문서는 Android OS (AOS) 환경에서의 Surffy NetFUNNEL Agent 적용 및 연동 가이드를 제공합니다.
설치
NetFUNNEL 서비스가 필요한 부분에 코드를 추가합니다.
이 가이드에서 권장하는 코드를 사용자 코드의 통신 부분에 적용하면 URL의 외부 입력을 통해 Surffy 서비스를 이용할 수 있습니다.
Kotlin
Java
Netfunnel
전체적인 흐름을 관리하는 클래스입니다.
singleton으로 되어 있어 최초 정보 입력 이후 변경 사항이 있는 정보들만 다시 setter로 설정하면 재반영됩니다.
속성
사용자가 입력해야 하는 속성은 다음과 같습니다.
- AppName: 고객사 앱 이름(식별용)
- Activity: NetFUNNEL을 적용하고자 하는 현재 Activity
- Context: 기기 내부 정보를 가져오기 위한 Context (Null일 경우, Activity의 Context를 가져옵니다.)
- TenantAPIURL: 테넌트 API 서버 주소
- TenantNFURL: 테넌트 NetFUNNEL 서버 주소
- eumURL: End User Monitoring 서버 주소
- SettingURL: NetFUNNEL 설정 서버 주소
TenantAPIURL, TenantNFURL 속성은 콘솔의 AOS 설치 가이드의 데이터를 입력하면 됩니다.
nfStart()
모든 입력 속성과 AgentInterface가 등록된 후 nfStart()함수를 호출하면 NetFUNNEL (대기열 체크)가 시작됩니다.
NetFUNNEL 동작 후 행동에 대해 AgentInterface의 onSuccess 함수에 기록하면 됩니다.
AgentInterface
사용자가 사용하기 위한 기능을 정의하는 인터페이스입니다.
AgentInterface에서는 다음과 같은 함수들을 Override하여 기능을 정의합니다. 정의하지 않으면 아무 행동도 하지 않습니다.
함수 목록
- public void onSuccess() *필수
- NetFUNNEL 동작 이후 동작에 대해 정의합니다. 이 부분에 실제 정상 동작하는 코드를 넣습니다.
- public void onCancel()
- NetFUNNEL 동작 중 취소 등의 액션이 발생한 상황을 대비하기 위해 정의합니다.
Netfunnel 클래스의 nfStart()을 수행하는 다음 라인부터는 동작에 영향을 줄만한 코드는 삽입하지 않는 것을 권장합니다.
모든 메서드는 콜백으로 동작하기 때문에 AgentInterface에서의 함수들에 대해 Activity 등의 문제를 일으킬 수 있는 기능은 사용하지 않는 것을 권장합니다.
WebView
Surffy-NetFUNNEL-Agent에서는 대기창을 WebView로 띄운 후 WebView 내 클라이언트가 서버와 통신하는 구조로 되어 있습니다.
EUM
NetFUNNEL이 성공적으로 동작하면 사용자의 EUM 정보가 수집되기 시작하고, NetFUNNEL 종료 시 수집을 종료하고 수집된 정보를 서버로 전송합니다.
요구 사양
최소 요구 사양은 다음과 같습니다.
- JAVA: JDK 1.8 이상
- Android: Android Agent 23 (Marshmallow) 이상
기능
- VWR (Virtual Waiting Room) 기능
- EUM 기능
부록
비정상 행위 방어
인터넷 미연결
인터넷 미연결에 대해 cancel로 통하는 방어 로직이 추가되었습니다.
비행기 모드
간혹 비행기 모드를 통해 우회 접속(비인가 접속)을 시도하는 경우가 있습니다. 이에 대한 방어는 다음과 같습니다.
- 비행기 모드가 켜진 경우 통신을 중단하고 AgentInterface의 onCancel로 진행시켜 주요 흐름을 방어합니다.
뒤로 가기(취소)
뒤로 가기 버튼이나 취소 버튼 등을 통해 우회 접속(비인가 접속)을 시도하는 경우가 있습니다. 이에 대한 방어는 다음과 같습니다.
- webview에서 취소 버튼이 입력된 경우 통신을 중단하고 AgentInterface의 onCancel로 진행시켜 주요 흐름을 방어합니다.
- 뒤로 가기 버튼(back button)이 입력된 경우 onBackPressed 리스너를 이용해 onCancel로 진행시켜 주요 흐름을 방어합니다.
빠른 반복 입력
NetFUNNEL이 동작하는 이벤트(onClick 등)는 사용자의 영역이고, 구현되어 있는 로직에 따라 빠르게 반복적으로 입력(터치) 할 경우 넷퍼넬을 반복하여 호출할 수 있습니다. 이에 대한 방어는 다음과 같습니다.
- nfStart() 함수 호출 시, 동일한 service URL 요청에 대한 1초의 반복 체크를 진행합니다.
라이브러리 추가
첨부 파일에 있는 aar파일을 다운로드한 후 app 단위 gradle에 추가합니다.
e.g. libs 디렉토리 아래에 aar 파일을 업로드한 경우
implementation files('libs/surffy-agent_x.x.x.aar')
상태 코드
코드 | 설명 | 비고 |
200(SUCCESS) | 성공 시 발생하는 코드 |
|
201(CONTINUE) | 대기 시 발생하는 코드 |
|
300(BYPASS) | 서버 내 200코드에 관계 없이 보내줌 |
|
301(SERVERSIDE_BLOCK) | 서버에서 BLOCK당함 |
|
302(SERVERSIDE_IP_BLOCK) | 서버에서 해당 IP가 BLOCK당함 |
|
303(EXPRESS_NUMBER) | 대기열에 상관 없이 바로 성공으로 간주 |
|
499(USER_CANCEL) | 사용자가 취소했을 경우 | 넷퍼넬 웹뷰 UI 취소 버튼 |
500 | 서비스가 없음 | 에러 코드 |
502(KEY_DONE) | 이미 key가 만료됨 | 에러 코드 |
505(KEY_NOT_EXISTS) | 존재하지 않는 key | 에러 코드 |
507(INVALID_KEY) | 잘못된 key 사용 | 에러 코드 |
513(LICENSE_OVER) | 라이센스 만료 | |
905(ERROR_DATA) | 데이터 오류 | |
908(ERROR_SERVICE) | 넷퍼넬 서버 동작 불가 | |
999(ERROR_SYSTEM) | 넷퍼넬 서버 동작 불가 | |
라이브러리 사용 예제
Connection 통신 예제
🏄♂️ 기술 문서에 질문이나 피드백이 있으신가요? support@stclab.com로 문의주시면 답변드리겠습니다.