API 레퍼런스
React Native 패키지의 모든 export — 시작, 훅, 로그와 에러, 세션, 사용자, 네트워크 기록, 번들 ID, 타입, tracer provider, 내비게이션, Redux, OTLP — 의 시그니처와 기본값, Android와 iOS의 동작 차이를 설명합니다.
따로 패키지를 적지 않은 API는 모두 @sophonz/react-native에서 import합니다. 네이티브 SDK를 호출하는 모든 API는 reject하지 않는 Promise를 돌려줍니다. 네이티브 쪽이 실패하면 false, 빈 문자열, "INVALID" 같은 기본값으로 resolve되므로 계측 코드가 앱을 멈추게 할 일은 없습니다. 호출이 왜 기본값으로 끝났는지 보려면 SDK 에러 로깅을 켜세요.
시작
initialize
initialize(args?: {
sdkConfig?: SDKConfig;
patch?: string;
logLevel?: SophonzLoggerLevel;
}): Promise<boolean>네이티브 SDK가 실행 중이 아니면 시작하고 전역 에러 핸들러를 설치합니다. SDK가 실행 중이고 핸들러가 설치되면 true로 resolve됩니다.
네이티브 모듈이 링크되지 않았을 때, 시작이 실패했을 때(iOS: 컬렉터와 키, plist, 익스포터가 모두 없음), exporters 설정이 잘못됐을 때, ErrorUtils를 쓸 수 없을 때는 false로 resolve됩니다. 한 번만 호출하세요. 옵션은 설정에 있습니다.
NOTE — 시작 후 initialize가 하는 일
React Native 버전과 패키지 버전을 기록하고, patch가 있으면 설정하고, ErrorUtils로 전역 핸들러를 설치해 처리되지 않은 JS 예외를 로그로 남긴 뒤 원래 핸들러에 넘깁니다. trackUnhandledRejections를 켜면 처리되지 않은 Promise 거부도 기록합니다. iOS 릴리스 빌드에서는 main.jsbundle의 식별자도 계산합니다. 이 모든 일은 SDK를 네이티브에서 시작했을 때도 일어나며, 시작 옵션만 건너뜁니다.
훅
| API | 반환값 | 설명 |
|---|---|---|
useSophonz(sdkConfig, patch?, logLevel?) | {isPending, isStarted} | effect 안에서 initialize를 호출합니다. 시작 전에 인자의 참조가 바뀌면 다시 실행되므로 sdkConfig는 고정된 객체로 두세요 |
useSophonzIsStarted() | boolean | null | 네이티브 SDK 실행 여부. 첫 응답 전에는 null |
useOrientationListener(enabled = true) | void | 시작 방향과, 세로와 가로 사이의 변경마다 브레드크럼을 남깁니다 |
SDK 에러 로깅
| API | 설명 |
|---|---|
configureSDKErrorLogging(config: Partial<SDKErrorLoggingConfig>) | 현재 설정에 병합합니다. {enabled, allowLogToConsole, customHandler(methodName, error)}, 기본값은 모두 꺼짐 |
getSDKErrorLoggingConfig() | 현재 설정의 복사본 |
로그와 에러
| API | 반환값 | 설명 |
|---|---|---|
logInfo(message) | Promise<boolean> | INFO 로그. 스택 트레이스는 붙지 않습니다 |
logWarning(message, includeStacktrace = true) | Promise<boolean> | WARN 로그 |
logError(message, includeStacktrace = true) | Promise<boolean> | ERROR 로그 |
logMessage(message, severity = "error", properties = {}, includeStacktrace = true) | Promise<boolean> | 속성을 붙인 로그. severity는 "info", "warning", "error" |
logHandledError(error, properties = {}) | Promise<boolean> | 잡은 Error를 JS 스택, spz.exception_handling: handled와 함께 ERROR 로그로 남깁니다. instanceof Error가 아니면 false로 resolve됩니다 |
logIfComponentError(error) | Promise<boolean> | 에러의 React componentStack을 ERROR 로그로 남깁니다. 없으면 false로 resolve됩니다 |
addBreadcrumb(message) | Promise<boolean> | 현재 세션에 브레드크럼 이벤트를 남깁니다. 로그보다 가볍습니다 |
import {logHandledError, logMessage} from "@sophonz/react-native";
try {
await checkout(cart);
} catch (e) {
logHandledError(e as Error, {cart_size: String(cart.length)});
}
logMessage("payment retried", "warning", {provider: "card"});- 속성 값은 문자열이어야 합니다. iOS에서는 문자열이 아닌 값이 하나라도 있으면 호출 전체가
false로 resolve되고 아무것도 기록되지 않습니다. Android는 다른 타입을 변환합니다. - 호출 위치에서 잡은 스택 트레이스는
spz.stacktrace.rn속성으로 전송됩니다.includeStacktrace가 켜져 있는데 JS 스택이 없으면 iOS는 대신 네이티브 스택을 붙입니다. handleGlobalError와handleError도 export되어 있습니다.initialize가 설치하는 부품이며 직접 호출하는 용도가 아닙니다.
세션
| API | 반환값 | 설명 |
|---|---|---|
getCurrentSessionId() | Promise<string> | 현재 세션 ID. 소문자 16진수 32자로, session.id로 전송되는 문자열과 같습니다. 실패하면 "" |
endSession() | Promise<boolean> | 현재 세션을 끝내고 새 세션을 시작합니다 |
addSessionProperty(key, value, permanent) | Promise<boolean> | 세션 속성. permanent: true면 제거할 때까지 이후 세션에도 유지됩니다 |
removeSessionProperty(key) | Promise<boolean> | 어떤 수명으로 추가했든 제거합니다 |
getLastRunEndState() | Promise<SessionStatus> | 이전 실행이 어떻게 끝났는지: "CRASH" 또는 "CLEAN_EXIT". SDK가 시작되지 않았으면 "INVALID" |
getDeviceId() | Promise<string> | SDK의 기기 식별자. 실패하면 "" |
getLastRunEndState는 다음 콜드 스타트까지 바뀌지 않으므로, 언제 읽어도 "앱이 예기치 않게 종료되었습니다" 같은 안내를 띄우는 데 쓸 수 있습니다.
AppState 리스너 안에서는 세션이 이미 끝나는 중일 수 있어, getCurrentSessionId가 닫히는 세션의 ID를 돌려줄 수 있습니다.
사용자
| API | 반환값 | 설명 |
|---|---|---|
setUserIdentifier(id), clearUserIdentifier() | Promise<boolean> | 사용자 식별자. 이후 세션에도 유지됩니다 |
addUserPersona(persona), clearUserPersona(persona), clearAllUserPersonas() | Promise<boolean> | 분류 태그. iOS에서는 현재 세션 동안 유지됩니다 |
setUsername(name), clearUsername() | Promise<boolean> | 사용자 이름 — Android만. iOS는 false로 resolve |
setUserEmail(email), clearUserEmail() | Promise<boolean> | 이메일 주소 — Android만. iOS는 false로 resolve |
로그아웃할 때 clearUserIdentifier를 호출하세요.
CAUTION — 식별자 고르기
값은 넘긴 그대로 저장됩니다. 이메일 주소나 실명보다 내부 식별자가 안전합니다. 보내는 값이 개인정보 처리 방침에 맞는지 확인하세요.
네트워크
fetch와 XMLHttpRequest로 보낸 요청은 네이티브에서 수집됩니다. SDK가 볼 수 없는 것만 수동으로 기록하세요. 네트워크를 참고하세요.
| API | 반환값 | 설명 |
|---|---|---|
recordNetworkRequest(url, httpMethod, startInMillis, endInMillis, bytesSent?, bytesReceived?, statusCode?) | Promise<boolean> | 완료된 요청. 0이나 생략한 숫자는 알 수 없는 값으로 기록됩니다 |
logNetworkClientError(url, httpMethod, startInMillis, endInMillis, errorType, errorMessage) | Promise<boolean> | HTTP 응답을 받지 못한 요청 |
httpMethod는 MethodType입니다. GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, CONNECT, TRACE, PURGE, LINK, UNLINK를 대소문자 구분 없이 받습니다. 시간은 epoch 밀리초입니다.
스팬에는 iOS에서는 ios.disableNetworkSpanForwarding을 켜지 않는 한, Android에서는 networking.enable_network_span_forwarding을 켰을 때만 spz.w3c_traceparent가 붙습니다.
번들 식별
| API | 반환값 | 설명 |
|---|---|---|
setJavaScriptPatch(patch) | Promise<boolean> | OTA 업데이트용 패치 식별자를 기록합니다. initialize({patch})가 이 함수를 호출합니다 |
setJavaScriptBundlePath(path) | Promise<boolean> | 실행 중인 JS 번들을 내용으로 식별합니다. iOS는 파일을 MD5로 해시해 react_native_bundle_id로 기록하며, iOS 릴리스 빌드에서는 main.jsbundle에 대해 자동으로 호출됩니다 |
OTA 업데이트로 다른 경로의 번들을 불러온 뒤에는 setJavaScriptBundlePath를 직접 호출하세요.
타입
| 타입 | 정의 |
|---|---|
SDKConfig | {ios?: IOSConfig; exporters?: OTLPExporterConfig; trackUnhandledRejections?: boolean; logLevel?: SophonzLoggerLevel}. 여기의 logLevel은 읽지 않습니다 |
IOSConfig | {collectorUrl?, appKey?, appName?, project?, deploymentEnvironment?: string; disableCrashReporter?, disableAutomaticViewCapture?, disableNetworkSpanForwarding?: boolean; disabledUrlPatterns?: string[]} |
AndroidConfig | {} — Android는 빌드 시점에 설정합니다 |
OTLPExporterConfig | {logExporter?: ExporterConfig; traceExporter?: ExporterConfig} |
ExporterConfig | {endpoint: string; headers?: {key: string; token: string}[]; timeout?: number} |
LogProperties | {[key: string]: string} |
LogSeverity | "info" | "warning" | "error" |
SessionStatus | "INVALID" | "CRASH" | "CLEAN_EXIT" |
SophonzLoggerLevel | "info" | "warn" | "error" |
MethodType | 네트워크에 나열한 HTTP 메서드 |
ComponentError | Error & React.ErrorInfo |
SDKErrorLoggingConfig | {enabled: boolean; allowLogToConsole: boolean; customHandler?: (methodName: string, error: Error) => void} |
트레이싱 — @sophonz/react-native-tracer-provider
가이드: OpenTelemetry와 OTLP.
| API | 설명 |
|---|---|
useSophonzNativeTracerProvider(config?, enabled = true) | enabled가 true이고 SDK가 실행 중이면 provider를 만듭니다. {tracerProvider, tracer, isLoading, isError, error}를 돌려줍니다 |
new SophonzNativeTracerProvider(config?) | 훅 없이 만드는 provider. SDK 실행 여부를 확인하지 않습니다 |
provider.getTracer(name, version?, {schemaUrl?}?) | SophonzNativeTracer. iOS에서는 schemaUrl을 무시합니다 |
tracer.startSpan(name, options?, context?), tracer.startActiveSpan(...) | 표준 OpenTelemetry 시그니처 |
(span as SophonzNativeSpan).spanContextAsync() | 네이티브 쪽이 ID를 정하면 resolve되는 Promise<SpanContext> |
startView(tracer, name) | 화면 뷰 형태의 스팬 |
recordCompletedSpan(tracer, name, options?) | 이벤트, 상태, 부모를 지정해 스팬을 한 번에 시작하고 끝냅니다. 옵션 타입은 CompletedSpanOptions |
asParent(span) | span이 부모가 되는 컨텍스트 |
endAsFailed(span) | ERROR 상태로 설정하고 끝냅니다 |
| 설정 타입 | 필드 |
|---|---|
SophonzNativeTracerProviderConfig | spanContextSyncBehaviour?: "return_empty" | "throw", setGlobalContextManager?: boolean |
SophonzNativeTracerProviderReturn | {isLoading, isError: boolean; error: string; tracerProvider: TracerProvider | null; tracer: Tracer | null} |
내비게이션 — @sophonz/react-native-navigation
가이드: 내비게이션.
| API | 설명 |
|---|---|
SophonzNavigationTracker | expo-router와 React Navigation용. 속성: ref, tracerProvider?, screenAttributes?, tracerOptions?, debug?(기본값 true), children |
SophonzNativeNavigationTracker | react-native-navigation용. Navigation.events()를 담은 ref를 받으며 속성은 같습니다 |
Redux — @sophonz/react-native-redux
가이드: Redux.
| API | 설명 |
|---|---|
useSophonzMiddleware(tracerProvider?) | provider가 생기면 {middleware}를 돌려줍니다 |
createSophonzMiddleware(tracerProvider) | 훅 없이 만드는 미들웨어 |
디스패치된 액션은 액션 타입, 결과, 페이로드 크기가 담긴 sys.rn_action 타입의 action 스팬이 됩니다.
OTLP — @sophonz/react-native-otlp
sdkConfig.exporters로 설정합니다. 추가 OTLP 익스포터를 참고하세요. 패키지는 코어 패키지가 시작할 때 호출하는 initialize(exporterConfig)와 설정 타입을 export합니다. 직접 호출할 일은 없습니다.
플랫폼 차이
| 동작 | Android | iOS |
|---|---|---|
setUsername, setUserEmail과 각 clear* | 기록됨 | false로 resolve. Apple SDK에 해당 필드가 없음 |
| SDK 시작 전의 호출 | SDK로 전달 | 기본값으로 resolve |
문자열이 아닌 logMessage 속성 | 변환 | 호출이 false로 resolve |
| 페르소나 | Android SDK의 범위를 따름 | 현재 세션 동안 유지 |
| React Native 버전, JS 패치, 번들 식별자 | 리소스 속성 | 프로세스 수명 속성 |
| 처리되지 않은 JS 예외 | React Native 크래시 타입의 로그 | exception.type, exception.message, JS 스택이 붙은 ERROR 로그 |
수동 기록 요청의 spz.w3c_traceparent | enable_network_span_forwarding을 켰을 때 | disableNetworkSpanForwarding을 켜지 않았을 때 |
| tracer provider의 스팬 kind | 유지 | 무시. 모든 스팬이 internal |
span.updateName | 적용 | 무시 |
| tracer 이름, 버전, 스키마 URL | 기록 | 기록 안 됨 |
| 배열 속성 값 | 유지 | 문자열로 기록 |
| 스팬 링크 | SDK로 전달 | SDK로 전달 |
iOS 항목은 React Native 모듈이 쓸 수 있는 Apple SDK 공개 API의 한계에서 비롯됩니다. 대시보드에서 차이가 문제가 되면 client.platform으로 거르세요.