API 및 설정

Sophonz iOS SDK의 Options 클래스, 주요 API, 그리고 초기화 예제를 설명합니다.

API 소개 및 설정

Options 클래스

SDK 초기화 시 사용하는 설정 옵션 클래스입니다. 각 파라미터의 역할은 아래와 같습니다.

@objc(SophonzOptions) public final class Options: NSObject {
 
    /// 앱 키 (Sophonz 콘솔에서 발급)
    public let appKey: String
 
    /// 데이터를 전송할 Collector 주소
    public let endpoints: Sophonz.Endpoints?
 
    /// 데이터 수집 비율 (0.0 ~ 1.0)
    /// 0.0: 수집 안 함 / 1.0: 100% 수집 (기본값: 1.0)
    public var sampleRate: Double
 
    /// 기기 ID(UUID)를 Collector로 전송할지 여부
    /// 기기 ID는 UUID를 생성하여 Keychain에 저장한 값입니다.
    public var isDeviceIdEnable: Bool
 
    /// 서비스 공간 식별자 (콘솔에서 확인)
    public var project: String?
 
    /// API 응답값으로 SDK 수집 여부를 제어합니다.
    public var sdkCollectControl: Sophonz.SDKCollectControl?
 
    /// 사용자 터치(클릭) 자동 수집 여부
    public var tapOption: Sophonz.TapOption?
 
    /// HTTP 요청의 Header 및 Body 수집 여부
    /// 설정하지 않으면 XHR은 수집하되 Header와 Body는 수집하지 않습니다.
    public var xhrOption: Sophonz.XHROption?
 
    /// WebView 세션 데이터 출처 설정
    /// true: Native가 전송한 데이터 사용 (기본값)
    /// false: WebView 자체에서 생성한 데이터 사용
    /// ※ Native 앱에서는 별도 설정이 필요 없습니다.
    public var webviewOption: Sophonz.WebviewOption?
 
    /// 배포 환경 구분
    /// 운영 환경과 테스트 환경이 동일 서버를 사용하는 경우에만 설정합니다.
    public var deployEnvironment: SophonzDeployEnvironment
}

파라미터 요약표

파라미터	타입	설명
`appKey`	`String`	앱 키 (필수)
`endpoints`	`Sophonz.Endpoints?`	Collector 주소
`project`	`String?`	서비스 공간 식별자
`sampleRate`	`Double`	수집 비율 (0.0~1.0, 기본값 1.0)
`isDeviceIdEnable`	`Bool`	기기 UUID 전송 여부
`deployEnvironment`	`SophonzDeployEnvironment`	운영/테스트 환경 구분
`sdkCollectControl`	`SDKCollectControl?`	API 응답으로 수집 제어
`tapOption`	`TapOption?`	터치 이벤트 자동 수집 → TapOption 상세
`xhrOption`	`XHROption?`	HTTP Header/Body 수집 → XHROption 상세
`webviewOption`	`WebviewOption?`	WebView 세션 연결 방식 → WebviewOption 상세

TapOption 상세

Sophonz.TapOption은 사용자의 탭(클릭) 이벤트 수집 방식을 설정하는 옵션 클래스입니다.

초기화

let tapOption = Sophonz.TapOption(
    isAutoCapture:             Bool,
    isAutoCaputrueButtonTitle: Bool,
    isAutoCaputrueButtonId:    Bool
)

파라미터 설명

파라미터	타입	기본값	설명
`isAutoCapture`	`Bool`	`false`	탭 이벤트 자동 수집 활성화 여부
`isAutoCaptureButtonTitle`	`Bool`	`true`	버튼의 Title 텍스트 수집 여부
`isAutoCaptureButtonId`	`Bool`	`true`	버튼의 ID 수집 여부

isAutoCapture가 false인 경우, 나머지 옵션 값과 무관하게 탭 이벤트가 수집되지 않습니다.

특정 버튼 수집 제외

button.sophonz_ignore = true

사용 예시

// 자동 수집 활성화, Title 수집 활성화, ID 수집 활성화
let tapOption = Sophonz.TapOption(
    isAutoCapture:             true,
    isAutoCaputrueButtonTitle: true,
    isAutoCaputrueButtonId:    true
)

XHROption 상세

Sophonz.XHROption은 앱 내 HTTP 요청의 Header 및 Body 수집 여부를 제어하는 옵션 클래스입니다.

초기화

let xhrOption = Sophonz.XHROption(
    isCaptureHttpRequestHeader: Bool,
    isCaptureHttpRequestBody:   Bool
)

파라미터 설명

