설정

플랫폼별 앱 아이덴티티, 컬렉터 URL과 앱 키의 위치, iOS가 이를 결정하는 순서, initialize와 sdkConfig, sophonz-config.json, Expo 설정 플러그인의 모든 옵션을 설명합니다.

아이덴티티

기기가 보내는 모든 배치에는 컬렉터가 어느 앱의 데이터인지 알 수 있게 하는 리소스 속성이 붙습니다.

포털에서 플랫폼마다 별도의 앱으로 등록하고 각자의 sk_ 키를 받습니다. 두 플랫폼이 키 하나를 같이 쓰지 마세요.

AppName은 조인 키입니다

포털은 service.name으로 텔레메트리와 등록된 앱을 연결합니다. iOS에서는 기본값이 번들 식별자이므로, 앱을 다른 이름으로 등록했다면 appName을 지정하세요. 나중에 이 값을 바꾸면 앱이 포털 항목에서 떨어져 나갑니다. 컬렉터는 계속 데이터를 받지만 앱 페이지가 비어서 전송이 멈춘 것처럼 보입니다.

Android: sophonz-config.json

Gradle 플러그인이 이 파일을 앱에 컴파일해 넣습니다. 런타임에는 값을 바꿀 수 없고, JavaScript의 sdkConfig에는 Android 항목이 없습니다.

{
  "sdk_config": {
    "app_framework": "react_native",
    "ingest": {
      "collector_url": "https://in.sophonz.ai",
      "service_key": "sk_android_replace_me",
      "service_namespace": "my-project",
      "deployment_environment": "production"
    }
  }
}

service_key와 collector_url은 빌드 시점의 SOPHONZ_SERVICE_KEY, SOPHONZ_COLLECTOR_URL 환경 변수로도 지정할 수 있으므로 키를 커밋하지 않아도 됩니다. 둘 다 있으면 파일의 값이 우선합니다.

React Native 앱에서 특히 중요한 키

나머지 옵션은 네이티브 앱과 같으며 Android 설정에 정리되어 있습니다. 파서가 모르는 키가 있으면 빌드가 실패합니다.

iOS: 아이덴티티를 정하는 순서

JavaScript가 SDK를 시작할 때 네이티브 모듈은 다음 중 먼저 사용할 수 있는 것을 고릅니다.

1. sdkConfig.ios.collectorUrl 와 sdkConfig.ios.appKey
2. 앱 번들 안의 Sophonz-Info.plist(최소한 CollectorURL과 AppKey가 있을 것)
3. @sophonz/react-native-otlp의 OTLP 익스포터만(Sophonz 컬렉터 없음)
4. 아무것도 없음: 시작이 실패하고 initialize는 false로 resolve됩니다

모든 단계에서 빈 문자열은 없는 것으로 취급합니다. SDK를 네이티브에서 시작하면 이 순서는 적용되지 않고, SophonzInitializer.swift에 적은 옵션이 그대로 쓰입니다.

JavaScript에서

import {initialize} from "@sophonz/react-native";
 
await initialize({
  sdkConfig: {
    ios: {
      collectorUrl: "https://in.sophonz.ai",
      appKey: "sk_ios_replace_me",
      appName: "my-ios-app",
      project: "my-project",
      deploymentEnvironment: "production",
      disabledUrlPatterns: ["analytics.example.com"],
    },
    trackUnhandledRejections: true,
  },
  logLevel: "warn",
});

Sophonz-Info.plist에서

앱의 Info.plist 옆에 정확히 Sophonz-Info.plist라는 이름으로 파일을 만들고, Copy Bundle Resources에 포함되도록 앱 타깃에 추가한 뒤, sdkConfig에서는 collectorUrl과 appKey를 빼세요.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CollectorURL</key>
  <string>https://in.sophonz.ai</string>
  <key>AppKey</key>
  <string>sk_ios_replace_me</string>
  <key>AppName</key>
  <string>my-ios-app</string>
  <key>Project</key>
  <string>my-project</string>
  <key>DeploymentEnvironment</key>
  <string>production</string>
</dict>
</plist>

이렇게 하면 키가 JavaScript 번들에 들어가지 않고, ios 블록 없는 initialize 호출 하나로 두 플랫폼을 처리할 수 있습니다.

네이티브 코드에서

