버전: 4.6.1

iOS 에이전트 API 참조

NetFUNNEL 4 iOS 에이전트 함수, 델리게이트 및 응답 형식에 대한 완전한 참조입니다.

개요

NetFUNNEL iOS 에이전트는 iOS 애플리케이션에서 트래픽 제어를 구현하기 위한 포괄적인 API를 제공합니다. 이 참조는 사용 가능한 모든 함수, 델리게이트 메서드 및 설정 옵션을 다룹니다.

핵심 함수

에이전트 초기화

설정 매개변수로 NetFUNNEL 에이전트를 초기화합니다.

Swift
Objective-C

Netfunnel.initialize(
    clientId: String,
    delegate: NetfunnelDelegate,
    networkTimeout: NSNumber?,
    retryCount: NSNumber?,
    printLog: NSNumber?,
    useNetfunnelTemplate: NSNumber?,
    errorBypass: NSNumber?,
    userId: String?,
    useNetworkRecoveryMode: NSNumber?
)

[agent initializeWithClientId:(NSString *)clientId
                                    delegate:(id<NetfunnelDelegate>)delegate
                              networkTimeout:(NSNumber *)networkTimeout
                                  retryCount:(NSNumber *)retryCount
                                    printLog:(NSNumber *)printLog
                        useNetfunnelTemplate:(NSNumber *)useNetfunnelTemplate
                                 errorBypass:(NSNumber *)errorBypass
                                      userId:(NSString *)userId
                      useNetworkRecoveryMode:(NSNumber *)useNetworkRecoveryMode];

매개변수:

매개변수	유형	필수	기본값	설명
`clientId`	`String`	✅	-	NetFUNNEL 콘솔에서 제공하는 클라이언트 ID
`delegate`	`NetfunnelDelegate`	✅	-	프로토콜을 구현하는 델리게이트 객체
`networkTimeout`	`NSNumber (Long)`	❌	3000	네트워크 타임아웃 (ms), 최소: 100, 최대: 10000
`retryCount`	`NSNumber (Int)`	❌	0	재시도 시도, 최소: 0, 최대: 10
`printLog`	`NSNumber (Bool)`	❌	false	디버그 로깅 활성화
`useNetfunnelTemplate`	`NSNumber (Bool)`	❌	true	콘솔의 대기실 템플릿 사용
`errorBypass`	`NSNumber (Bool)`	❌	false	오류 시 우회
`userId`	`String`	❌	N/A	화이트/블랙리스트 매칭 값
`useNetworkRecoveryMode`	`NSNumber (Bool)`	❌	false	네트워크 문제 중 대기실 열어두기

기본 제어 함수

기본 제어 시작

진입 속도 제한을 위한 기본 제어를 시작합니다.

Swift
Objective-C

