버전: 4.6.1-saas

Android 에이전트

개요

NetFUNNEL Android 에이전트는 모바일 어플리케이션에서 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다. 사용자는 적용하고자 하는 클라이언트 어플리케이션 코드에 에이전트에서 제공하는 다양한 함수들을 적용, 구현하여 가상 대기실을 적용할 수 있습니다.

최소 요구 사항

Android API Level 22 (Lollipop 5.1) 이상
Java 1.8 이상
Kotlin 2.0.0-RC1 이상

외부 의존성

Ktor (3.0.0 이상)
Kotlinx Serialization (버전 무관)

에이전트 동작 흐름

대기 전

대기 전, 설정 정보를 초기화합니다. 이 과정은 NetFUNNEL 서버로부터 설정 정보를 Fetch하고 해당 정보들을 기반으로 객체들을 초기화하는 과정입니다.
“초기화 함수”를 사용하여 NetFUNNEL의 설정 정보를 초기화하세요.

대기 중

가상 대기실을 노출하여 트래픽 대기를 적용하고 싶은 화면(Activity 혹은 Fragment)에서 대기시키는 과정입니다.
“대기 시작 함수”를 사용하여 가상 대기실을 적용하세요.

대기 후

대기가 종료된 이후 상황에 대한 처리 과정입니다. end-user의 대기가 종료되는 상황은 다음과 같습니다.
- 대기 마친 후, 진입 성공
- 대기 도중, 서버 에러 혹은 네트워크 에러 상황으로 인해 진입 실패
- 대기 도중, end-user의 대기 취소
“콜백 함수”와 “대기 종료 함수”를 사용하여 대기 종료 후 로직을 구현하세요.

에이전트 설치

정보

본 가이드는 Android Studio 환경을 기준으로 작성합니다.

NetFUNNEL Android 에이전트는 .aar(Android Archive) 형식으로 제공됩니다. Android 프로젝트에 .aar 파일을 추가하고, Gradle 설정을 통해 종속성을 등록합니다.

에이전트 다운로드

NetFUNNEL 콘솔의 에이전트 탭에서 NetFUNNEL Android 에이전트를 다운로드합니다.

.aar 파일 추가

제공된 .aar 파일을 프로젝트의 app/libs 디렉터리에 복사합니다.

프로젝트 루트/
├── app/
|    └── libs/
|         └── netfunnel-android-agent-release-{{latest}}.aar
|         └── netfunnel-android-agent-debug-{{latest}}.aar
└── gradle/

Gradle 설정

에이전트 종속성 추가

.aar 파일을 인식시키기 위해 아래와 같이 build.gradle 파일에 종속성을 추가합니다.

Kotlin DSL (build.gradle.kts)

dependencies {
    implementation(files("libs/netfunnel-android-agent-release-{{latest}}.aar"))
    ...
}

Groovy DSL (build.gradle)

dependencies {
    implementation files("libs/netfunnel-android-agent-release-{{latest}}.aar")
    ...
}

정보

NetFUNNEL Android 에이전트는 빌드 환경에 따라 총 2개의 파일을 제공합니다. 디버깅 시에는 debug 사용을 권장하며, 앱 배포 시 release 사용을 권장합니다.

외부 라이브러리 추가

NetFUNNEL Android 에이전트는 외부 라이브러리를 포함하지 않습니다. 아래 라이브러리를 프로젝트에 추가합니다.

Ktor: 네트워크 통신 라이브러리 (3.0.0 이상)
Kotlinx Serialization: 직렬화 라이브러리 (버전 무관)

Kotlin DSL (build.gradle.kts)

dependencies {
    val ktorVersion = "{{KTOR_VERSION}}"
    val serializationVersion = "{{SERIALIZATION_VERSION}}"
    
    // Ktor dependencies
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-okhttp:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-gson:$ktorVersion")
    
    // Serialization dependency
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
    ...
}

Groovy DSL (build.gradle)

ext {
    ktorVersion = "{{KTOR_VERSION}}"
    serializationVersion = "{{SERIALIZATION_VERSION}}"
}

