iOS 에이전트 적용

설치 전 요구사항

iOS 에이전트를 설치하기 전에 다음 요구사항을 확인하세요.

iOS 14.0 이상
Xcode 14.0 이상
Swift 5.0 이상 또는 Objective-C

에이전트 설치

에이전트는 두 가지 방식으로 설치할 수 있습니다.

Swift Package Manager를 이용한 자동 설치 방식
XCFramework을 이용한 수동 설치 방식

Swift Package Manager 자동 설치

Xcode에서 프로젝트를 열고 File → Add Package Dependencies를 선택합니다.
패키지 URL을 입력합니다.

https://github.com/whatap/WhatapIOSAgent-Release
버전 선택 후 Add Package를 클릭합니다.

XCFramework 수동 설치

XCFramework을 다운로드합니다.

curl -O https://repo.whatap-mobile-agent.io/uploads/2.1.0/WhatapAgent.xcframework.zip
unzip WhatapAgent.xcframework.zip

Xcode 프로젝트에 추가:
- 프로젝트 타겟 선택 → General 탭
- Frameworks, Libraries, and Embedded Content 섹션
- + 버튼 → Add Other → Add Files
- WhatapAgent.xcframework 선택
- Embed & Sign 확인
- Objective-C 프로젝트는 Bridging Header 설정 필요

Agent 초기화

Whatap iOS SDK는 앱의 성능 데이터를 수집하기 위해 앱 시작 시점에 초기화되어야 합니다. SDK 초기화는 앱이 시작될 때 가장 먼저 실행되어야 하며, 이를 통해 앱의 전체 생명주기 동안 발생하는 이벤트를 추적할 수 있습니다.

노트

중요: 초기화 시점

iOS에서 가장 빠른 초기화 시점은 main() 함수나 +load 메서드입니다. Swift 환경과의 호환성 및 안정성을 고려하여 다음 시점을 권장합니다:

SwiftUI: @main struct의 init() - 앱 구조체가 생성되는 시점
UIKit: application:willFinishLaunchingWithOptions: - didFinishLaunching보다 먼저 호출됨
Objective-C: +load 메서드 또는 application:willFinishLaunchingWithOptions:

초기화 시점이 늦어지면 앱 시작 초기의 중요한 성능 데이터(pre-main time, 초기 메모리 사용량 등)를 놓칠 수 있습니다.

Swift

SwiftUI 앱에서는 @main struct의 init()에서 SDK를 초기화합니다.

import SwiftUI
import WhatapAgent

@main
struct MyApp: App {
    init() {
        // 시작 시 SDK 초기화
        let agent = WhatapAgentBuilder()
            .setProjectKey("<YOUR_PROJECT_ACCESS_KEY>")
            .setPCode(<YOUR_PCODE>)
            .setServerUrl("<YOUR_SERVER_URL>")
            .build()
        
        agent.initialize()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

UIKit 기반 앱에서는 AppDelegate의 application:willFinishLaunchingWithOptions:에서 SDK를 초기화하는 것을 권장합니다.

import UIKit
import WhatapAgent

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, 
                    willFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // 가장 빠른 시점에 SDK 초기화 (권장)
        let agent = WhatapAgentBuilder()
            .setProjectKey("<YOUR_PROJECT_ACCESS_KEY>")
            .setServerUrl("<YOUR_SERVER_URL>")
            .setPCode(<YOUR_PCODE>)
            .build()
        
        agent.initialize()
        
        return true
    }
}

Objective-C

방법 1: +load 메서드 사용 (가장 빠름)

AppDelegate.m

#import "AppDelegate.h"
@import WhatapAgent;

@implementation AppDelegate

+ (void)load {
    // 클래스가 메모리에 로드되는 시점 (main() 이전)
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        WhatapAgentBuilder *builder = [[WhatapAgentBuilder alloc] init];
        [builder setProjectKey:@"<YOUR_PROJECT_ACCESS_KEY>"];
        [builder setServerUrl:@"<YOUR_SERVER_URL>"];
        [builder setPCode:<YOUR_PCODE>];
        
        WhatapIOSAgent *agent = [builder build];
        [agent initialize];
    });
}

@end

+load 메서드는 앱이 실행되기 전에 호출되므로 복잡한 작업은 피해야 합니다. SDK 초기화만 수행하세요.

방법 2: willFinishLaunchingWithOptions 사용 (권장)

AppDelegate.m