Netfunnel.shared.nfStart(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStartWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

매개변수:

매개변수	유형	필수	설명
`projectKey`	`String`	✅	콘솔의 기본 제어 프로젝트 키
`segmentKey`	`String`	✅	콘솔의 기본 제어 세그먼트 키

기본 제어 중지

기본 제어를 중지하고 진입 키를 반환합니다.

Swift
Objective-C

Netfunnel.shared.nfStop(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStopWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

매개변수:

매개변수	유형	필수	설명
`projectKey`	`String`	✅	기본 제어 프로젝트 키
`segmentKey`	`String`	✅	기본 제어 세그먼트 키

구간 제어 함수

구간 제어 시작

동시 사용자 관리를 위한 구간 제어를 시작합니다.

Swift
Objective-C

Netfunnel.shared.nfStartSection(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStartSectionWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

매개변수:

매개변수	유형	필수	설명
`projectKey`	`String`	✅	콘솔의 구간 제어 프로젝트 키
`segmentKey`	`String`	✅	콘솔의 구간 제어 세그먼트 키

구간 제어 중지

구간 제어를 중지하고 구간 키를 반환합니다.

Swift
Objective-C

Netfunnel.shared.nfStopSection(projectKey: String, segmentKey: String)

[[Netfunnel shared] nfStopSectionWithProjectKey:(NSString *)projectKey segmentKey:(NSString *)segmentKey];

매개변수:

매개변수	유형	필수	설명
`projectKey`	`String`	✅	구간 제어 프로젝트 키
`segmentKey`	`String`	✅	구간 제어 세그먼트 키

유틸리티 함수

버전 가져오기

NetFUNNEL iOS 에이전트 버전을 반환합니다.

Swift
Objective-C

let version = Netfunnel.shared.getVersion()

NSString *version = [[Netfunnel shared] getVersion];

반환 값:

유형	설명
`String`	NetFUNNEL 에이전트 버전 문자열

델리게이트 프로토콜

NetfunnelDelegate 프로토콜은 NetFUNNEL 이벤트를 처리하기 위한 콜백 메서드를 정의합니다.

필수 메서드

nfSuccess

사용자가 큐를 성공적으로 통과했을 때 호출됩니다.

Swift
Objective-C

func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfSuccessWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message;

매개변수:

매개변수	유형	설명
`projectKey`	`String`	프로젝트 키
`segmentKey`	`String`	세그먼트 키
`statusCode`	`Int`	상태 코드 (200, 300, 303)
`message`	`String`	성공 메시지

상태 코드:

코드	시나리오
200	큐를 통과함; 접근 허용됨
300	구독/라이선스 만료; 프로젝트/세그먼트 비활성화; 오류와 함께 `errorBypass = true`
303	화이트리스트의 IP/ID에서 요청 (관리자 우회)

nfError

시스템 오류가 발생했을 때 호출됩니다.

Swift
Objective-C

func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfErrorWithProjectKey:(NSString *)projectKey
                    segmentKey:(NSString *)segmentKey
                    statusCode:(NSInteger)statusCode
                       message:(NSString *)message;

매개변수:

매개변수	유형	설명
`projectKey`	`String`	프로젝트 키
`segmentKey`	`String`	세그먼트 키
`statusCode`	`Int`	상태 코드 (500)
`message`	`String`	오류 메시지

상태 코드:

코드	시나리오
500	초기화 없이 Start 호출됨; 잘못된 키; 세그먼트 삭제됨; 부분 서버 응답

nfNetworkError

네트워크 오류가 발생했을 때 호출됩니다.

Swift
Objective-C

func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfNetworkErrorWithProjectKey:(NSString *)projectKey
                           segmentKey:(NSString *)segmentKey
                           statusCode:(NSInteger)statusCode
                              message:(NSString *)message;

매개변수:

매개변수	유형	설명
`projectKey`	`String`	프로젝트 키
`segmentKey`	`String`	세그먼트 키
`statusCode`	`Int`	상태 코드 (1001, 1002)
`message`	`String`	네트워크 오류 메시지

상태 코드:

코드	시나리오
1001	네트워크 연결 끊김 (Wi-Fi/셀룰러 꺼짐)
1002	네트워크 타임아웃; 잘못된 HTML URL; 서버 다운 (예: 502)

선택적 메서드

nfBlock

사용자가 차단되었을 때 호출됩니다.

Swift
Objective-C

func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfBlockWithProjectKey:(NSString *)projectKey
                   segmentKey:(NSString *)segmentKey
                   statusCode:(NSInteger)statusCode
                      message:(NSString *)message;

상태 코드:

코드	시나리오
301	콘솔에서 세그먼트 차단됨 (선의의 차단)
302	블랙리스트의 IP/ID에서 요청; BotManager Basic 활성화됨 (악의적 차단)

nfClose

사용자가 대기실을 닫을 때 호출됩니다.

Swift
Objective-C

func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfCloseWithProjectKey:(NSString *)projectKey
                   segmentKey:(NSString *)segmentKey
                   statusCode:(NSInteger)statusCode
                      message:(NSString *)message;

상태 코드:

코드	시나리오
495	대기실 후: 닫기 버튼 클릭됨
496	대기실 전: 닫기 버튼 클릭됨
497	매크로 차단 방: 닫기 버튼 클릭됨
498	차단 방: 닫기 버튼 클릭됨
499	기본 대기실: 취소 버튼 클릭됨

nfContinue

사용자 정의 대기 UI를 사용할 때 (useNetfunnelTemplate = false) 호출됩니다.

Swift
Objective-C

func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int)

- (void)nfContinueWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message
                       aheadWait:(NSInteger)aheadWait
                      behindWait:(NSInteger)behindWait
                        waitTime:(NSString *)waitTime
                    progressRate:(NSInteger)progressRate;

매개변수:

매개변수	유형	설명
`projectKey`	`String`	프로젝트 키
`segmentKey`	`String`	세그먼트 키
`statusCode`	`Int`	상태 코드 (201)
`message`	`String`	계속 메시지
`aheadWait`	`Int`	큐에서 앞에 있는 사용자 수
`behindWait`	`Int`	큐에서 뒤에 있는 사용자 수
`waitTime`	`String`	예상 대기 시간
`progressRate`	`Int`	진행률 백분율 (0-100)

상태 코드:

코드	시나리오
201	`useNetfunnelTemplate = false`일 때 (사용자 정의 대기 UI 사용 중)

nfComplete

서버로 키 반환이 완료되었을 때 호출됩니다.

Swift
Objective-C

func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String)

- (void)nfCompleteWithProjectKey:(NSString *)projectKey
                      segmentKey:(NSString *)segmentKey
                      statusCode:(NSInteger)statusCode
                         message:(NSString *)message;

상태 코드:

코드	시나리오
200	서버로 진입 키 반환 성공
500	서버로 진입 키 반환 실패

모범 사례

1. UI 업데이트에 항상 메인 큐 사용

func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    DispatchQueue.main.async {
        // 여기서 UI 업데이트
        self.updateUI()
    }
}

