초기화 옵션 참조

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

완전한 초기화 예제

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

Swift

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self
)

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self];

---

목차

• 필수 매개변수
• 네트워크 설정
• 디버깅 옵션
• 템플릿 옵션
• 오류 처리 옵션
• 고급 옵션

---

필수 매개변수

이러한 매개변수는 에이전트가 올바르게 작동하기 위해 필수입니다.

매개변수	유형	설명	필수	예제
clientId	String	NetFUNNEL 콘솔에서 제공하는 클라이언트 ID	예	"{{CLIENT_ID}}"
delegate	NetfunnelDelegate	NetfunnelDelegate 프로토콜을 구현하는 델리게이트 객체	예	self

우회 모드

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

clientId

유형: String
필수: ✅ 예
설명: NetFUNNEL 콘솔에서 제공하는 클라이언트 ID

Swift

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    // ... 다른 매개변수들
)

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                // ... 다른 매개변수들
];

요구 사항:

• 비어있지 않아야 함
• NetFUNNEL 콘솔의 클라이언트 ID와 일치해야 함
• 문서 예제에서는 플레이스홀더 {{CLIENT_ID}} 사용

delegate

유형: NetfunnelDelegate
필수: ✅ 예
설명: NetfunnelDelegate 프로토콜을 구현하는 델리게이트 객체

Swift

class AppDelegate: UIResponder, UIApplicationDelegate, NetfunnelDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: self
        )
        return true
    }
}

Objective-C

@interface AppDelegate : UIResponder <UIApplicationDelegate, NetfunnelDelegate>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self];
    return YES;
}

@end

요구 사항:

• NetfunnelDelegate 프로토콜을 구현해야 함
• 필수 델리게이트 메서드를 구현해야 함
• 모든 콜백 시나리오를 처리해야 함

---

네트워크 설정

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

매개변수	유형	필수	기본값	범위
networkTimeout	NSNumber (Long)	선택	3000	100–10000
retryCount	NSNumber (Int)	선택	0	0–10
useNetworkRecoveryMode	NSNumber (Bool)	선택	false	true/false

networkTimeout

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

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

동작:

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

예제:

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

중요 참고 사항:

• 너무 짧은 값은 정상 요청을 타임아웃으로 처리할 수 있음
• networkTimeout: 3000 및 retryCount: 3인 경우, nfNetworkError 콜백 전 최대 대기 시간은 12초
• 오류 응답이 35ms에 도착하더라도 재시도는 다음 시도 전에 2.965초를 대기함

Swift

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    networkTimeout: 5000 // 5초
)

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@5000];

retryCount

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

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

동작:

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

예제:

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

중요 참고 사항:

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

Swift

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    retryCount: 3 // 최대 3회 재시도
)

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@3];

useNetworkRecoveryMode

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

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

이것이 해결하는 문제:

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

동작:

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

복구 시나리오:

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

중요 참고 사항:

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

Swift

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    useNetworkRecoveryMode: true // 네트워크 복구 활성화
)

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                      useNetworkRecoveryMode:@true];

---

디버깅 옵션

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

매개변수	유형	필수	기본값	옵션
printLog	NSNumber (Bool)	선택	false	true/false

printLog

Xcode 콘솔에 NetFUNNEL 로그를 출력합니다.

사용법:

Swift

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

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@true];

Xcode 콘솔에서 로그 확인:

1. Xcode 콘솔 열기
2. NetFUNNEL로 필터링
3. NetFUNNEL 로그 메시지 찾기

로그 출력:

• 초기화 상태
• 네트워크 요청 세부 정보
• 델리게이트 메서드 호출
• 오류 메시지
• 키 관리 이벤트

---

템플릿 옵션

대기실 모양 및 템플릿을 제어합니다.

매개변수	유형	필수	기본값	옵션
useNetfunnelTemplate	NSNumber (Bool)	선택	true	true/false

useNetfunnelTemplate

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

옵션:

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

사용자 정의 템플릿 구현:

useNetfunnelTemplate: false인 경우, 사용자 정의 대기실 UI를 구현하고 실시간 대기 정보를 받기 위해 nfContinue 델리게이트 메서드를 처리해야 합니다.

nfContinue 델리게이트 매개변수:

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

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

extension AppDelegate: NetfunnelDelegate {
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        // 사용자 정의 대기실 UI 업데이트
        updateCustomWaitingRoom(aheadWait: aheadWait, behindWait: behindWait, waitTime: waitTime, progressRate: progressRate)
    }
}

완전한 사용자 정의 뷰 컨트롤러 구현:

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

Swift

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

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@false
                        useNetfunnelTemplate:@false];

2. 사용자 정의 대기실 뷰 컨트롤러:

class CustomWaitingRoomViewController: UIViewController {
    @IBOutlet weak var waitTimeLabel: UILabel!
    @IBOutlet weak var progressBar: UIProgressView!
    @IBOutlet weak var aheadLabel: UILabel!
    @IBOutlet weak var behindLabel: UILabel!
    @IBOutlet weak var cancelButton: UIButton!
    
