통합 가이드

1. 에이전트 소개

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

2. 에이전트 설치

2.1 최소 요구 사항

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

참고

이 가이드는 Android Studio 환경을 기준으로 작성되었습니다.

2.2 에이전트 추가

NetFUNNEL Android 에이전트는 .aar(Android Archive) 파일로 제공됩니다.

1. NetFUNNEL 콘솔의 에이전트 탭에서 Android 에이전트를 다운로드합니다.
2. .aar 파일을 프로젝트의 app/libs 디렉터리에 복사합니다.

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

팁

에이전트 파일은 빌드 환경에 따라 두 가지로 제공됩니다. 디버깅에는 debug, 앱 배포에는 release 파일을 사용하세요.

2.3 Gradle 설정

app/build.gradle에 에이전트와 외부 라이브러리 종속성을 추가합니다. NetFUNNEL Android 에이전트는 외부 라이브러리를 포함하지 않으므로 아래 라이브러리를 함께 추가해야 합니다.

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

Kotlin DSL (build.gradle.kts)

dependencies {
    // NetFUNNEL Android 에이전트
    implementation(files("libs/netfunnel-android-agent-release-{VERSION}.aar"))

    // Ktor
    val ktorVersion = "{KTOR_VERSION}"
    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")

    // Kotlinx Serialization
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:{SERIALIZATION_VERSION}")
}

Groovy DSL (build.gradle)

dependencies {
    // NetFUNNEL Android 에이전트
    implementation files("libs/netfunnel-android-agent-release-{VERSION}.aar")

    // Ktor
    def ktorVersion = "{KTOR_VERSION}"
    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"

    // Kotlinx Serialization
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:{SERIALIZATION_VERSION}"
}

2.4 Manifest 설정

NetFUNNEL 서버와 통신하기 위해 AndroidManifest.xml에 인터넷 권한을 추가합니다.

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 인터넷 접속 권한 허용 -->
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

2.5 초기화

NetFUNNEL Android 에이전트는 앱 실행과 동시에 초기화되어야 합니다. Application 클래스의 onCreate()에서 초기화 함수를 한 번 호출합니다.

주의

초기화하지 않고 시작 함수를 호출하면 onError(500)가 반환됩니다. 반드시 앱 실행 시점에 초기화하세요.

Kotlin

SampleApplication.kt

import com.nf4.Netfunnel

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()

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

Java

SampleApplication.java

import com.nf4.Netfunnel;

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Java는 이름 지정 인자를 지원하지 않으므로 아래 순서대로 모든 값을 전달합니다.
        Netfunnel.INSTANCE.initialize(
                "{CLIENT_ID}",         // clientId
                "{SERVER_URL}",        // serverUrl
                "{ERROR_URL}",         // errorUrl
                3000,                  // networkTimeout
                0,                     // retryCount
                false,                 // printLog
                false,                 // errorBypass
                true,                  // useNetfunnelTemplate
                "{USER_ID}",           // userId
                false,                 // useNetworkRecoveryMode
                "{HEALTH_CHECK_URL}",  // healthCheckUrl
                null,                  // statusBarStyle
                null,                  // navigationBarStyle
                null                   // isTransparent
        );
    }
}

참고

{CLIENT_ID}, {SERVER_URL}, {ERROR_URL}은 NetFUNNEL 콘솔의 에이전트 탭에서 확인합니다. 각 값의 의미와 기본값은 아래 파라미터 표를 참고하세요.

NetFUNNEL Android 에이전트는 다양한 부가 기능을 제공합니다. 부가 기능을 활성화하려면 초기화 함수에 설정값을 추가합니다.

파라미터	타입	설명	조건
clientId	String	클라이언트 고유 식별자	필수 · 빈 문자열 불가
serverUrl	String	NetFUNNEL 서버 주소	기본: 기본 주소 사용
errorUrl	String	NetFUNNEL 에러 페이지 HTML 주소	기본: 기본 주소 사용
networkTimeout	Long	네트워크 응답 최대 대기 시간	기본 3,000ms · 최대 10,000ms · 최소 100ms
retryCount	Int	네트워크 재시도 횟수	기본 0 · 최대 10 · 최소 0
printLog	Boolean	디버그 로그 출력	기본: false
errorBypass	Boolean	Error·NetworkError 대신 Success 콜백 반환	기본: false
useNetfunnelTemplate	Boolean	NetFUNNEL 대기실 사용 (false면 커스텀 대기실)	기본: true
userId	String	반복 요청 차단의 ID 기준 차단·허용에 사용할 사용자 ID	기본: null
useNetworkRecoveryMode	Boolean	네트워크 에러 시 대기실 유지 및 회복	기본: false
healthCheckUrl	String	네트워크 헬스 체크 주소	기본: null
statusBarStyle	String	대기실(WebView) 상태바 투명화 옵션	기본: null
navigationBarStyle	String	대기실(WebView) 내비게이션바 투명화 옵션	기본: null
isTransparent	Boolean	대기실(WebView) 배경 투명화	기본: null (불투명)