파라미터	타입	기본값	설명
`isCaptureHttpRequestHeader`	`Bool`	`false`	HTTP 요청의 Header 수집 여부
`isCaptureHttpRequestBody`	`Bool`	`false`	HTTP 요청의 Body 수집 여부

XHROption을 설정하지 않으면 XHR 요청 자체는 수집되지만, Header와 Body는 수집되지 않습니다.

Body 수집 시 민감한 개인정보(비밀번호, 토큰 등)가 포함될 수 있으므로, 수집 대상 API를 사전에 검토하고 적용하세요.

사용 예시

// Header, Body 모두 수집
let xhrOption = Sophonz.XHROption(
    isCaptureHttpRequestHeader: true,
    isCaptureHttpRequestBody:   true
)
 
// Header만 수집
let xhrOption = Sophonz.XHROption(
    isCaptureHttpRequestHeader: true,
    isCaptureHttpRequestBody:   false
)

WebviewOption 상세

Sophonz.WebviewOption은 하이브리드 앱에서 Native 세션과 WebView 세션의 연결 방식을 제어하는 옵션 클래스입니다.

초기화

let webOption = Sophonz.WebviewOption(
    isSharedSession: Bool,
    isNeedWebAgent:  Bool
)

파라미터 설명

파라미터	타입	기본값	설명
`isSharedSession`	`Bool`	`true`	Native 세션과 WebView 세션을 통합할지 여부
`isNeedWebAgent`	`Bool`	`true`	SDK가 WebView에 WebAgent 스크립트를 자동 주입할지 여부

isSharedSession: true로 설정하면 Native와 WebView의 사용자 행동이 하나의 세션으로 통합되어 추적됩니다.

isNeedWebAgent: false는 WebAgent 스크립트가 이미 별도로 로드된 경우 중복 주입을 방지하기 위해 사용합니다. 순수 Native 앱에서는 별도 설정이 필요 없습니다.

사용 예시

// 하이브리드 앱 — 세션 통합, WebAgent 자동 주입
let webOption = Sophonz.WebviewOption(
    isSharedSession: true,
    isNeedWebAgent:  true
)
 
// WebAgent를 별도로 로드하는 경우 — 중복 주입 방지
let webOption = Sophonz.WebviewOption(
    isSharedSession: true,
    isNeedWebAgent:  false
)

주요 API

extension Sophonz {
 
    /// SDK 초기화
    @discardableResult
    @objc public static func setup(options: Sophonz.Options,
                                   isDebug: Bool = false) -> Sophonz?
 
    /// SDK 시작
    @objc public func start()
 
    /// 사용자 ID 설정
    @objc public static func setUserId(id: String?)
 
    /// 현재 설정된 사용자 ID 반환
    @objc public static func getUserId() -> String?
 
    /// 커스텀 로그 전송
    @objc public static func customLog(level: Sophonz.LogLevel, message: String)
 
    /// Span에 커스텀 속성 추가
    /// SDK start() 이전에 설정하면 이후 생성되는 모든 Span에 자동 포함됩니다.
    @objc public static func setAttribute(key: String, value: String?)
 
    /// Keychain에 저장된 기기 UUID 반환
    @objc public static func getDeviceId() -> String
 
    /// xib 방식으로 WebView를 초기화한 경우, 스크립트를 수동으로 주입합니다.
    @objc public static func setWebviewConfiguration(
        userContentController: WKUserContentController)
}

API 요약표

API	설명
`Sophonz.setup(options:isDebug:)`	SDK 초기화
`.start()`	SDK 시작
`Sophonz.setUserId(id:)`	사용자 ID 설정
`Sophonz.getUserId()`	사용자 ID 조회
`Sophonz.customLog(level:message:)`	커스텀 로그 전송
`Sophonz.setAttribute(key:value:)`	Span에 커스텀 속성 추가
`Sophonz.getDeviceId()`	기기 UUID 조회
`Sophonz.setWebviewConfiguration(userContentController:)`	xib WebView 스크립트 수동 주입

SDK 초기화 예제

Swift 프로젝트 — 기본 예시

AppDelegate의 didFinishLaunchingWithOptions에서 아래와 같이 초기화합니다.

