iOS Agent 통합 가이드

iOS Agent를 실제 서비스에 통합하기 위한 단계별 가이드입니다.

---

1. 에이전트 소개

EUM(End-User Monitoring) iOS 에이전트는 사용자 경험을 모니터링하고 분석하기 위한 도구입니다. 이 에이전트를 통해 사용자는 End-User의 다양한 활동을 추적하고, 성능 데이터를 수집할 수 있습니다. 특히 End-User의 트래픽이 집중되는 지점을 식별하여 사용자가 NetFUNNEL의 가상 대기실을 효과적으로 적용할 수 있도록 지원함으로써, 트래픽 과부하를 방지하고 안정적인 서비스 제공할 수 있습니다.

1.1 최소 요구 사항

• iOS: 9.0 이상
• Xcode: 12.0 이상
• Swift: 5.0 이상

1.2 지원 빌드 환경

Debug 빌드:

• ios-arm64: 실제 iOS 디바이스(ARM64 아키텍처)에서 디버깅할 때 사용하는 빌드

• ios-arm64_x86_64-simulator: iOS 시뮬레이터(ARM64/x86_64 아키텍처)에서 디버깅할 때 사용하는 빌드

• eum_ios.xcframework: 디버깅을 위해 실제 디바이스와 시뮬레이터 모두에서 사용 가능한 통합 빌드

Release 빌드:

• ios-arm64: iOS 디바이스(ARM64 아키텍처)에서 릴리스(배포)할 때 사용하는 빌드

• ios-arm64_x86_64-simulator: iOS 시뮬레이터(ARM64/x86_64 아키텍처)에 최적화된 릴리스 빌드

• eum_ios.xcframework: 배포를 위해 실제 디바이스와 시뮬레이터 모두에서 사용 가능한 통합 빌드

---

2. 에이전트 설치

info

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

2.1 에이전트 다운로드

에이전트 파일을 다운로드합니다.

Download

2.2 Framework 파일 추가

프로젝트의 Build Settings에서 Framework Search Paths에 @executable_path/Frameworks와 같이 Netfunnel_iOS.framework 파일이 위치한 경로를 추가합니다.

project_root/
├── YourProject.xcodeproj
├── YourProject/
│   └── Frameworks/
│       └── eum_ios.framework
└── ...

2.3 라이브러리 Import

에이전트를 사용하려면 프로젝트의 소스 파일에서 import 문을 통해 라이브러리를 import 해야 합니다.

1. Xcode 프로젝트에서 왼쪽의 Project Navigator에서 프로젝트를 선택합니다.
2. General 탭에서 Frameworks, Libraries, and Embedded Content 섹션을 찾습니다.
3. + 버튼을 눌러 eum_ios.framework 파일을 추가합니다.
4. Embed & Sign 옵션을 선택하여 실행 시 파일이 포함되도록 설정합니다.

warning

Framework Search Paths에 @executable_path/Frameworks 경로가 포함되어 있는지 확인하세요.

---

3. 에이전트 초기화

EUM 기능을 사용하기 전, 앱의 최초 액티비티(화면) 또는 Application 클래스에 initialize 함수를 호출하여 EUM을 초기화하세요.

note

AppDelegate의 application(_:didFinishLaunchingWithOptions:)에서 초기화하면 앱 시작과 함께 정확한 모니터링이 가능합니다.

3.1 초기화 함수 호출

Swift

AppDelegate.swift

import UIKit
import eum_ios

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // EUM Initialization
        EUM.shared.initialize(
            serverURL: "undefined",
            clientId: "{TENANT_ID}",
            settingURL: "undefined",
            trackResource: true,
            printLog: false
        )
        
        return true
    }
}

Objective-C

AppDelegate.m

#import "AppDelegate.h"
#import "eum_ios/eum_ios.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // EUM Initialization
    EUM *eumAgent = [EUM shared];
    [eumAgent initializeWithServerURL:@"undefined"
                             clientId:@"{TENANT_ID}"
                           settingURL:@"undefined"
                        trackResource:@true
                             printLog:@false];
    
    return YES;
}

@end

3.2 초기화 파라미터 상세

파라미터	타입	설명	필수	기본값
serverURL	String	EUM 서버 주소	O	-
clientId	String	EUM 클라이언트 ID	O	-
settingURL	String	EUM 설정 파일 주소	O	-
trackResource	NSNumber?	EUM 리소스 이벤트 추적 유무	X	true
printLog	NSNumber?	EUM 디버그를 위한 로그 출력 유무	X	false

3.3 초기화 확인

초기화 성공

초기화에 성공했을 경우, 아래와 같은 로그를 확인할 수 있습니다.

[EUM] [INI] EUM is on. Console displays EUM.
[EUM] [INI] Initialization success.
[EUM] [INI] Result(isSuccess: true, version: "{EUM_VERSION}")

초기화 실패

초기화 함수 호출 이후, 네트워크 에러 등으로 인해 EUM의 설정 파일을 가져오는 데에 실패했을 경우에는 아래와 같은 로그를 확인할 수 있습니다.

[EUM] [INI] Initialization failed.
[EUM] [INI] Result(isSuccess: false, version: "{EUM_VERSION}")

---

4. 추가 기능

4.1 버전 확인

에이전트 버전을 확인하려면 다음 함수를 사용합니다:

Swift

let version = EUM.getVersion()
print("EUM Agent version: (version)")

Objective-C

NSString *version = [EUM getVersion];
NSLog(@"EUM Agent version: %@", version);

함수	파라미터	반환 값	설명
getVersion	N/A	String	EUM 에이전트 버전을 반환(확인)하는 함수

---

FAQ

Q: 초기화 실패 시 어떻게 해야 하나요?

A: 다음 사항을 확인하세요:

1. 네트워크 연결 상태 확인
2. 서버 URL과 설정 URL이 올바른지 확인
3. 클라이언트 ID가 유효한지 확인
4. Framework가 올바르게 프로젝트에 추가되었는지 확인

Q: 특정 이벤트만 수집하고 싶어요

A: trackResource 파라미터를 false로 설정하면 리소스 이벤트 수집을 비활성화할 수 있습니다. 세션 이벤트와 화면 이벤트는 기본적으로 수집됩니다.

Q: 프로덕션 환경에서 로그를 끄려면?

A: 초기화 시 printLog: false로 설정하거나 빌드 구성에 따라 조건부로 설정하세요:

Swift

EUM.shared.initialize(
    serverURL: "undefined",
    clientId: "{TENANT_ID}",
    settingURL: "undefined",
    trackResource: true,
    printLog: false
)

Objective-C

[EUM.shared initializeWithServerURL:@"undefined"
                            clientId:@"{TENANT_ID}"
                          settingURL:@"undefined"
                       trackResource:@true
                            printLog:@false];

Q: XCFramework vs Framework 중 어떤 것을 사용해야 하나요?

A: iOS 에이전트는 두 가지 빌드 형식을 제공합니다:

• XCFramework: 실제 디바이스와 시뮬레이터 모두를 지원하는 통합 패키지로, 대부분의 경우 권장됩니다.

• 개별 Framework: 특정 환경(디바이스 또는 시뮬레이터)에서만 사용하는 경우 선택할 수 있습니다.

---