API 레퍼런스

Sophonz 클래스의 공개 API — 수명 주기, 사용자와 세션, 로그와 크래시, 스팬, 브레드크럼, 푸시 알림, 실험과 기능 플래그, SwiftUI.

시작은 Sophonz.start(options:) 정적 메서드로 하고, 그 뒤의 모든 호출은 Sophonz.shared를 통합니다. 자동 계측으로 부족한 경우 여기 있는 메서드로 직접 기록을 남기거나 맥락을 덧붙입니다.

수명 주기

API	설명
`Sophonz.start(options:)`	SDK 시작. 정적 메서드이며 던집니다
`Sophonz.shared.stop()`	중지
`Sophonz.shared.state`	`.notInitialized` · `.started` · `.stopped`
`Sophonz.shared.isSDKEnabled`	수집 중인지
`Sophonz.shared.logLevel`	SDK 콘솔 로그 수준. 기본 `.error`
`Sophonz.sdkVersion`	SDK 버전

start는 메인 스레드에서 호출해야 하며, 아니면 SophonzSetupError.invalidThread를 던집니다.

사용자와 세션

API	설명
`deviceId`	기기 식별자
`currentUserSessionId`	현재 세션 ID
`endUserSession()`	세션을 강제로 종료
`userIdentifier`	사용자 식별자. 읽기·쓰기
`setProperty(key:value:lifespan:)`	속성 추가. `value`가 `nil`이면 제거
`removeAllProperties(lifespans:)`	속성 일괄 제거
`addPersona(_:lifespan:)` · `removePersona(_:lifespan:)`	사용자 분류 태그
`removeAllPersonas(lifespans:)`	태그 일괄 제거
`getCurrentPersonas(completion:)`	현재 태그 조회. 비동기

lifespan은 값이 얼마나 오래 남을지를 정합니다. 세션 하나에만 붙일지, 프로세스가 살아 있는 동안 유지할지, 영구 보존할지를 구분합니다.

CAUTION — 식별자 선택

userIdentifier에 넣은 값은 그대로 저장되고 대시보드에 표시됩니다. 이메일이나 실명 대신 내부 식별자를 쓰는 편이 안전합니다.

로그와 크래시

Sophonz.shared.log(
  "결제 실패",
  severity: .error,
  attributes: ["order.id": orderId]
)

API	설명
`log(_:severity:timestamp:attachment:attributes:stackTraceBehavior:)`	로그 기록
`appendCrashInfo(key:value:)`	다음 크래시 보고에 함께 남길 값
`lastRunEndState()`	직전 실행이 어떻게 끝났는지

stackTraceBehavior로 스택트레이스를 포함할지 정합니다. attachment로 파일을 함께 보낼 수 있습니다.

lastRunEndState()는 앱이 시작된 직후에 확인해, 직전 실행이 크래시로 끝났는지 판단하는 데 씁니다.

스팬

let span = Sophonz.shared.createSpan(name: "checkout", type: .performance)
defer { span?.end() }

API	설명
`createSpan(name:parentSpan:type:status:startTime:endTime:events:links:attributes:autoTerminationCode:)`	스팬 생성
`end(errorCode:endTime:)`	스팬 종료
`createStartupChildSpan(name:startTime:endTime:attributes:)`	앱 시작 트레이스에 하위 스팬 추가
`addAttributesToStartupTrace(_:)`	앱 시작 트레이스에 속성 추가

type은 기본값이 .performance이며, 계측 항목의 spz.type 값을 그대로 씁니다.

autoTerminationCode를 주면 세션이 끝날 때 열려 있던 스팬이 그 코드로 자동 종료됩니다. 끝내지 않은 스팬이 세션 경계를 넘어 남는 것을 막습니다.

브레드크럼과 세션 이벤트

API	설명
`addBreadcrumb(_:timestamp:attributes:)`	브레드크럼. 세션 타임라인에 남습니다
`addSessionEvent(name:type:timestamp:attributes:)`	세션 스팬에 이벤트 추가
`addSessionEvent(_:)`	만들어 둔 이벤트를 추가

푸시 알림

API	설명
`addPushNotificationEvent(notification:timestamp:attributes:captureData:)`	`UNNotification`으로 기록
`addPushNotificationEvent(userInfo:timestamp:attributes:captureData:)`	페이로드 딕셔너리로 기록

자동 수집을 켜지 않았거나, 알림 처리 지점을 직접 통제하고 싶을 때 씁니다. captureData의 기본값은 이 API에서는 true이며, 자동 캡처 서비스의 기본값(false)과 다릅니다.

실험과 기능 플래그

API	설명
`trackExperiment(id:variant:startedAt:)` · `untrackExperiment(id:endedAt:)`	실험 참여 기록
`trackExperiments(_:)` · `untrackExperiments(ids:endedAt:)`	여러 건을 한 번에
`trackFeatureFlag(id:variant:startedAt:)` · `untrackFeatureFlag(id:endedAt:)`	기능 플래그
`trackFeatureFlags(_:)` · `untrackFeatureFlags(ids:endedAt:)`	여러 건을 한 번에

SwiftUI

화면 계측은 뷰 컨트롤러가 나타나는 것을 보고 app.screen.name을 붙입니다. UIKit에서는 화면이 곧 뷰 컨트롤러라 그대로 맞지만, SwiftUI에서는 NavigationStack 전체가 뷰 컨트롤러 하나(UIKitNavigationController)입니다. 이름을 붙이지 않으면 앱의 모든 스팬이 그 이름 하나로 기록됩니다.

SwiftUI 화면은 스스로 이름을 밝힙니다.

struct GalleryView: View {
  var body: some View {
    List { /* ... */ }
      .sophonzScreen("Gallery")
  }
}

API	설명
`sophonzScreen(_:attributes:)`	이 뷰가 화면임을 선언합니다. 화면 이름을 설정하고 렌더 스팬도 남깁니다
`sophonzTrace(_:attributes:)`	화면의 일부인 뷰 구간을 스팬으로
`sophonzTrace(_:attributes:contentComplete:)`	`contentComplete` 값이 정해질 때까지를 로딩으로 간주
`@SophonzTrace` 매크로	같은 계측을 매크로로

스팬은 시작 시점의 화면을 기록합니다. 화면을 떠난 뒤 끝나는 요청도 시작한 화면에 남으므로, 느린 요청일수록 이 규칙이 중요합니다.

텔레메트리에서 app.screen.name이 UIKitNavigationController로 보인다면 그 화면에 sophonzScreen이 빠진 것입니다.

OpenTelemetry 확장

익스포터와 프로세서는 Sophonz.OTelOptions로 시작 시점에만 넘길 수 있습니다. 시작 이후에 추가하는 API는 없습니다.

let otel = Sophonz.OTelOptions(spanExporters: [myExporter])
try Sophonz.start(options: .withCollector(
  url: "https://in.sophonz.ai",
  appKey: "sk_…",
  otel: otel
))

NOTE — 네트워크와 WebView에는 직접 호출 API가 없습니다

두 영역은 캡처 서비스의 스위즐링으로만 수집합니다. 요청을 직접 기록하는 메서드나 WebView에 붙이는 브리지 API는 아직 없습니다. 조정은 설정의 서비스 옵션으로 합니다.