dependencies {
    // Ktor dependencies
    implementation "io.ktor:ktor-client-core:$ktorVersion"
    implementation "io.ktor:ktor-client-okhttp:$ktorVersion"
    implementation "io.ktor:ktor-client-content-negotiation:$ktorVersion"
    implementation "io.ktor:ktor-serialization-gson:$ktorVersion"
    
    // Serialization dependency
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion"
    ...
}

Manifest 설정

NetFUNNEL 서버와 통신하기 위해 인터넷 사용 권한을 추가해야 합니다. AndroidManifest.xml 파일에서 인터넷 접속 권한을 허용합니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:tools="http://schemas.android.com/tools">
   
   <!-- 인터넷 권한 설정 -->
   <uses-permission android:name="android.permission.INTERNET" />
   
</manifest>

에이전트 초기화

NetFUNNEL Android 에이전트는 앱 실행과 동시에 초기화되어야 합니다.

정보

Application 클래스의 onCreate()에서 앱 시작 시 한 번만 실행될 수 있도록 초기화 작업을 수행합니다.

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    serverUrl = "{{SERVER_URL}}",
    errorUrl = "{{ERROR_URL}}",
    networkTimeout = 3000,
    retryCount = 0,
    printLog = false,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "{{USER_ID}}",
    useNetworkRecoveyMode = true,
    healthCheckUrl = "{{HEALTH_CHECK_URL}}",
    statusBarStyle = null
)

Java

Netfunnel.INSTANCE.initialize(
        "{{CLIENT_ID}}",
        "{{SERVER_URL}}",
        "{{ERROR_URL}}",
        3000,
        0,
        false,
        false,
        true,
        "{{USER_ID}}",
        true,
        "{{HEALTH_CHECK_URL}}",
        null
);

파라미터	타입	설명	필수 여부	조건
clientId	String	사용자 고유 식별자	O	빈 문자열 불가
serverUrl	String	NetFUNNEL 서버 주소	X	없음 (기본 주소 사용)
errorUrl	String	NetFUNNEL 에러 페이지의 html 주소	X	없음 (기본 주소 사용)
networkTimeout	Long	네트워크 응답을 기다리는 최대 시간	X	기본 (ms): 3,000 최대 (ms): 10,000 최소 (ms): 100
retryCount	Int	네트워크 요청 실패 시 재시도 횟수	X	기본 (time): 0 최대 (time): 10 최소 (time): 0
printLog	Boolean	디버그를 위한 로그 출력 여부	X	기본: false
errorBypass	Boolean	에러 발생 시 바이패스 여부	X	기본: false
useNetfunnelTemplate	Boolean	콘솔에서 커스텀한 NetFUNNEL 대기실 사용 여부	X	기본: true
userId	String	블랙리스트, 화이트리스트 확인을 위한 end-user의 고유 식별자	X	기본: null
useNetworkRecoveryMode	Boolean	네트워크 연결 끊김 시 대기실 유지 및 재연결 시도 기능 사용 여부	X	기본: false
healthCheckUrl	String	네트워크 지연과 NetFUNNEL 서버 장애를 구분하기 위한 헬스체크 URL	X	기본: null
statusBarStyle	String	NetFUNNEL 대기실(웹뷰)의 상태바 투명화 옵션	X	기본: null

에이전트 적용

NetFUNNEL Android 에이전트에서 제공하는 함수를 통해 특정 화면에 대기실을 적용할 수 있습니다.

정보

시작 함수와 종료 함수에 사용하는 프로젝트 키와 세그먼트 키는 콘솔의 프로젝트 탭에서 확인 가능합니다.

콜백 함수

NetFUNNEL Android 에이전트를 사용하기 위해서는 시작 함수와 종료 함수에 콜백 함수를 반드시 주입해야 합니다.

대기실은 다양한 상황(대기 성공, 취소, 차단, 에러, 네트워크 오류 등)에 따라 종료될 수 있으며, 각 상황에 대한 처리 시나리오는 콜백 함수를 통해 구현할 수 있습니다.

abstract class	abstract function	필수 구현 여부
NetfunnelCallback	onSuccess	필수
NetfunnelCallback	onError	필수
NetfunnelCallback	onNetworkError	필수
NetfunnelCallback	onBlock	선택
NetfunnelCallback	onClose	선택
NetfunnelCallback	onContinue	선택
NetfunnelCompleteCallback	onComplete	선택

