API 레퍼런스

Sophonz 오브젝트가 제공하는 공개 API — 세션과 사용자, 로그와 예외, 스팬, 트레이스 보강, OpenTelemetry 확장.

모든 공개 API는 io.sophonz.android.sophonzsdk.Sophonz 오브젝트에 있습니다. 자동 계측만으로 부족한 경우, 여기에 있는 메서드로 직접 기록을 남기거나 자동 수집된 데이터에 맥락을 덧붙입니다.

수명 주기

메서드	설명
`start(context)`	SDK 시작. `Application.onCreate()`에서 호출
`isStarted()`	시작 여부
`disable()`	SDK 중지
`getLastRunEndState()`	직전 실행이 어떻게 끝났는지 (정상 종료 · 크래시 등)
`getSdkCurrentTimeMs()`	SDK가 쓰는 시각. 기기 시계 보정이 반영된 값

메서드	설명
`setUserIdentifier(id)` · `clearUserIdentifier()`	사용자 식별자
`setUsername(name)` · `clearUsername()`	사용자 이름
`setUserEmail(email)` · `clearUserEmail()`	이메일
`addUserPersona(persona)` · `clearUserPersona(p)` · `clearAllUserPersonas()`	사용자 분류 태그
`getCurrentUserId()`	현재 사용자 식별자
`getDeviceId()`	기기 식별자

CAUTION — 식별자 선택

여기에 넣은 값은 그대로 저장되고 대시보드에 표시됩니다. 이메일이나 실명 대신 내부 식별자를 쓰는 편이 안전하며, 개인정보 처리 방침에 맞는 값인지 확인하세요.

메서드	설명
`getCurrentUserSessionId()`	현재 세션 ID
`endUserSession()`	세션을 강제로 종료
`addUserSessionProperty(key, value, scope)`	세션 속성 추가. `scope`로 세션 한정과 영구 보존을 구분
`removeUserSessionProperty(key)`	세션 속성 제거
`addUserSessionListener(l)` · `removeUserSessionListener(l)`	세션 시작·종료 알림 수신

메서드	설명
`logInfo(message)` · `logWarning(message)` · `logError(message)`	심각도별 로그
`logMessage(message, severity, properties)`	속성을 붙인 로그
`logException(throwable, severity, properties, message)`	예외 기록
`logCustomStacktrace(elements, severity, properties, message)`	스택트레이스 직접 전달
`addBreadcrumb(message)`	브레드크럼. 세션 타임라인에 남습니다
`logPushNotification(...)`	푸시 알림 수신 기록

예외 기록은 크래시와 다릅니다. 크래시는 앱을 종료시킨 처리되지 않은 예외이고, logException은 잡아서 처리한 예외를 남기는 것입니다.

메서드	설명
`startSpan(name, parent, startTimeMs, autoTerminationMode)`	스팬 시작
`createSpan(name, parent, autoTerminationMode)`	스팬 생성. 시작은 따로
`recordSpan(name, parent, attributes, events, mode) { }`	블록 실행 시간을 스팬으로
`recordCompletedSpan(name, start, end, errorCode, parent, attributes, events)`	이미 끝난 구간을 기록
`getSpan(spanId)`	진행 중인 스팬 조회

autoTerminationMode는 앱이 백그라운드로 가거나 세션이 끝날 때 열린 스팬을 어떻게 처리할지 정합니다. 끝내지 않은 스팬이 세션 경계를 넘어 남는 것을 막습니다.

Sophonz.recordSpan("checkout") {
  processPayment()
}

메서드	설명
`startView(name)` · `endView(name)`	화면 구간을 직접 지정
`activityLoaded(activity)`	Activity 로드 완료 시점 통보
`observeNavigation(activity, controller)`	Navigation 컨트롤러 연결
`addStartupTraceChildSpan(name, start, end)`	앱 시작 트레이스에 하위 스팬 추가
`addStartupTraceAttribute(key, value)`	앱 시작 트레이스에 속성 추가
`addLoadTraceChildSpan(activity, name, start, end)`	화면 로드 트레이스에 하위 스팬 추가
`addLoadTraceAttribute(activity, key, value)`	화면 로드 트레이스에 속성 추가
`applicationInitStart()` · `applicationInitEnd()`	Application 초기화 구간 표시
`appReady()`	앱이 실제로 사용 가능해진 시점

appReady()는 첫 화면이 그려진 시점과 사용자가 실제로 쓸 수 있는 시점이 다를 때 의미가 있습니다. 이 호출을 시작 트레이스의 끝으로 삼으려면 automatic_data_capture.end_startup_with_app_ready를 켜야 합니다.

메서드	설명
`recordNetworkRequest(request)`	요청을 직접 기록. 자동 계측 대상이 아닌 클라이언트용
`addHttpRequestInfoModifier(m)` · `removeHttpRequestInfoModifier(m)`	기록 직전에 요청 정보를 수정
`generateW3cTraceparent()`	`traceparent` 값 생성. 직접 헤더를 붙일 때 사용

메서드	설명
`trackExperiment(name, variant, ttl)` · `untrackExperiment(name, ttl)`	실험 참여 기록
`trackFeatureFlag(name, ttl)` · `untrackFeatureFlag(name, ttl)`	기능 플래그 기록
`createExperiment(...)` · `createFeatureFlag(...)`	추적 객체 생성
`trackExperiments(list)` · `trackFeatureFlags(list)`	여러 건을 한 번에

기록된 값은 세션에 붙어, 특정 변형을 받은 사용자만 골라 성능이나 에러율을 비교할 수 있게 합니다.

메서드	설명
`getOpenTelemetryKotlin()`	SDK가 쓰는 OpenTelemetry 인스턴스
`addSpanExporter(exporter)` · `addSpanProcessor(processor)`	스팬 파이프라인 확장
`addLogRecordExporter(exporter)` · `addLogRecordProcessor(processor)`	로그 파이프라인 확장
`setResourceAttribute(key, value)`	리소스 속성 추가

CAUTION — 등록 순서

익스포터와 프로세서는 start()보다 먼저 등록해야 합니다. 시작 이후에 추가한 것은 파이프라인에 반영되지 않습니다.

이 경로로 Sophonz 외의 OTLP 백엔드에 같은 데이터를 함께 보낼 수 있습니다. 계측은 OpenTelemetry 시맨틱 컨벤션을 따르므로 다른 백엔드에서도 그대로 해석됩니다.