2. 모든 필수 델리게이트 메서드 구현

class ViewController: UIViewController, NetfunnelDelegate {
    // 필수 메서드
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    
    // 선택적 메서드 (필요에 따라 구현)
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) { }
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) { }
}

3. 오류를 우아하게 처리

func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    // 디버깅을 위해 오류 로깅
    print("NetFUNNEL Error: \(statusCode) - \(message)")
    
    // 서비스 가용성을 위해 원래 로직 진행
    DispatchQueue.main.async {
        self.proceedWithOriginalLogic()
    }
}

4. 키를 즉시 반환

// 기본 제어 - 작업 후 즉시 키 반환
private func performAction() {
    // 작업 로직
    actionService.performAction { [weak self] result in
        // 작업 완료 후 즉시 키 반환
        Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
    }
}

// 구간 제어 - 전체 구간이 완료될 때 키 반환
private func completeSection() {
    // 구간 완료 로직
    sectionService.completeSection { [weak self] result in
        if result.success {
            // 구간이 완전히 완료될 때 키 반환
            Netfunnel.shared.nfStopSection(projectKey: "project", segmentKey: "segment")
        }
    }
}

5. 설명적인 프로젝트/세그먼트 키 사용

// ✅ 좋음: 설명적인 키
Netfunnel.shared.nfStart(projectKey: "ecommerce_app", segmentKey: "checkout_protection")

// ❌ 나쁨: 일반적인 키
Netfunnel.shared.nfStart(projectKey: "project1", segmentKey: "segment1")

오류 처리

일반적인 오류 시나리오

오류 유형	상태 코드	원인	해결 방법
시스템 오류	500	잘못된 키, 세그먼트 삭제됨	콘솔 구성 확인
네트워크 오류	1001	인터넷 연결 없음	네트워크 복구 모드 활성화
네트워크 오류	1002	서버 타임아웃/다운	서버 상태 확인
차단	301	세그먼트 차단됨	세그먼트 활성화 확인
차단	302	사용자가 블랙리스트에 있음	사용자 상태 확인

오류 복구 전략

func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    switch statusCode {
    case 1001: // 네트워크 연결 끊김
        // 오프라인 메시지 표시, 네트워크 복구 모드 활성화
        showOfflineMessage()
    case 1002: // 네트워크 타임아웃/서버 다운
        // 재시도 옵션 표시, 서버 상태 확인
        showRetryOption()
    default:
        // 알 수 없는 네트워크 오류 로깅
        print("Unknown network error: \(statusCode)")
    }
}

