초기화 옵션 참조

모든 NetFUNNEL Android 에이전트 설정 옵션 및 매개변수에 대한 완전한 참조입니다.

---

목차

• 필수 매개변수
• 네트워크 설정
• 디버깅 옵션
• 템플릿 옵션
• 에러 처리 옵션
• UI 구성
• 고급 옵션

---

완전한 초기화 예제

사용 가능한 모든 설정 옵션을 보여주는 완전한 예제입니다:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 3000,
    retryCount = 0,
    printLog = false,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_67890",
    useNetworkRecoveryMode = true,
    statusBarStyle = null
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    false,// printLog
    false,// errorBypass
    true, // useNetfunnelTemplate
    "user_67890", // userId
    true, // useNetworkRecoveryMode
    null  // statusBarStyle
);

---

필수 매개변수

이 매개변수들은 에이전트가 제대로 작동하기 위해 필수입니다.

매개변수	타입	설명	필수	예제
clientId	String	NetFUNNEL 클라이언트 ID	예	"{{CLIENT_ID}}"

우회 모드

clientId가 누락되면 에이전트는 우회 모드로 실행되어 대기실 없이 직접 접근을 허용합니다.

---

네트워크 설정

NetFUNNEL 서버 통신에 대한 네트워크 동작 및 타임아웃을 제어합니다.

매개변수	타입	필수	기본값	범위
networkTimeout	Long	선택	3000	100–10000
retryCount	Int	선택	0	0–10
useNetworkRecoveryMode	Boolean	선택	false	true/false

networkTimeout

일시적 실패로 간주되기 전에 NetFUNNEL 서버 API 요청에 대한 최대 타임아웃 지속 시간입니다.

속성	값
단위	밀리초 (ms)
범위	100–10000
기본값	3000
적용 대상	NetFUNNEL 서버 엔드포인트만

동작:

• 타임아웃 내 응답 없음 → 일시적 실패
• 즉시 에러 응답 → 타임아웃 대기 없음
• 각 재시도는 동일한 타임아웃 설정을 사용합니다

예제:

• networkTimeout = 1000 → 1초 타임아웃
• networkTimeout = 5000 → 5초 타임아웃

중요 참고사항:

• 너무 짧은 값은 정상 요청이 타임아웃으로 처리될 수 있습니다
• networkTimeout = 3000 및 retryCount = 3인 경우, onNetworkError 콜백 전 최대 대기 시간은 12초입니다
• 에러 응답이 35ms에 도착하더라도 재시도는 다음 시도 전에 2.965초를 대기합니다

retryCount

NetFUNNEL 서버 API 호출에서 일시적 실패에 대한 추가 재시도 횟수입니다.

속성	값
범위	0–10
기본값	0
공식	총 시도 횟수 = (설정 값) + 1
적용 대상	NetFUNNEL 서버 엔드포인트만

동작:

• 일시적 실패 → 재시도 트리거 (재시도 횟수 > 0인 경우)
• 영구적 실패 → 모든 재시도 시도 소진
• 각 재시도는 networkTimeout 설정을 준수합니다

예제:

• retryCount = 0 → 재시도 없음 (단일 시도)
• retryCount = 1 → 초기 1회 + 재시도 1회 (총 2회 시도)
• retryCount = 2 → 초기 1회 + 재시도 2회 (총 3회 시도)

중요 참고사항:

• 재시도 중 요청이 성공하면 재시도 프로세스가 즉시 중지됩니다
• 모든 재시도 시도가 소진된 후 onNetworkError 콜백이 트리거됩니다
• 각 재시도는 networkTimeout 설정을 준수합니다

useNetworkRecoveryMode

네트워크 문제로 인해 사용자가 대기실에서 쫓겨나는 것을 방지합니다. 활성화되면 네트워크 문제가 발생해도 사용자는 대기 상태(모달 또는 대기실)에 머물고, 연결이 복구되면 자동으로 재개됩니다.

속성	값
기본값	false
적용 대상	5002 (진입 확인) 요청만
핵심 이점	네트워크 문제 중 대기 경험에 중단 없음

이것이 해결하는 문제:

• 복구 모드 없음: 네트워크 실패 → 에러 페이지/콜백 → 사용자가 대기 위치 손실
• 복구 모드 있음: 네트워크 실패 → 대기 상태 유지 → 네트워크 복구 시 자동 재개

동작:

모드	5002 (진입 확인)	사용자 경험
true	대기 상태 유지, 자동 복구	중단 없음
false	정상 재시도 → 에러 처리	에러 페이지/콜백

복구 시나리오:

• 빠른 복구: 기존 키/시퀀스 유지 (대기열 위치 유지)
• 장기 중단: 새 키/시퀀스 획득 (위치가 재설정될 수 있음)

중요 참고사항:

• useNetworkRecoveryMode = true는 대기 중 네트워크 실패 중에만 대기실을 유지합니다
• 네트워크가 대기가 시작되기 전에 실패하면 onNetworkError 콜백이 여전히 트리거됩니다
• 이 설정은 일시적인 네트워크 문제로 인해 사용자가 대기 위치를 잃는 것을 방지합니다

---

디버깅 옵션

디버깅 및 로깅 기능을 활성화합니다.

매개변수	타입	필수	기본값	옵션
printLog	Boolean	선택	false	true/false

printLog

NetFUNNEL 로그를 Logcat에 출력합니다.

사용법:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    printLog = true // 디버그 로깅 활성화
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    true, // printLog - 디버그 로깅 활성화
    false,// errorBypass
    true, // useNetfunnelTemplate
    null, // userId
    false,// useNetworkRecoveryMode
    null  // statusBarStyle
);

Logcat에서 로그 확인:

1. Android Studio Logcat 열기
2. package:mine NetFUNNEL로 필터링
3. NetFUNNEL 로그 메시지 확인

로그 출력:

• 초기화 상태
• 네트워크 요청 세부 정보
• 콜백 응답
• 오류 메시지
• 키 관리 이벤트

---

템플릿 옵션

대기실 외관 및 템플릿을 제어합니다.

매개변수	타입	필수	기본값	옵션
useNetfunnelTemplate	Boolean	선택	true	true/false

useNetfunnelTemplate

기본 NetFUNNEL 대기실 템플릿을 사용합니다.

옵션:

• true (기본값): NetFUNNEL의 표준 대기실 템플릿 사용
• false: 사용자 정의 대기실 템플릿 구현 허용

사용자 정의 템플릿 구현:

useNetfunnelTemplate = false인 경우, 사용자 정의 대기실 UI를 구현하고 onContinue 콜백을 처리하여 실시간 대기 정보를 받아야 합니다.

onContinue 콜백 매개변수:

매개변수	타입	설명	예제
statusCode	Int	대기 상태에 대한 응답 코드	201
message	String	대기 상태에 대한 메시지	"Continue"
aheadWait	Int	대기열에서 앞에 있는 사용자 수	{{N}}
behindWait	Int	대기열에서 뒤에 있는 사용자 수	{{N}}
waitTime	String	예상 대기 시간	{{HH:mm:ss}}
progressRate	Int	진행률 백분율	{{0~100}}

기본 사용자 정의 템플릿 예제:

private val callback = object : NetfunnelCallback() {
    override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        // 사용자 정의 대기실 UI 업데이트
        updateCustomWaitingRoom(aheadWait, behindWait, waitTime, progressRate)
    }
}

완전한 사용자 정의 다이얼로그 구현:

1. 사용자 정의 템플릿으로 초기화:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    useNetfunnelTemplate = false  // 사용자 정의 템플릿 활성화
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    false,// printLog
    false,// errorBypass
    false,// useNetfunnelTemplate - 사용자 정의 템플릿 활성화
    null, // userId
    false,// useNetworkRecoveryMode
    null  // statusBarStyle
);

2. 사용자 정의 다이얼로그 XML 레이아웃:

<!-- dialog_netfunnel.xml -->
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:background="@drawable/bg_dialog_rounded"
    android:orientation="vertical"
    android:padding="24dp">
    
    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Expected Wait Time"
        android:textSize="16sp"
        android:textStyle="bold" />
        
    <TextView
        android:id="@+id/txt_wait_time"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="00:00:00"
        android:textSize="28sp"
        android:textStyle="bold" />
        
    <ProgressBar
        android:id="@+id/progress_bar"
        style="?android:attr/progressBarStyleHorizontal"
        android:layout_width="match_parent"
        android:layout_height="12dp"
        android:progress="50" />
        
    <TextView
        android:id="@+id/txt_front_queue"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Users ahead: 0"
        android:textSize="15sp" />
        
    <TextView
        android:id="@+id/txt_behind_queue"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Users behind: 0"
        android:textSize="15sp" />
        
    <Button
        android:id="@+id/btn_cancel"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Close"
        android:textSize="15sp" />
</LinearLayout>

3. 사용자 정의 다이얼로그 컨트롤러:

class NetfunnelDialog(
    context: Context,
    private val onClose: () -> Unit
) : Dialog(context) {
    private lateinit var binding: DialogNetfunnelBinding
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = DialogNetfunnelBinding.inflate(layoutInflater)
        setContentView(binding.root)
        
        binding.btnCancel.setOnClickListener {
            closeDialog()
        }
    }
    
    private fun closeDialog() {
        dismiss()
        onClose()  // 대기 종료를 위해 Netfunnel.nfStop() 호출
    }
    
    fun updateDialog(aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        "Users ahead: $aheadWait".also { binding.txtFrontQueue.text = it }
        "Users behind: $behindWait".also { binding.txtBehindQueue.text = it }
        binding.txtWaitTime.text = waitTime
        binding.progressBar.progress = progressRate
    }
}