참고

statusBarStyle및 navigationBarStyle웹뷰 시스템바 스타일 설정에 대한 세부 내용은 고급 기능 - 대기실 투명화에서 확인하세요.

참고

isTransparent웹뷰 배경 투명화 옵션에 대한 세부 내용은 고급 기능 - 대기실 투명화에서 확인하세요.

3. 에이전트 적용

Android 에이전트는 코드 기반 적용을 지원합니다. 대기열을 적용할 화면에서 시작 함수를 호출하고, 진입이 완료된 시점에 종료 함수를 호출합니다. 대기열 적용 지점을 바꿀 때마다 앱 배포가 필요하지만, 트래픽이 발생하기 전에 대기실을 노출하므로 트래픽을 사전에 효과적으로 제어할 수 있습니다.

참고

projectKey와 segmentKey는 NetFUNNEL 콘솔의 프로젝트 탭에서 확인합니다. 시작·종료 함수의 모든 파라미터는 필수입니다.

3.1 기본 제어

시작 함수

대기를 적용하고 싶은 지점에서 함수를 호출하여 키를 발급하고 대기실을 노출시킵니다. 화면 진입이나 이벤트 시작 부분에 적용합니다.

파라미터	타입	설명	필수
projectKey	String	NetFUNNEL 콘솔의 프로젝트 키	O
segmentKey	String	NetFUNNEL 콘솔의 세그먼트 키	O
callback	NetfunnelCallback	대기실 이벤트 처리를 위한 시작 콜백	O
activity	Activity	대기실을 띄울 현재 화면	O

Kotlin

Netfunnel.nfStart("{PROJECT_KEY}", "{SEGMENT_KEY}", startCallback, this)

Java

Netfunnel.INSTANCE.nfStart("{PROJECT_KEY}", "{SEGMENT_KEY}", startCallback, this);

종료 함수

진입을 완료한 후 키 반납을 위해 사용합니다. 진입 성공 후 또는 진입한 유저의 활동이 완료되는 지점에 적용합니다.

파라미터	타입	설명	필수
projectKey	String	NetFUNNEL 콘솔의 프로젝트 키	O
segmentKey	String	NetFUNNEL 콘솔의 세그먼트 키	O
completeCallback	NetfunnelCompleteCallback	키 반납 결과를 받는 종료 콜백	O

Kotlin

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

Java

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

3.2 구간 제어

구간 제어란, 앱의 특정 구간에서 동시 접속자 수를 일정하게 유지하도록 제어하는 기능입니다. 시작 함수 호출 시 키를 발급하고, 종료 함수를 호출하기 전까지는 유저가 활동 구간에 있는 것으로 판단하여 다음 대기자를 진입시키지 않습니다. 종료 함수를 호출하면 키를 반납하고 다음 대기자가 진입합니다. (예: 결제 흐름, 로그인부터 로그아웃까지)

시작 함수

구간이 시작되는 지점에서 호출합니다. 파라미터는 기본 제어의 시작 함수와 같습니다.

Kotlin

Netfunnel.nfStartSection("{PROJECT_KEY}", "{SEGMENT_KEY}", startCallback, this)

Java

Netfunnel.INSTANCE.nfStartSection("{PROJECT_KEY}", "{SEGMENT_KEY}", startCallback, this);

종료 함수

진입한 유저의 활동 구간이 종료되는 지점에서 호출합니다. 파라미터는 기본 제어의 종료 함수와 같습니다.

Kotlin

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

Java

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

3.3 콜백 처리

시작 콜백

시작 함수에 전달한 NetfunnelCallback으로 넷퍼넬 서버의 응답을 받습니다. 응답 결과에 따라 다양한 처리 로직을 수행할 수 있습니다.

참고

onSuccess, onError, onNetworkError는 반드시 구현해야 합니다. 그 외 콜백은 구현하지 않아도 서비스에 영향이 없습니다.