#import "AppDelegate.h"
@import WhatapAgent;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application 
    willFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // didFinishLaunching보다 먼저 실행되는 SDK 초기화
    WhatapAgentBuilder *builder = [[WhatapAgentBuilder alloc] init];
    [builder setProjectKey:@"<YOUR_PROJECT_ACCESS_KEY>"];
    [builder setServerUrl:@"<YOUR_SERVER_URL>"];
    [builder setPCode:<YOUR_PCODE>];
    
    WhatapIOSAgent *agent = [builder build];
    [agent initialize];
    
    return YES;
}
@end

주요 설정

1. 와탭 서비스 설정 (프로젝트키, 코드, 서버주소)

Swift

let agent = WhatapAgentBuilder()
  .setProjectKey("<YOUR_PROJECT_ACCESS_KEY>")  // 필수
  .setServerUrl("<YOUR_SERVER_URL>") // 필수
  .setPCode(<YOUR_PCODE>)               // 필수
  .setSamplingRate(1.0)        // 선택 (0.0 ~ 1.0, 기본값: 1.0)
  .build()

Objective-C

WhatapAgentBuilder *builder = [[WhatapAgentBuilder alloc] init];
[builder setProjectKey:@"<YOUR_PROJECT_ACCESS_KEY>"];  // 필수
[builder setServerUrl:@"<YOUR_SERVER_URL>"];  // 필수
[builder setPCode:<YOUR_PCODE>];  // 필수
[builder setSamplingRate:1.0];  // 선택 (0.0 ~ 1.0, 기본값: 1.0)
WhatapIOSAgent *agent = [builder build];

2. 화면 추적 설정

화면 추적은 사용자가 앱 내에서 어떤 화면을 방문하고, 각 화면에서 얼마나 머무르는지를 모니터링하는 기능입니다.

팁

화면 추적의 이점

사용자의 화면 이동 경로(Screen Flow) 추적
화면별 체류 시간 자동 계산
화면 로딩/렌더링 시간 등 성능 지표 수집
가장 많이 방문한 화면 분석

SwiftUI

struct ContentView: View {
    var body: some View {
        Text("Hello")
            .onAppear {
                WhatapIOSAgent.trackScreen("ContentView")
            }
    }
}

UIKit

class ViewController: UIViewController {
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        WhatapIOSAgent.trackScreen("ViewController")
    }
}

Objective-C

@implementation ViewController

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [WhatapIOSAgent trackScreen:@"ViewController"];
}

@end

3. 네트워크 모니터링

네트워크 요청은 자동으로 추적됩니다.
URLSession을 사용하는 경우 별도 설정이 필요하지 않습니다.

4. 크래시 리포팅

크래시는 자동으로 수집됩니다.
비활성화하려면 다음과 같이 설정합니다.

Swift

WhatapAgentBuilder()
  .setCrashReportingEnabled(false)
  .build()

Objective-C

WhatapAgentBuilder *builder = [[WhatapAgentBuilder alloc] init];
[builder setCrashReportingEnabled:NO];
[builder build];

5. ChainView 설정

ChainView는 사용자 행동을 체인으로 연결해 전체 플로우를 추적하는 기능입니다.

Swift

// ChainView 시작 (로그인 플로우 예시)
let chainId = WhatapIOSAgent.startChainView("LoginFlow")

// 단계별 이벤트 추가
WhatapIOSAgent.addChainViewEvent(chainId, event: "EmailInput")
WhatapIOSAgent.addChainViewEvent(chainId, event: "PasswordInput")
WhatapIOSAgent.addChainViewEvent(chainId, event: "LoginButtonClick")
WhatapIOSAgent.addChainViewEvent(chainId, event: "AuthenticationSuccess")

// 종료
WhatapIOSAgent.endChainView(chainId)

// 간단한 사용 예시
WhatapIOSAgent.setChainView("UserAction", value: "AddToCart")
WhatapIOSAgent.setChainView("UserAction", value: "Checkout")

Objective-C

// ChainView 시작 (로그인 플로우 예시)
NSString *chainId = [WhatapIOSAgent startChainView:@"LoginFlow"];

// 단계별 이벤트 추가
[WhatapIOSAgent addChainViewEvent:chainId event:@"EmailInput"];
[WhatapIOSAgent addChainViewEvent:chainId event:@"PasswordInput"];
[WhatapIOSAgent addChainViewEvent:chainId event:@"LoginButtonClick"];
[WhatapIOSAgent addChainViewEvent:chainId event:@"AuthenticationSuccess"];

// 종료
[WhatapIOSAgent endChainView:chainId];