시작 콜백 - NetfunnelCallback

콜백 함수	상태 코드	시나리오
onSuccess	200	대기열을 정상 통과하여 서비스 이용이 허용
onSuccess	300	구독이나 라이센스 만료 콘솔의 프로젝트/세그먼트 비활성화 에이전트의 errorBypass=true 설정 및 에러 발생 시
onSuccess	303	콘솔의 화이트리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 바이패스)
onError	500	에이전트의 초기화 함수 없이 시작 함수 호출 에이전트의 시작 함수에 존재하지 않는 프로젝트/세그먼트 키 사용 콘솔의 세그먼트 삭제 서버 에러로 인해 응답이 일부 누락된 경우
onNetworkError	1001	네트워크 연결 차단 (와이파이, 셀룰러 데이터 차단)
onNetworkError	1002	네트워크 타임아웃 서버 에러로 인해 유효하지 않은 HTML URL 받은 경우 서버 다운으로 인해 응답받지 못할 경우 (502 등)
onBlock	301	콘솔의 세그먼트 차단 (선의적 진입 차단)
onBlock	302	콘솔의 블랙리스트에 등록된 IP 혹은 ID로 요청한 경우 (관리자 전용 차단) 콘솔의 BotManager Basic 활성화 (악의적 진입 차단)
onClose	495	사후 대기실의 닫기 버튼 클릭하거나 뒤로가기 버튼을 호출한 경우
onClose	496	사전 대기실의 닫기 버튼 클릭하거나 뒤로가기 버튼을 호출한 경우
onClose	497	매크로 차단실의 닫기 버튼 클릭하거나 뒤로가기 버튼을 호출한 경우
onClose	498	차단실의 닫기 버튼 클릭하거나 뒤로가기 버튼을 호출한 경우
onClose	499	기본 대기실의 취소 버튼 클릭하거나 뒤로가기 버튼을 호출한 경우
onContinue	201	에이전트의 useNetfunnelTemplate=false 설정 및 기본 대기 시

Kotlin

import com.nf4.NetfunnelCallback

class StartCallback {

    companion object {
        private const val TAG = "NetFUNNEL"
    }

    private val callback = object : NetfunnelCallback() {
        override fun onSuccess(statusCode: Int, message: String) {
            Log.d(TAG, "onSuccess $statusCode $message")
            /**
            * 대기열 통과 시 시 처리할 로직
            * ex - 서비스 화면 진입 처리
            */
        }

        override fun onError(statusCode: Int, message: String) {
            Log.d(TAG, "onError $statusCode $message")
            /**
            * 에러 발생 시 처리할 로직
            * ex - 사용자에게 오류 메시지 표시 또는 바이패스
            */
        }

        override fun onNetworkError(statusCode: Int, message: String) {
            Log.d(TAG, "onNetworkError $statusCode $message")
            /**
            * 네트워크 에러 발생 시 처리할 로직
            * ex - 네트워크 재연결 안내 또는 재시도 화면으로 이동
            */
        }

        override fun onBlock(statusCode: Int, message: String) {
            Log.d(TAG, "onBlock $statusCode $message")
            /**
            * 사용자 진입 차단 시 처리할 로직
            * ex - 접근 제한 메시지 표시
            */
        }

        override fun onClose(statusCode: Int, message: String) {
            Log.d(TAG, "onClose $statusCode $message")
            /**
            * 사용자가 대기를 취소하거나 뒤로가기한 경우 처리할 로직 (웹뷰 종료로 이전 화면 자동 복귀)
            * ex - 종료 안내 Toast 표시
            */
        }

        override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
            Log.d(TAG, "onContinue $statusCode $message")
            /**
            * 대기 진행 중 UI 업데이트 로직 (자체 커스텀 대기실 사용 시에만 해당)
            * ex - 실시간 대기 정보를 커스텀 대기 화면에 업데이트
            */
        }
    }

    fun getCallback(): NetfunnelCallback = callback
}

Java

import com.nf4.NetfunnelCallback;

public class StartCallback{

    private static final String TAG = "NetFUNNEL";