콜백	statusCode	설명
onSuccess	200	대기열을 정상적으로 통과하여 서비스에 진입
onSuccess	300	구독·라이선스 만료 · 프로젝트·세그먼트 비활성화 · errorBypass=true 설정
onSuccess	303	화이트리스트 IP·ID 요청 (우회)
onError	500	초기화 없이 시작 함수 호출 · 존재하지 않는 프로젝트·세그먼트 키 사용 · 대기 중 세그먼트 삭제 · 서버 응답 누락
onNetworkError	1001	네트워크 연결 차단 (Wi-Fi·셀룰러 차단)
onNetworkError	1002	네트워크 타임아웃 · 유효하지 않은 대기실 HTML 주소 · 넷퍼넬 서버 다운
onBlock	301	세그먼트 차단
onBlock	302	블랙리스트 · BotManager Basic 활성화
onClose	499	기본 대기실의 취소 버튼 또는 뒤로 가기
onClose	498	차단실의 닫기 버튼 또는 뒤로 가기
onClose	497	매크로 차단실의 닫기 버튼 또는 뒤로 가기
onClose	496	사전 대기실의 닫기 버튼 또는 뒤로 가기
onClose	495	사후 대기실의 닫기 버튼 또는 뒤로 가기
onContinue	201	useNetfunnelTemplate=false로 대기 중 (커스텀 대기실)

Kotlin

StartCallback 예시

import com.nf4.NetfunnelCallback

val startCallback = object : NetfunnelCallback() {
    override fun onSuccess(statusCode: Int, message: String) {
        // 진입 또는 우회 응답: 넷퍼넬 적용 이전의 원래 서비스 로직 실행
        // 예) 화면 이동, 함수 실행, API 요청
    }

    override fun onError(statusCode: Int, message: String) {
        // 시스템 에러: 원활한 서비스 이용을 위해 원래 서비스 로직 실행
    }

    override fun onNetworkError(statusCode: Int, message: String) {
        // 네트워크 에러: 원래 로직 실행 또는 안내 후 대기열 재진입
    }

    override fun onBlock(statusCode: Int, message: String) {
        // 진입 차단: 차단 안내 또는 무동작
    }

    override fun onClose(statusCode: Int, message: String) {
        // 대기실 닫기·취소: 취소 안내 또는 무동작
    }

    override fun onContinue(
        statusCode: Int, message: String,
        aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int
    ) {
        // 커스텀 대기실 사용 시: 대기 정보로 UI 갱신
    }
}

Java

StartCallback 예시

import com.nf4.NetfunnelCallback;

NetfunnelCallback startCallback = new NetfunnelCallback() {
    @Override
    public void onSuccess(int statusCode, @NonNull String message) {
        // 진입 또는 우회 응답: 넷퍼넬 적용 이전의 원래 서비스 로직 실행
    }

    @Override
    public void onError(int statusCode, @NonNull String message) {
        // 시스템 에러: 원활한 서비스 이용을 위해 원래 서비스 로직 실행
    }

    @Override
    public void onNetworkError(int statusCode, @NonNull String message) {
        // 네트워크 에러: 원래 로직 실행 또는 안내 후 대기열 재진입
    }

    @Override
    public void onBlock(int statusCode, @NonNull String message) {
        // 진입 차단: 차단 안내 또는 무동작
    }

    @Override
    public void onClose(int statusCode, @NonNull String message) {
        // 대기실 닫기·취소: 취소 안내 또는 무동작
    }

    @Override
    public void onContinue(int statusCode, @NonNull String message,
                           int aheadWait, int behindWait, @NonNull String waitTime, int progressRate) {
        // 커스텀 대기실 사용 시: 대기 정보로 UI 갱신
    }
};

종료 콜백

종료 함수에 전달한 NetfunnelCompleteCallback으로 키 반납 결과를 받습니다. 구현하지 않아도 서비스에 영향이 없습니다.

콜백	statusCode	설명
onComplete	200	진입 키 반납 성공
onComplete	500	진입 키 반납 실패

Kotlin

StopCallback 예시

import com.nf4.NetfunnelCompleteCallback

val stopCallback = object : NetfunnelCompleteCallback() {
    override fun onComplete(statusCode: Int, message: String) {
        // 키 반납 후 실행할 로직
    }
}

Java

StopCallback 예시

import com.nf4.NetfunnelCompleteCallback;

NetfunnelCompleteCallback stopCallback = new NetfunnelCompleteCallback() {
    @Override
    public void onComplete(int statusCode, @NonNull String message) {
        // 키 반납 후 실행할 로직
    }
};