4. 완전한 콜백 구현:

private val callback = object : NetfunnelCallback() {
    override fun onContinue(statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        activity.runOnUiThread {
            if (dialog == null) {
                dialog = NetfunnelDialog(activity) { 
                    Netfunnel.nfStop("{{PROJECT_KEY}}", "{{SEGMENT_KEY}}", stopCallback)
                }.apply {
                    setCanceledOnTouchOutside(false)
                    show()
                }
            }
            dialog?.updateDialog(aheadWait, behindWait, waitTime, progressRate)
        }
    }
    
    override fun onSuccess(statusCode: Int, message: String) {
        dialog?.dismiss()
        dialog = null
        // 메인 Activity로 이동
    }
    
    override fun onError(statusCode: Int, message: String) {
        dialog?.dismiss()
        dialog = null
        // 오류 처리
    }
}

중요 참고사항:

• 다이얼로그 생성: 다이얼로그를 한 번만 생성한 후 updateDialog()로 UI 업데이트
• UI 업데이트: UI 수정 시 항상 runOnUiThread 사용
• 적절한 종료: 진입 키를 반환하기 위해 다이얼로그를 닫을 때 Netfunnel.nfStop() 호출
• 제한된 기능: 사용자 정의 템플릿은 고급 대기실 기능에 제한이 있습니다
• 권장사항: 사용자 정의 UI가 필요한 경우가 아니면 전체 기능을 위해 useNetfunnelTemplate = true 사용

---

에러 처리 옵션

에러가 처리되고 사용자에게 표시되는 방식을 제어합니다.

매개변수	타입	필수	기본값	옵션
errorBypass	Boolean	선택	false	true/false

errorBypass

Error/NetworkError를 Success로 처리합니다.

동작:

• false (기본값): 정상 오류 처리 (오류 시 콜백/리다이렉트)
• true: 오류를 성공으로 처리하여 서비스가 계속 진행되도록 허용 (우회 모드)

errorBypass = true인 경우:

• onError 및 onNetworkError 콜백이 호출되지 않음
• 대신 onSuccess 콜백이 트리거됨
• onSuccess 콜백만 구현하면 됨
• 모든 오류 상황이 우회됨

errorBypass = true 사용 사례:

• 테스트 환경
• 네트워크 연결이 핵심 기능에 영향을 주지 않는 서비스
• 간단한 이벤트 참여 시스템
• 개발 및 디버깅 시나리오

중요 경고:

• errorBypass = true는 모든 오류 상황을 우회합니다
• 중요한 네트워크 문제를 숨길 수 있으므로 주의해서 사용하세요
• 중요한 트래픽 제어가 필요한 프로덕션 환경에서는 권장되지 않습니다

처리되는 오류 유형:

• 네트워크 오류 (1001, 1002)
• 서버 오류 (500)
• 사용자 취소 (499)
• 잘못된 구성 오류

코드 기반 통합 콜백: errorBypass = false인 경우, 다음 콜백이 트리거됩니다:

• onNetworkError: 네트워크 관련 오류 (1001, 1002)
• onError: 서버 오류 (500)
• onClose: 사용자 취소 (499)

네트워크 오류 콜백

NetFUNNEL Android 에이전트는 onNetworkError 콜백을 통해 상세한 네트워크 오류 정보를 제공합니다.

네트워크 오류 유형:

상태 코드	메시지	설명
1001	Network Not Connected	네트워크 연결 차단됨 (WiFi/셀룰러 데이터 비활성화)
1002	Network Timeout	네트워크 응답 지연으로 인한 타임아웃

네트워크 오류 처리 예제:

private val callback = object : NetfunnelCallback() {
    override fun onNetworkError(statusCode: Int, message: String) {
        when (statusCode) {
            1001 -> {
                // 네트워크 연결 차단됨 - 즉시 사용자 안내 표시
                showToast("네트워크 연결에 실패했습니다. 네트워크 설정을 확인해 주세요.", activity)
            }
            1002 -> {
                // 네트워크 타임아웃 - 재시도 화면으로 이동
                navigateToNetworkErrorActivity(activity)
            }
        }
    }
}

오류 처리 전략:

• 1001 (Network Not Connected): 즉시 사용자 안내 (토스트 메시지, 다이얼로그)
• 1002 (Network Timeout): 재시도 옵션이 있는 오류 화면으로 이동

UI 구성

대기실 UI 외관 및 동작을 제어합니다.

매개변수	타입	필수	기본값	옵션
statusBarStyle	String?	선택	null	null, "auto", "black", "white"

statusBarStyle