    private final NetfunnelCallback callback = new NetfunnelCallback() {
        @Override
        public void onSuccess(int statusCode, @NonNull String message) {
            Log.d(TAG, "onSuccess " + statusCode + " " + message);
            /**
            * 대기열 통과 시 시 처리할 로직
            * ex - 서비스 화면 진입 처리
            */
        }

        @Override
        public void onError(int statusCode, @NonNull String message) {
            Log.d(TAG, "onError " + statusCode + " " + message);
            /**
            * 에러 발생 시 처리할 로직
            * ex - 사용자에게 오류 메시지 표시 또는 바이패스
            */
        }

        @Override
        public void onNetworkError(int statusCode, @NonNull String message) {
            Log.d(TAG, "onNetworkError " + statusCode + " " + message);
            /**
            * 네트워크 에러 발생 시 처리할 로직
            * ex - 네트워크 재연결 안내 또는 재시도 화면으로 이동
            */
        }

        @Override
        public void onBlock(int statusCode, @NonNull String message) {
            Log.d(TAG, "onBlock " + statusCode + " " + message);
            /**
            * 사용자 진입 차단 시 처리할 로직
            * ex - 접근 제한 메시지 표시
            */
        }

        @Override
        public void onClose(int statusCode, @NonNull String message) {
            Log.d(TAG, "onClose " + statusCode + " " + message);
            /**
            * 사용자가 대기를 취소한 경우 처리할 로직 (웹뷰 종료로 이전 화면 자동 복귀)
            * ex - 종료 안내 Toast 표시
            */
        }

        @Override
        public void onContinue(int statusCode, @NonNull String message, int aheadWait, int behindWait, @NonNull String waitTime, int progressRate) {
            Log.d(TAG, "onContinue " + statusCode + " " + message);
            /**
            * 대기 진행 중 UI 업데이트 로직 (자체 커스텀 대기실 사용 시에만 해당)
            * ex - 실시간 대기 정보를 커스텀 대기 화면에 업데이트
            */
        }
    };

    public NetfunnelCallback getCallback() {
        return callback;
    }
}

종료 콜백 - NetfunnelCompleteCallback

콜백 함수	상태 코드	시나리오
onComplete	200	대기 완료 후 서버에 진입 키 반납을 성공한 경우
onComplete	500	대기 완료 후 서버에 진입 키 반납을 실패한 경우

Kotlin

import com.nf4.NetfunnelCompleteCallback

class StopCallback {

    companion object {
        private const val TAG = "NetFUNNEL"
    }

    private val callback = object : NetfunnelCompleteCallback() {
        override fun onComplete(statusCode: Int, message: String) {
            Log.d(TAG, "onComplete $statusCode $message")
            /**
            * 진입 키 반납 결과 처리 로직
            * ex - 키 반납 성공 시 다음 페이지로 이동
            */
        }
    }

    fun getCallback(): NetfunnelCompleteCallback = callback
}

Java

import com.nf4.NetfunnelCompleteCallback;

public class StopCallback {

    private static final String TAG = "NetFUNNEL";

    private final NetfunnelCompleteCallback callback = new NetfunnelCompleteCallback() {
        @Override
        public void onComplete(int statusCode, @NonNull String message) {
            Log.d(TAG, "onComplete " + statusCode + " " + message);
            /**
            * 진입 키 반납 결과 처리 로직
            * ex - 키 반납 성공 시 다음 페이지로 이동
            */
        }
    };

    public NetfunnelCompleteCallback getCallback() {
        return callback;
    }
}

기본 제어

시작 함수

특정 화면(Activity 혹은 Fragment)에서 대기실을 적용시키기 위해서는 “대기 시작 함수”를 사용하여 가상 대기실을 노출시킬 수 있습니다. 기본 제어는 end-user가 특정 화면에 진입할 때 대기를 적용하여 서버 부하를 조절하고, end-user 경험을 관리하는 데 유용합니다.

Kotlin

Netfunnel.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity)

Java