    var onCancel: (() -> Void)?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
    }
    
    private func setupUI() {
        view.backgroundColor = UIColor.systemBackground
        progressBar.progress = 0.0
        cancelButton.addTarget(self, action: #selector(cancelTapped), for: .touchUpInside)
    }
    
    func updateWaitingInfo(aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        DispatchQueue.main.async {
            self.aheadLabel.text = "앞 사용자 수: \(aheadWait)"
            self.behindLabel.text = "뒤 사용자 수: \(behindWait)"
            self.waitTimeLabel.text = waitTime
            self.progressBar.progress = Float(progressRate) / 100.0
        }
    }
    
    @objc private func cancelTapped() {
        dismiss(animated: true) {
            self.onCancel?()
        }
    }
}

3. 완전한 델리게이트 구현:

extension AppDelegate: NetfunnelDelegate {
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        DispatchQueue.main.async {
            if self.waitingRoomVC == nil {
                self.waitingRoomVC = CustomWaitingRoomViewController()
                self.waitingRoomVC?.modalPresentationStyle = .fullScreen
                self.waitingRoomVC?.onCancel = {
                    Netfunnel.shared.nfStop(projectKey: projectKey, segmentKey: segmentKey)
                }
                self.window?.rootViewController?.present(self.waitingRoomVC!, animated: true)
            }
            self.waitingRoomVC?.updateWaitingInfo(aheadWait: aheadWait, behindWait: behindWait, waitTime: waitTime, progressRate: progressRate)
        }
    }
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async {
            self.waitingRoomVC?.dismiss(animated: true)
            self.waitingRoomVC = nil
            // 메인 콘텐츠로 이동
        }
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async {
            self.waitingRoomVC?.dismiss(animated: true)
            self.waitingRoomVC = nil
            // 오류 처리
        }
    }
}

중요 참고 사항:

• 뷰 컨트롤러 생성: 뷰 컨트롤러를 한 번만 생성한 다음 updateWaitingInfo로 UI 업데이트
• UI 업데이트: UI 수정을 위해 항상 DispatchQueue.main.async 사용
• 적절한 종료: 진입 키를 반환하기 위해 뷰 컨트롤러를 닫을 때 Netfunnel.shared.nfStop() 호출
• 제한된 기능: 사용자 정의 템플릿은 고급 대기실 기능에 제한이 있음
• 권장 사항: 사용자 정의 UI가 필요한 경우를 제외하고는 useNetfunnelTemplate: true를 사용하여 전체 기능 활용

errorBypass

유형: NSNumber (Bool)
필수: ❌ 아니오
기본값: false
설명: 오류 시 트래픽 제어 우회

Swift

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    errorBypass: false // 오류 시 우회하지 않음
)

objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@false
                        useNetfunnelTemplate:@true
                                 errorBypass:@false
                                    // ... 다른 매개변수들
];

동작:

값	동작
false	오류 발생 시에도 트래픽 제어 유지 (권장)
true	오류 시 사용자가 대기실을 우회할 수 있도록 허용

---

오류 처리 옵션

오류 처리 및 사용자 표시 방식을 제어합니다.

매개변수	유형	필수	기본값	옵션
errorBypass	NSNumber (Bool)	선택	false	true/false

errorBypass

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

동작:

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

errorBypass: true인 경우:

• nfError 및 nfNetworkError 델리게이트 메서드가 호출되지 않음
• 대신 nfSuccess 델리게이트 메서드가 트리거됨
• nfSuccess 델리게이트 메서드만 구현하면 됨
• 모든 오류 상황이 우회됨

errorBypass: true 사용 사례:

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

중요 경고:

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

처리되는 오류 유형:

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

델리게이트 기반 통합 콜백: errorBypass: false인 경우 다음 델리게이트 메서드가 트리거됩니다:

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

네트워크 오류 콜백

NetFUNNEL iOS 에이전트는 nfNetworkError 델리게이트 메서드를 통해 자세한 네트워크 오류 정보를 제공합니다.

네트워크 오류 유형:

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

네트워크 오류 처리 예제:

extension AppDelegate: NetfunnelDelegate {
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        switch statusCode {
        case 1001:
            // 네트워크 연결 차단 - 즉시 사용자 안내 표시
            showAlert(title: "Network Error", message: "네트워크 연결에 실패했습니다. 네트워크 설정을 확인해 주세요.")
        case 1002:
            // 네트워크 타임아웃 - 재시도 화면으로 이동
            navigateToNetworkErrorScreen()
        default:
            break
        }
    }
}

오류 처리 전략:

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

---

고급 옵션

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

매개변수	유형	필수	기본값	옵션
userId	String?	선택	nil	사용자 식별자 문자열

userId

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

사용법:

Swift

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

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@3000
                                  retryCount:@0
                                    printLog:@false
                        useNetfunnelTemplate:@true
                                 errorBypass:@false
                                      userId:@"user_67890"];

사용 사례:

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

---

완전한 예제

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

Swift

Netfunnel.initialize(
    clientId: "{{CLIENT_ID}}",
    delegate: self,
    networkTimeout: 5000,
    retryCount: 2,
    printLog: false,
    errorBypass: false,
    useNetfunnelTemplate: true,
    userId: "user_67890",
    useNetworkRecoveryMode: true
)

Objective-C

[agent initializeWithClientId:@"{{CLIENT_ID}}"
                                delegate:self
                              networkTimeout:@5000
                                  retryCount:@2
                                    printLog:@false
                        useNetfunnelTemplate:@true
                                 errorBypass:@false
                                      userId:@"user_67890"
                      useNetworkRecoveryMode:@true];

---

관련 문서

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