import UIKit
import SophonzCore
 
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
 
    var window: UIWindow?
 
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        setupSophonzSDK()
        return true
    }
 
    func setupSophonzSDK() {
        let endpoint   = Sophonz.Endpoints(collectorURL: "https://in.v0.sophonz.com")
        let appKey = "서비스 키"
 
        // SDK 수집 여부를 API 응답으로 제어
        let sdkControl = Sophonz.SDKCollectControl(remoteCollectionControlEnable: true)
 
        // HTTP 요청 Header, Body 수집
        let xhrOption  = Sophonz.XHROption(
            isCaptureHttpRequestHeader: true,
            isCaptureHttpRequestBody:   true)
 
        // Native 세션 공유 (기본값: true)
        let webOption  = Sophonz.WebviewOption(isSharedSession: true)
 
        // 터치 자동 수집, Title 활성화, ID 활성화
        let tapOption  = Sophonz.TapOption(
            isAutoCapture:             true,
            isAutoCaputrueButtonTitle: true,
            isAutoCaputrueButtonId:    true)
 
        let option = Sophonz.Options(
            project:           "namespace",
            appKey:            appKey,
            endpoints:         endpoint,
            deployEnvironment: .production,
            sampleRate:        1.0,
            isDeviceIdEnable:  true,
            sdkCollectControl: sdkControl,
            tapOption:         tapOption,
            xhrOption:         xhrOption,
            webviewOption:     webOption)
 
        // isDebug: true → 콘솔 로그 출력 활성화
        Sophonz.setup(options: option, isDebug: true)?.start()
    }
}

Swift 프로젝트 — 실전 예시

실제 프로젝트에서는 Collector URL, 서비스 키, 네임스페이스를 별도의 매니저 클래스로 관리하는 것을 권장합니다.

func setupSophonzSDK() {
    // Collector URL: 사용자가 선택한 IP를 우선 사용하고, 없으면 기본값으로 폴백
    let endpoint = Sophonz.Endpoints(
        collectorURL: "https://in.v0.sophonz.com"
    )
 
    // API 응답으로 SDK 수집 여부 원격 제어
    let sdkControl = Sophonz.SDKCollectControl(
        remoteCollectionControlEnable: true
    )
 
    // HTTP 요청의 Header 및 Body 수집 활성화
    let xhrOption = Sophonz.XHROption(
        isCaptureHttpRequestHeader: true,
        isCaptureHttpRequestBody:   true
    )
 
    // Native 세션 공유, WebAgent 스크립트 중복 주입 방지
    let webOption = Sophonz.WebviewOption(
        isSharedSession: true,
        isNeedWebAgent:  false
    )
 
    // 탭 이벤트 자동 수집 (Title 수집 활성화, ID 수집 활성화)
    let tapOption = Sophonz.TapOption(
        isAutoCapture:             true,
        isAutoCaputrueButtonTitle: true,
        isAutoCaputrueButtonId:    true
    )
 
    let option = Sophonz.Options(
        project:           "namespace",
        appKey:            appKey,
        endpoints:         endpoint,
        deployEnvironment: .development,
        sampleRate:        1,
        isDeviceIdEnable:  true,
        sdkCollectControl: sdkControl,
        tapOption:         tapOption,
        xhrOption:         xhrOption,
        webviewOption:     webOption
    )
 
    // isDebug: true → 콘솔 로그 출력 활성화
    Sophonz.setup(options: option, isDebug: true)?.start()
}

Objective-C 프로젝트

AppDelegate의 didFinishLaunchingWithOptions에서 아래와 같이 초기화합니다.

#import "AppDelegate.h"
#import <SophonzCore/SophonzCore-Swift.h>
 
@implementation AppDelegate
 
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [self setupSophonzSDK];
    return YES;
}
 
- (void)setupSophonzSDK {
    SophonzEndpoints *endpoint =
        [[SophonzEndpoints alloc] initWithCollectorURL:@"https://in.v0.sophonz.com"];
    NSString *appKey = @"서비스 키";
 
    SophonzSDKCollectControl *sdkControl =
        [[SophonzSDKCollectControl alloc] initWithRemoteCollectionControlEnable:YES];
 
    SophonzXHROption *xhrOption =
        [[SophonzXHROption alloc] initWithIsCaptureHttpRequestHeader:YES
                               isCaptureHttpRequestBody:YES];
 
    SophonzWebviewOption *webOption =
        [[SophonzWebviewOption alloc] initWithIsSharedSession:YES];
 
    SophonzTapOption *tapOption =
        [[SophonzTapOption alloc] initWithIsAutoCapture:YES];
 
    SophonzOptions *option = [[SophonzOptions alloc]
        initWithProject:           @"namespace"
        appKey:                    appKey
        endpoints:                 endpoint
        deployEnvironment:         SophonzDeployEnvironmentProduction
        sampleRate:                1.0
        isDeviceIdEnable:          YES
        sdkCollectControl:         sdkControl
        tapOption:                 tapOption
        xhrOption:                 xhrOption
        webviewOption:             webOption];
 
    [[Sophonz setupWithOptions:option isDebug:YES] start];
}
 
@end