본문으로 건너뛰기
버전: 4.6.1

빠른 시작

이 빠른 시작 가이드로 5-10분 안에 NetFUNNEL 4 iOS 에이전트를 시작하고 실행하세요.

이 가이드로 할 수 있는 것​

  • 코드 기반 통합: iOS 코드에서 NetFUNNEL 함수를 호출하여 트래픽 제어 적용
  • 기본 제어: ViewController 진입, 버튼 탭, API 호출에 대한 진입 속도 제한
  • 구간 제어: 특정 애플리케이션 구간 내의 동시 사용자 제어
제어 유형 선택

어떤 제어 유형을 사용해야 할지 모르시나요? 통합 방법 개요를 확인하여 기본 제어와 구간 제어 접근 방식을 비교하고 사용 사례에 가장 적합한 방법을 찾아보세요.

사전 요구 사항​

  • NetFUNNEL 콘솔 액세스
  • Xcode 환경
  • iOS 개발 기본 이해 (Swift/Objective-C)
  • iOS 12.0 이상
연습 프로젝트 제공

연습할 기본 프로젝트가 필요하신가요? NetFUNNEL SDK 통합 연습을 위한 iOS 애플리케이션 (Single ViewController) 템플릿을 포함한 샘플 프로젝트를 확인하세요.

1단계: SDK 설치 및 에이전트 초기화​

1.1 NetFUNNEL 콘솔에서 SDK 다운로드​

  1. NetFUNNEL 콘솔에 로그인
  2. 이동: Agent → Mobile Agent → iOS
  3. ZIP 파일 다운로드: netfunnel-ios-agent-4.3.2-onprem.zip
  4. ZIP 파일을 추출하여 폴더 구조 확인: 
    netfunnel-ios-agent-4.3.2-onprem/
    ├── netfunnel-ios-agent-debug/
    │   └── netfunnel_ios.xcframework
    └── netfunnel-ios-agent-release/
        └── netfunnel_ios.xcframework

1.2 프로젝트에 프레임워크 추가​

1. Frameworks 폴더 생성:

  • 프로젝트 루트에 Frameworks 폴더 생성
  • netfunnel-ios-agent-debug/netfunnel_ios.xcframework를 Frameworks 폴더로 복사 (개발용)

2. Xcode에서 프레임워크 등록:

  • Project ▸ General ▸ Frameworks, Libraries, and Embedded Content로 이동
  • + 클릭하고 Add Files… 선택
  • netfunnel_ios.xcframework 파일 선택
  • 프레임워크가 목록에 나타나는지 확인

3. Info.plist에 인터넷 권한 추가:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

1.3 에이전트 초기화​

NetFUNNEL 콘솔에서 초기화 코드 가져오기:

  1. Agent → Mobile Agent → iOS로 이동
  2. 실제 클라이언트 ID가 포함된 초기화 코드 복사

AppDelegate에 추가:

중요: 먼저 초기화해야 함

application(_:didFinishLaunchingWithOptions:)에서 super를 호출하기 전에 초기화하세요. 이 단계를 누락하면 = 우회 모드 (보호 없음).

import UIKit
import Netfunnel_iOS

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        Netfunnel.initialize(
            clientId: "{{CLIENT_ID}}",
            delegate: self
        )
        
        return true
    }
}
실제 코드 사용

플레이스홀더 {{CLIENT_ID}}를 NetFUNNEL 콘솔의 실제 클라이언트 ID로 교체하세요.

2단계: 제어 유형 선택​

옵션 A: 기본 제어 (5분)​

최적 사용 사례: ViewController 진입, 버튼 탭, API 호출

  1. 프로젝트에 SDK 추가 (설치 및 초기화 참조)
  2. NetFUNNEL 콘솔에서 세그먼트 생성:
    • 프로젝트 → 세그먼트 → 세그먼트 생성으로 이동
    • 기본 제어 선택
    • 진입 허용 수를 0으로 설정 (테스트용)
  3. ViewController에 이 코드 추가:
import UIKit
import Netfunnel_iOS