// 간단한 사용 예시
[WhatapIOSAgent setChainView:@"UserAction" value:@"AddToCart"];
[WhatapIOSAgent setChainView:@"UserAction" value:@"Checkout"];

6. Extra 설정

앱의 추가 정보를 설정하여 더 상세한 분석이 가능합니다.

Swift

WhatapIOSAgent.setUserId("user123")
WhatapIOSAgent.setExtra("membership", value: "premium")
WhatapIOSAgent.setExtra("region", value: "seoul")
WhatapIOSAgent.setExtra("version", value: "2.1.0")

Objective-C

[WhatapIOSAgent setUserId:@"user123"];
[WhatapIOSAgent setExtra:@"membership" value:@"premium"];
[WhatapIOSAgent setExtra:@"region" value:@"seoul"];
[WhatapIOSAgent setExtra:@"version" value:@"2.1.0"];

7. 네트워크 보안 설정

iOS 14 이상에서는 네트워크 정책에 따라 Info.plist에 추가 설정이 필요할 수 있습니다.

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>whatap-mobile-agent.io</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

노트

ATS(App Transport Security) 설정

iOS 9부터 도입된 ATS는 네트워크 통신을 보호하기 위한 기능입니다.
와탭 에이전트는 HTTPS를 사용하지만, 특정 환경에서는 예외 설정이 필요할 수 있습니다.
프로덕션 환경에서는 반드시 필요한 도메인만 예외 처리하는 것을 권장합니다.

문제 해결 및 지원

문제 해결

SDK 초기화 실패

SDK 초기화가 실패하는 경우 다음 사항을 확인하세요.

프로젝트 키와 PCode 확인: 올바른 값이 설정되었는지 확인합니다.
네트워크 연결 상태 확인: 디바이스가 인터넷에 연결되어 있는지 확인합니다.
서버 URL이 올바른지 확인: 제공받은 수집 서버 주소가 정확한지 확인합니다.

데이터가 수집되지 않음

모니터링 데이터가 대시보드에 표시되지 않는 경우 다음 사항을 확인하세요.

샘플링 비율 확인: setSamplingRate(1.0)으로 100% 수집되도록 설정되어 있는지 확인합니다.
Info.plist의 네트워크 권한 확인: App Transport Security 설정이 올바른지 확인합니다.

크래시 리포트가 전송되지 않음

크래시 데이터가 수집되지 않는 경우 다음 사항을 확인하세요.

앱을 재시작해야 이전 크래시가 전송됨: 크래시 발생 후 앱이 다시 실행될 때 이전 크래시 정보가 전송됩니다.
시뮬레이터에서는 일부 크래시가 캡처되지 않을 수 있음: 실제 디바이스에서 테스트하는 것을 권장합니다.

지원

문제가 발생하면 다음 채널로 문의하세요.

이메일: support@whatap.io
기술 문서: https://docs.whatap.io

기술 지원 요청 시 다음 정보를 함께 제공하면 더 빠른 해결이 가능합니다:

프로젝트 키
iOS 버전
Xcode 버전
SDK 버전
에러 메시지 또는 로그
문제 재현 방법

다음 단계

모니터링 시작하기

와탭 서비스 페이지로 이동해 모바일 모니터링을 시작하세요. 앞서 생성한 프로젝트를 선택한 다음 대시보드 > Mobile Dashboard 메뉴로 이동하세요.

설치 전 요구사항​

에이전트 설치​

Swift Package Manager 자동 설치​

XCFramework 수동 설치​

Agent 초기화​

Swift​

Objective-C​

주요 설정​

1. 와탭 서비스 설정 (프로젝트키, 코드, 서버주소)​

2. 화면 추적 설정​

3. 네트워크 모니터링​

4. 크래시 리포팅​

5. ChainView 설정​

6. Extra 설정​

7. 네트워크 보안 설정​

문제 해결 및 지원​

문제 해결​

SDK 초기화 실패​

데이터가 수집되지 않음​

크래시 리포트가 전송되지 않음​

지원​

다음 단계​

설치 전 요구사항

에이전트 설치

Swift Package Manager 자동 설치

XCFramework 수동 설치

Agent 초기화

Swift

Objective-C

주요 설정

1. 와탭 서비스 설정 (프로젝트키, 코드, 서버주소)

2. 화면 추적 설정

3. 네트워크 모니터링

4. 크래시 리포팅

5. ChainView 설정

6. Extra 설정

7. 네트워크 보안 설정

문제 해결 및 지원

문제 해결

SDK 초기화 실패

데이터가 수집되지 않음

크래시 리포트가 전송되지 않음

지원

다음 단계