iOS 에이전트 적용

와탭 iOS 모바일 모니터링 서비스를 사용하기 위해서는 회원 가입 후 프로젝트를 생성하고 iOS 애플리케이션에 와탭 iOS 에이전트를 적용해야 합니다.

프로젝트 생성하기

에이전트를 설치하기 전에 먼저 프로젝트를 생성하세요.

와탭 모니터링 서비스에 로그인합니다.
왼쪽 사이드 메뉴에서 전체 프로젝트 > + 프로젝트 버튼을 클릭합니다.
상품 선택 화면에서 설치할 제품을 선택합니다.
아래 항목을 입력하거나 선택합니다.
- 프로젝트 이름: 프로젝트의 이름을 입력합니다.
- 데이터 서버 지역: 데이터 서버가 위치한 리전을 선택합니다. 리전은 클라우드 서비스를 제공하는 데이터 센터의 묶음입니다. 선택한 리전에 사용자의 데이터가 저장됩니다.
- 타임 존: 알림 및 보고서 생성 시 기준이 되는 시간을 설정합니다.
- 알림 언어 설정: 경고 알림 메시지의 언어를 설정합니다. (한글, 영어 지원)
- 프로젝트 그룹: 여러 프로젝트를 그룹으로 묶어 관리할 수 있습니다. 소속될 그룹이 있으면 선택하세요.
- 프로젝트 설명: 프로젝트에 대한 추가 설명이나 세부 정보를 입력합니다.
모든 설정을 완료하면 프로젝트 생성하기 버튼을 클릭합니다.

노트

조직을 선택한 상태에서 프로젝트를 추가할 경우 조직 하위 그룹을 필수로 설정해야 합니다.

그룹에 대한 자세한 설명은 다음 문서를 참고하세요.

프로젝트 액세스 키 확인

프로젝트 액세스 키는 와탭 서비스 활성화를 위한 고유 ID입니다.

설치 안내 섹션에서 프로젝트 액세스 키 발급받기 버튼을 선택하세요. 프로젝트 액세스 키를 자동으로 발급 받은 후 다음 단계를 진행합니다.

팁

프로젝트를 생성한 다음에는 자동으로 에이전트 설치 페이지로 이동합니다. 에이전트 설치 페이지로 이동하지 않는다면 왼쪽 메뉴에서 전체 프로젝트를 선택한 다음 새로 생성한 프로젝트를 선택하세요.

설치 전 요구사항

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/1.2.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("x439k23s88411-x234p54k2k9ksch-z7j91dmvhielot")
            .setCode(3380)
            .setServerUrl("15.165.146.117")
            .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("x439k23s88411-x234p54k2k9ksch-z7j91dmvhielot")  
            .setCode(3380)
            .setServerUrl("15.165.146.117")
            .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:@"x439k23s88411-x234p54k2k9ksch-z7j91dmvhielot"];
        [builder setCode:3380];
        [builder setServerUrl:@"15.165.146.117"];
        
        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:@"x439k23s88411-x234p54k2k9ksch-z7j91dmvhielot"];
    [builder setCode:3380];
    [builder setServerUrl:@"15.165.146.117"];
    
    WhatapIOSAgent *agent = [builder build];
    [agent initialize];
    
    return YES;
}

@end

주요 설정

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

Swift

let agent = WhatapAgentBuilder()
  .setProjectKey("프로젝트키")  // 필수
  .setCode(3380)               // 필수
  .setServerUrl("15.165.146.117") // 필수
  .setSamplingRate(1.0)        // 선택 (0.0 ~ 1.0, 기본값: 1.0)
  .build()

Objective-C

WhatapAgentBuilder *builder = [[WhatapAgentBuilder alloc] init];
[builder setProjectKey:@"프로젝트키"];  // 필수
[builder setCode:3380];  // 필수
[builder setServerUrl:@"15.165.146.117"];  // 필수
[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 초기화 실패

데이터가 수집되지 않음

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

지원

다음 단계