Expo 플러그인과 설치 마법사가 만드는 SophonzInitializer.swift는 Sophonz.start(options:)를 호출합니다. iOS 설정에 나오는 캡처 서비스 옵션, traceparent 허용 목록, 행 감지, 크래시 리포터 선택은 모두 여기서만 설정할 수 있습니다. 옵션에는 platform: .reactNative를 유지하세요.

initialize

initialize({sdkConfig?, patch?, logLevel?}): Promise<boolean>

useSophonz(sdkConfig, patch?, logLevel?)는 같은 값을 순서대로 받습니다.

sdkConfig 레퍼런스

SDKConfig 타입에는 logLevel 필드도 선언되어 있지만 initialize는 이 값을 읽지 않습니다. logLevel은 sdkConfig 옆에 넘기세요.

네이티브 시작 후에도 적용되는 것

MainApplication이나 SophonzInitializer가 SDK를 이미 시작했다면 initialize는 자체 시작을 건너뜁니다. 이때 ios 옵션과 exporters는 경고 없이 무시됩니다. 다음은 여전히 적용됩니다.

• trackUnhandledRejections
• patch
• 전역 JS 에러 핸들러, React Native와 SDK 버전
• iOS 릴리스 빌드의 JS 번들 식별자

시작 설정은 네이티브 코드에 두세요. Android는 sophonz-config.json, iOS는 Sophonz.Options나 Sophonz-Info.plist입니다.

익스포터 필드

요약만 적습니다. 자세한 설명은 OpenTelemetry와 OTLP에 있습니다.

Tracer provider 옵션

useSophonzNativeTracerProvider(config?, enabled?)와 new SophonzNativeTracerProvider(config?)는 다음 옵션을 받습니다.

{}를 넘기면 전역 컨텍스트 매니저가 꺼집니다. OpenTelemetry와 OTLP를 참고하세요.

Expo 설정 플러그인

androidAppKey나 iOSAppKey가 없거나 iOSUseSPM이 boolean이 아니면 prebuild가 실패합니다. 그 밖에 플러그인이 만나는 문제는 경고로만 보고되고 prebuild는 계속됩니다.

{
  "expo": {
    "plugins": [
      [
        "@sophonz/react-native",
        {
          "androidAppKey": "sk_android_replace_me",
          "iOSAppKey": "sk_ios_replace_me",
          "androidSDKConfig": {
            "networking": {
              "enable_traceparent_injection": true,
              "traceparent_only_allow_domains": ["api.example.com"]
            }
          }
        }
      ]
    ]
  }
}

플러그인이 두 플랫폼 모두에서 SDK를 네이티브로 시작하므로, 플러그인을 쓰는 Expo 앱에서 initialize에 넘긴 sdkConfig는 무시됩니다. 속성으로 제공되지 않는 iOS 수집 옵션은 생성된 SophonzInitializer.swift를 직접 고쳐야 하며, 이후 prebuild는 --clean 없이는 이 파일을 건드리지 않습니다.

iOS에서 Swift Package Manager 사용

기본값은 CocoaPods입니다. Apple SDK를 SPM에서 가져오려면(React Native 0.75 이상, 동적 프레임워크) 다음처럼 설치합니다.

cd ios
SOPHONZ_USE_SPM=1 USE_FRAMEWORKS=dynamic pod install

Expo에서는 iOSUseSPM: true를 지정하세요. 플러그인이 Podfile 맨 위에 ENV['SOPHONZ_USE_SPM'] ||= '1'을 넣으므로 셸 환경에 따라 결과가 달라지지 않습니다.

Podfile의 sophonz_post_install(installer) 훅은 SophonzIO 패키지를 앱 타깃에 추가해 임베드와 서명이 되게 합니다. 이 훅이 없으면 Release 빌드가 실행 즉시 Library not loaded로 크래시합니다. 어느 쪽을 쓰든 훅은 Podfile에 남겨 두세요. SOPHONZ_USE_SPM이 없으면 이전 SPM 설치가 추가한 항목을 제거합니다.

SDK 에러 로깅

모든 API 호출은 reject하지 않고 기본값으로 resolve됩니다. 개발 중에 호출이 왜 실패했는지 보려면 다음을 설정합니다.

import {configureSDKErrorLogging} from "@sophonz/react-native";
 
configureSDKErrorLogging({
  enabled: __DEV__,
  allowLogToConsole: true,
  customHandler: (method, error) => {
    // 자체 진단 도구로 전달
  },
});