NetFUNNEL 대기실(WebView)의 상태 표시줄 스타일 및 아이콘 색상을 제어합니다.

사용 가능한 값:

값	설명	동작
null (기본값)	앱의 기본 테마 사용	상태 표시줄이 표시됨, 전체 화면 모드 없음
"auto"	테마에 따른 자동 아이콘 색상	라이트 모드: 검은색 아이콘, 다크 모드: 흰색 아이콘
"black"	항상 검은색 아이콘	테마와 관계없이 고정된 검은색 아이콘 색상
"white"	항상 흰색 아이콘	테마와 관계없이 고정된 흰색 아이콘 색상

동작 세부 사항:

기본값 (null):

• 앱의 기본 테마 설정을 따름
• 전체 화면 모드가 적용되지 않음
• 상태 표시줄이 정상적으로 표시됨

옵션 값 ("auto", "black", "white"):

• 전체 화면 모드가 자동으로 적용됨
• 상태 표시줄이 투명해짐
• 선택한 옵션에 따라 아이콘 색상이 제어됨

사용 예제:

1. 기본 동작:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = null  // 앱의 기본 테마 사용
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    false,// printLog
    false,// errorBypass
    true, // useNetfunnelTemplate
    null, // userId
    false,// useNetworkRecoveryMode
    null  // statusBarStyle - 앱의 기본 테마 사용
);

2. 자동 아이콘 색상:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "auto"  // 테마에 따라 아이콘 색상 자동 조정
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    false,// printLog
    false,// errorBypass
    true, // useNetfunnelTemplate
    null, // userId
    false,// useNetworkRecoveryMode
    "auto" // statusBarStyle - 테마에 따라 아이콘 색상 자동 조정
);

3. 고정된 검은색 아이콘:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "black"  // 항상 검은색 아이콘
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    false,// printLog
    false,// errorBypass
    true, // useNetfunnelTemplate
    null, // userId
    false,// useNetworkRecoveryMode
    "black" // statusBarStyle - 항상 검은색 아이콘
);

4. 고정된 흰색 아이콘:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    statusBarStyle = "white"  // 항상 흰색 아이콘
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    false,// printLog
    false,// errorBypass
    true, // useNetfunnelTemplate
    null, // userId
    false,// useNetworkRecoveryMode
    "white" // statusBarStyle - 항상 흰색 아이콘
);

중요 참고 사항:

• 전체 화면 모드: 옵션 값("auto", "black", "white")을 사용하면 전체 화면 모드가 자동으로 적용됨
• 투명도: 옵션 값을 사용하면 상태 표시줄이 투명해짐
• 테마 호환성: "auto" 옵션은 라이트/다크 테마에 자동으로 적응함
• 아이콘 가시성: 대기실 배경에 따라 적절한 아이콘 색상 선택

상태 표시줄 구성 가이드

상태 표시줄 구성 옵션에 대한 자세한 정보는 기능 가이드 - 대기실 상태 표시줄 설정을 참조하세요.

---

고급 옵션

고급 사용 사례를 위한 추가 구성 옵션입니다.

매개변수	타입	필수	기본값	옵션
userId	String?	선택	null	사용자 식별자 문자열

userId

화이트리스트/블랙리스트 관리를 위한 사용자 식별자를 설정합니다.

사용법:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    userId = "user_67890" // 사용자별 식별자
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    3000, // networkTimeout
    0,    // retryCount
    false,// printLog
    false,// errorBypass
    true, // useNetfunnelTemplate
    "user_67890", // userId - 사용자별 식별자
    false,// useNetworkRecoveryMode
    null  // statusBarStyle
);

사용 사례:

• 특정 사용자 화이트리스트
• 문제가 있는 사용자 블랙리스트
• 사용자별 트래픽 제어
• 분석 및 모니터링

---

완전한 예제

모든 옵션이 포함된 완전한 초기화 예제입니다:

Kotlin

Netfunnel.initialize(
    clientId = "{{CLIENT_ID}}",
    networkTimeout = 5000,
    retryCount = 2,
    printLog = false,
    errorBypass = false,
    useNetfunnelTemplate = true,
    userId = "user_67890",
    useNetworkRecoveryMode = true,
    statusBarStyle = null
)

Java

Netfunnel.INSTANCE.initialize(
    "{{CLIENT_ID}}",
    5000, // networkTimeout
    2,    // retryCount
    false,// printLog
    false,// errorBypass
    true, // useNetfunnelTemplate
    "user_67890", // userId
    true, // useNetworkRecoveryMode
    null  // statusBarStyle
);

---

관련 문서

• 설치 및 초기화: 기본 설정 가이드
• API 참조: 함수 사양 및 콜백
• 문제 해결: 일반적인 문제 및 해결 방법
• 기본 제어 통합: 구현 예제
• 구간 제어 통합: 구현 예제