class ViewController: UIViewController, NetfunnelDelegate {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // 사용자가 뷰에 진입할 때 NetFUNNEL 시작
        Netfunnel.shared.nfStart(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    // MARK: - NetfunnelDelegate Methods
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 사용자가 진행할 수 있음 - 원래 로직 실행
        DispatchQueue.main.async {
            self.setupUI()
        }
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 시스템 에러 - 서비스 가용성을 위해 원래 로직 진행
        DispatchQueue.main.async {
            self.setupUI()
        }
    }
    
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 네트워크 에러 - 로깅만 수행, 네트워크 복구 모드에 의존
        print("NetFUNNEL Network error: \(message)")
    }
    
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 사용자가 차단됨 - 적절한 메시지 표시
        DispatchQueue.main.async {
            let alert = UIAlertController(title: "Access Blocked", message: message, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self.present(alert, animated: true)
        }
    }
    
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 사용자가 대기실을 닫음 - 적절히 처리
        print("NetFUNNEL User closed waiting room: \(message)")
    }
    
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        print("NetFUNNEL Continue: \(message), waitTime: \(waitTime)")
    }
    
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        print("NetFUNNEL Key returned successfully")
    }
    
    // 사용자가 떠날 때 키 반환
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        Netfunnel.shared.nfStop(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    private func setupUI() {
        // 원래 UI 설정 로직
    }
}

결과: 사용자가 ViewController에 진입할 때 대기실이 나타납니다.

옵션 B: 구간 제어 (10분)​

최적 사용 사례: 다단계 프로세스, 동시 사용자 제한 유지

  1. 프로젝트에 SDK 추가 (옵션 A와 동일)
  2. NetFUNNEL 콘솔에서 세그먼트 생성 (구간 제어 선택)
  3. 체크아웃/결제 흐름에 이 코드 추가:
import UIKit
import Netfunnel_iOS

class CheckoutViewController: UIViewController, NetfunnelDelegate {
    
    // 구간 시작 (예: 체크아웃 프로세스)
    func startCheckout() {
        Netfunnel.shared.nfStartSection(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    // MARK: - NetfunnelDelegate Methods
    
    func nfSuccess(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 사용자가 구간에 진입함
        DispatchQueue.main.async {
            self.showCheckoutForm()
        }
    }
    
    func nfError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 시스템 에러 - 서비스 가용성을 위해 원래 로직 진행
        DispatchQueue.main.async {
            self.showCheckoutForm()
        }
    }
    
    func nfNetworkError(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 네트워크 에러 - 로깅만 수행, 네트워크 복구 모드에 의존
        print("NetFUNNEL Network error: \(message)")
    }
    
    func nfBlock(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 사용자가 차단됨 - 적절한 메시지 표시
        DispatchQueue.main.async {
            let alert = UIAlertController(title: "Access Blocked", message: message, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            self.present(alert, animated: true)
        }
    }
    
    func nfClose(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        // 사용자가 대기실을 닫음 - 적절히 처리
        print("NetFUNNEL User closed waiting room: \(message)")
    }
    
    func nfContinue(projectKey: String, segmentKey: String, statusCode: Int, message: String, aheadWait: Int, behindWait: Int, waitTime: String, progressRate: Int) {
        print("NetFUNNEL Continue: \(message), waitTime: \(waitTime)")
    }
    
    func nfComplete(projectKey: String, segmentKey: String, statusCode: Int, message: String) {
        print("NetFUNNEL Section key returned successfully")
    }
    
    // 구간 종료 (예: 결제 완료 후)
    func completeCheckout() {
        // 체크아웃 완료 로직
        processPayment()
        
        // 성공적인 완료 후 키 반환
        Netfunnel.shared.nfStopSection(projectKey: "{{PROJECT_KEY}}", segmentKey: "{{SEGMENT_KEY}}")
    }
    
    private func showCheckoutForm() {
        // 체크아웃 폼 설정 로직
    }
    
    private func processPayment() {
        // 결제 처리 로직
    }
}

결과: 사용자가 체크아웃 구간에 진입하기 전에 대기열에서 대기하며, 제어된 동시성을 유지합니다.

3단계: 작동 확인​

기본 제어의 경우:​

  1. 세그먼트에서 진입 허용 수를 0으로 설정 (대기실이 나타나야 함)
  2. 대기실 표시 확인 (예상 대기 시간 표시)
  3. 진입 허용 수를 1로 설정 (즉시 진입해야 함)
  4. 로그 또는 네트워크 모니터링에서 키 반환 확인

구간 제어의 경우:​

  1. 세그먼트에서 진입 허용 수를 0으로 설정 (대기실이 나타나야 함)
  2. 대기실 표시 확인 (예상 대기 시간이 표시되지 않음)
  3. 진입 허용 수를 1로 설정 (즉시 구간에 진입해야 함)
  4. 구간을 통해 탐색 (Section1 → Section2 → End)
  5. 로그에서 키 타임아웃 연장 확인 (5003 요청 찾기)
  6. 구간이 완료되면 키 반환 확인

도움이 필요하신가요?​

  • 문제 해결: 일반적인 문제 및 해결 방법
  • iOS 로그에서 NetFUNNEL 메시지 확인 (printLog = true 활성화)
  • 프로젝트/세그먼트 키가 콘솔과 정확히 일치하는지 확인