Netfunnel.INSTANCE.nfStart("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity);

파라미터	타입	설명	필수 여부
projectKey	String	콘솔의 기본 제어 프로젝트 키	O
segmentKey	String	콘솔의 기본 제어 세그먼트 키	O
callback	NetfunnelCallback	대기실 이벤트 처리를 위한 사용자 정의 콜백 함수	O
activity	Activity	대기실 적용시키는 화면	O

종료 함수

기본 제어의 대기를 성공적으로 마치는 경우, 아래와 같은 2가지 상황을 구현해야 합니다.

대기를 마치고 서비스로 진입하는 코드 (타겟 페이지로 진입하는 코드)
비즈니스 로직을 마치고 “대기 종료 함수”를 호출하여 서비스 진입 키를 NetFUNNEL 서버에 반납하는 코드

Kotlin

Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback)

Java

Netfunnel.INSTANCE.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback);

파라미터	타입	설명	필수 여부
projectKey	String	대기 시작 함수에 사용한 프로젝트 키	O
segmentKey	String	대기 시작 함수에 사용한 세그먼트 키	O
completeCallback	NetfunnelCompleteCallback	대기를 마치고 키 반납을 처리하기 위한 사용자 정의 콜백 함수	O

구간 제어

시작 함수

구간 제어는 특정 페이지의 진입과 종료 사이에 대기 상태를 적용하는 방법입니다. 구간 제어를 통해 사용자는 페이지의 특정 구간에서 원활한 흐름을 유지할 수 있습니다.

이벤트 페이지에 진입한 후 상품을 구매하고, 결제 완료 버튼을 클릭한 경우
end-user의 로그인 이후 로그아웃할 때까지의 주기

구간 제어를 시작하기 위해서는, “구간 시작 함수”를 사용하여 특정 제어 구간의 시작을 정의해야 합니다. 이에 따라 특정 구간의 흐름에서 대기 상태를 유지하도록 설정할 수 있습니다.

Kotlin

Netfunnel.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity)

Java

Netfunnel.INSTANCE.nfStartSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", callback, activity);

파라미터	타입	설명	필수 여부
projectKey	String	콘솔의 구간 제어 프로젝트 키	O
segmentKey	String	콘솔의 구간 제어 세그먼트 키	O
callback	NetfunnelCallback	대기실 이벤트 처리를 위한 사용자 정의 콜백 함수	O
activity	Activity	대기실 적용시키는 화면	O

종료 함수

구간 제어의 대기를 성공적으로 마치는 경우, 아래와 같은 상황을 구현할 수 있습니다.

대기를 마치고 서비스로 진입하는 코드 (타켓 페이지로 진입하는 코드)

구간 제어를 종료하기 위해서는, “구간 종료 함수”를 사용하여 특정 구간의 끝을 정의해야 합니다. 이에 따라 end-user의 구간 제어를 종료하고 다음 end-user가 진입할 수 있도록 설정할 수 있습니다.

Kotlin

Netfunnel.nfStopSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback)

Java

Netfunnel.INSTANCE.nfStopSection("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", completeCallback);

파라미터	타입	설명	필수 여부
projectKey	String	대기 시작 함수에 사용한 프로젝트 키	O
segmentKey	String	대기 시작 함수에 사용한 세그먼트 키	O
completeCallback	NetfunnelCompleteCallback	대기를 마치고 키 반납을 처리하기 위한 사용자 정의 콜백 함수	O

개요​

최소 요구 사항​

외부 의존성​

에이전트 동작 흐름​

대기 전​

대기 중​

대기 후​

에이전트 설치​

에이전트 다운로드​

.aar 파일 추가​

Gradle 설정​

에이전트 종속성 추가​

외부 라이브러리 추가​

Manifest 설정​

에이전트 초기화​

에이전트 적용​

콜백 함수​

시작 콜백 - NetfunnelCallback​

종료 콜백 - NetfunnelCompleteCallback​

기본 제어​

시작 함수​

종료 함수​

구간 제어​

시작 함수​

종료 함수​

개요

최소 요구 사항

외부 의존성

에이전트 동작 흐름

대기 전

대기 중

대기 후

에이전트 설치

에이전트 다운로드

.aar 파일 추가

Gradle 설정

에이전트 종속성 추가

외부 라이브러리 추가

Manifest 설정

에이전트 초기화

에이전트 적용

콜백 함수

시작 콜백 - NetfunnelCallback

종료 콜백 - NetfunnelCompleteCallback

기본 제어

시작 함수

종료 함수

구간 제어

시작 함수

종료 함수