성능 고려 사항

1. 델리게이트 메서드 오버헤드 최소화

// ✅ 좋음: 효율적인 델리게이트 구현
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    DispatchQueue.main.async { [weak self] in
        self?.handleSuccess()
    }
}

// ❌ 나쁨: 델리게이트에서 무거운 작업
func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
    // 무거운 작업은 별도 메서드로 이동해야 함
    performHeavyOperation()
    updateDatabase()
    sendAnalytics()
}

2. 약한 참조 사용

class ViewController: UIViewController, NetfunnelDelegate {
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        DispatchQueue.main.async { [weak self] in
            self?.handleSuccess()
        }
    }
}

3. 키 반환 타이밍 최적화

// ✅ 좋음: 최적의 시점에 키 반환
override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment")
}

// ❌ 나쁨: 너무 일찍 키 반환
override func viewDidLoad() {
    super.viewDidLoad()
    Netfunnel.shared.nfStop(projectKey: "project", segmentKey: "segment") // 너무 이르다!
}

디버깅

디버그 로깅 활성화

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

네트워크 요청 모니터링

Xcode의 Network Inspector 또는 Charles Proxy와 같은 도구를 사용하여 NetFUNNEL 요청을 모니터링합니다:

시작 요청: NetFUNNEL 서버로의 요청 찾기
키 반환 요청: nfStop/nfStopSection 요청 찾기
타임아웃 확장: 5003 요청 찾기 (구간 제어)

일반적인 디버그 시나리오

문제	디버그 단계
대기실이 나타나지 않음	진입 허용 수 = 0 확인, 세그먼트 활성화 확인
키가 반환되지 않음	`nfStop`/`nfStopSection` 호출 확인
델리게이트에서 앱 충돌	메인 큐에서 UI 업데이트 확인
네트워크 오류	`printLog = true` 활성화, 연결 확인

개요​

핵심 함수​

에이전트 초기화​

기본 제어 함수​

기본 제어 시작​

기본 제어 중지​

구간 제어 함수​

구간 제어 시작​

구간 제어 중지​

유틸리티 함수​

버전 가져오기​

델리게이트 프로토콜​

필수 메서드​

nfSuccess​

nfError​

nfNetworkError​

선택적 메서드​

nfBlock​

nfClose​

nfContinue​

nfComplete​

모범 사례​

1. UI 업데이트에 항상 메인 큐 사용​

2. 모든 필수 델리게이트 메서드 구현​

3. 오류를 우아하게 처리​

4. 키를 즉시 반환​

5. 설명적인 프로젝트/세그먼트 키 사용​

오류 처리​

일반적인 오류 시나리오​

오류 복구 전략​

성능 고려 사항​

1. 델리게이트 메서드 오버헤드 최소화​

2. 약한 참조 사용​

3. 키 반환 타이밍 최적화​

디버깅​

디버그 로깅 활성화​

네트워크 요청 모니터링​

일반적인 디버그 시나리오​

개요

핵심 함수

에이전트 초기화

기본 제어 함수

기본 제어 시작

기본 제어 중지

구간 제어 함수

구간 제어 시작

구간 제어 중지

유틸리티 함수

버전 가져오기

델리게이트 프로토콜

필수 메서드

nfSuccess

nfError

nfNetworkError

선택적 메서드

nfBlock

nfClose

nfContinue

nfComplete

모범 사례

1. UI 업데이트에 항상 메인 큐 사용

2. 모든 필수 델리게이트 메서드 구현

3. 오류를 우아하게 처리

4. 키를 즉시 반환

5. 설명적인 프로젝트/세그먼트 키 사용

오류 처리

일반적인 오류 시나리오

오류 복구 전략

성능 고려 사항

1. 델리게이트 메서드 오버헤드 최소화

2. 약한 참조 사용

3. 키 반환 타이밍 최적화

디버깅

디버그 로깅 활성화

네트워크 요청 모니터링

일반적인 디버그 시나리오