설정

Sophonz Browser SDK의 초기화 옵션 전체 레퍼런스와, 서버에서 계측을 활성화·비활성화하는 원격 설정을 설명합니다.

SophonzSDK.init()에 전달할 수 있는 모든 옵션과, 서버에서 계측을 동적으로 제어하는 원격 설정 기능을 설명합니다.

설정 (Options)

원격 설정

Sophonz Browser SDK는 서버와 통신하여 앱의 계측 상태를 동적으로 관리할 수 있습니다. 이 기능을 통해 서버 측에서 계측을 활성화하거나 비활성화할 수 있으며, Exporter 실패 시 자동으로 계측을 중단하는 기능을 제공합니다.

원격 설정 API

Sophonz Browser SDK는 초기화 시 원격 설정 API (/control/status)를 호출하여 원격 설정 상태를 확인합니다.

동작 방식

1. 초기화 시 상태 확인: init() 호출 시 이전에 저장된 isCollecting 상태를 확인합니다.
2. 계측 비활성화: 저장된 isCollecting이 false인 경우 계측이 비활성화됩니다.
3. 백그라운드 업데이트: 원격 설정 API를 백그라운드에서 호출하여 최신 상태를 localStorage에 저장합니다.
4. 다음 세션 적용: 서버에서 isCollecting: false를 반환하면 다음 init() 호출 시 계측이 비활성화됩니다.

서버 응답 형식

interface AgentControlResponse {
  /** 계측 수집 활성화 여부 - false인 경우 다음 init 시 계측 비활성화 */
  isCollecting: boolean;
  /** 자동 중단 활성화 여부 */
  autoStop: boolean;
  /** 자동 중단 실패 임계값 - exporter가 이 횟수 이상 실패하면 계측 중단 */
  autoStopThreshold: number;
  /** 서버에서 발급한 토큰 */
  token: string;
}

자동 중단 (Exporter 실패 시)

Exporter가 연속으로 실패하면 계측을 자동으로 중단합니다.

수집기에 닿지 못하는 상태에서 계속 전송을 시도하면, 어차피 저장되지 않을 요청이 사용자 브라우저와 서버 양쪽에 계속 쌓입니다. 자동 중단은 그 시점에 SDK를 멈춰 불필요한 트래픽을 만들지 않도록 하는 장치입니다. 수집기 장애나 점검처럼 다수의 클라이언트가 동시에 실패하는 상황에서, 복구 중인 서버에 재시도가 몰리는 것을 막아 줍니다.

동작 방식

1. 실패 추적: ExporterFailureTracker가 Exporter의 성공/실패를 추적합니다.
2. 임계값 도달: 연속 실패 횟수가 autoStopThreshold에 도달하면 자동으로 deinit()이 호출됩니다.
3. 실패 카운터 리셋: 실패 카운터는 init() 호출 시에만 리셋됩니다. 성공해도 리셋되지 않습니다.

Exporter 이벤트

Sophonz는 CustomEvent를 통해 Exporter의 성공/실패를 알립니다.

// Exporter 이벤트 리스닝 예시
window.addEventListener('sophonz:exporter', (event) => {
  const { type } = event.detail; // 'success' | 'failure'
  console.log(`Exporter ${type}`);
});

리소스 속성

SDK가 내보내는 모든 Span, 로그 레코드, 메트릭은 동일한 리소스를 가집니다. init() 옵션에서 가져온 앱 식별 정보와 함께 다음 속성이 포함됩니다.

UA Client Hints 속성 세 가지는 navigator.userAgentData에서 읽는데, Safari와 Firefox는 이 API를 지원하지 않습니다. 해당 브라우저에서는 빈 값이 아니라 속성 자체가 붙지 않으며, user_agent.original은 어디서나 사용할 수 있습니다. 동기적으로 읽을 수 있는 low-entropy 값만 사용하므로 네트워크 요청이나 대기가 발생하지 않습니다.

전송 재시도

전송에 실패한 배치는 자동으로 재시도합니다. init()에서 설정할 수 있는 옵션은 없습니다.

• HTTP 429, 502, 503, 504와 네트워크 오류·타임아웃에서 재시도합니다. 400, 401, 403, 404 등 그 밖의 상태 코드는 재시도하지 않습니다. 잘못된 요청이나 인증 실패는 다시 보내도 성공하지 않기 때문입니다.
• 최초 전송 이후 최대 5회 재시도합니다. 대기 시간은 1000ms에서 시작해 매번 1.5배로 늘어나며 5000ms에서 상한에 걸리고, ±20%의 지터가 적용됩니다. 전체 시도의 총 예산은 30000ms입니다.
• 응답에 Retry-After 헤더가 있으면 초 단위와 HTTP-date 형식 모두 존중합니다.
• 페이지가 숨겨진 상태에서는 재시도를 예약하지도, 실행하지도 않습니다. 숨겨진 탭은 언로드 중일 수 있어 지연된 요청이 무의미하거나 언로드를 방해하기 때문입니다.
• XHR과 fetch 경로에 적용됩니다. navigator.sendBeacon은 제외됩니다. 요청이 큐에 들어갔는지만 알려주는 fire-and-forget 방식이라 재시도할 근거가 없기 때문입니다.

대기는 타이머로 처리하며 메인 스레드를 막지 않습니다.

옵션 상세 설명

collectorUrl

(string, 선택)

텔레메트리 데이터를 전송할 콜렉터의 URL을 지정합니다. 기본값은 https://in.sophonz.ai입니다.

// ✅ 올바른 형식
collectorUrl: 'https://collector.yourdomain.com'
collectorUrl: 'http://192.168.1.100:4318'
 
// ❌ 잘못된 형식 (초기화 실패)
collectorUrl: 'collector.yourdomain.com'
collectorUrl: '//collector.yourdomain.com'

authorizationToken

(string, 선택)

콜렉터에 인증할 때 사용할 토큰을 설정합니다. 보안이 필요한 경우 사용합니다.

project

(string, 선택)

프로젝트를 설정합니다. 여러 앱(Android, iOS, Web 등)을 묶어서 모니터링할 경우 필요합니다. 비어있는 경우 service.namespace를 보내지 않습니다.

appName

(string, 선택)

Sophonz에서 관리하는 앱의 이름을 지정합니다. 앱 등록할 때의 패키지명이며, 이 값은 앱을 구분짓는 값으로 텔레메트리 데이터 저장 및 분석에 사용됩니다. appName은 앱 등록 시 입력한 패키지명과 동일해야 하며 패키지 이름에는 a-z, A-Z, 0-9, -, _, .만 입력할 수 있습니다.

appKey

(string, 선택)

Sophonz에서 발급된 앱 키를 설정합니다. Sophonz 콘솔에 로그인해 프로젝트에서 앱 추가로 앱을 등록하고, 앱 관리에서 발급된 앱 키를 확인해 설치하세요.

appVersion

(string, 선택)

앱 버전을 지정합니다. 이 값은 앱 버전을 구분짓는 값으로 텔레메트리 데이터 저장 및 분석에 사용됩니다.

웹 콘텐츠 버전 (web.version)

webVersion이라는 옵션은 없습니다. 웹 콘텐츠의 버전은 appVersion으로 넘긴 값에서 SDK가 알아서 만들어 web.version 리소스 속성으로 내보냅니다.

동작 방식:

• 웹뷰 환경: 옵션으로 전달한 appVersion 값이 web.version으로 남고, appVersion에는 네이티브 SDK가 전달한 버전이 들어갑니다. 두 버전이 갈라지는 건 이 경우뿐입니다.
• 일반 웹 환경: web.version과 appVersion이 같은 값입니다.

// 웹뷰 환경 예시: 네이티브 앱 버전 1.0.0, 웹 콘텐츠 버전 2.3.1
SophonzSDK.init({
  appVersion: '2.3.1', // 웹뷰에서는 web.version으로 남음
  // appVersion은 네이티브 SDK에서 전달한 1.0.0이 사용됨
});

deploymentEnvironment

(string, 선택)

배포 환경을 설정합니다. 예를 들어, production, staging 등으로 설정하여 환경별로 데이터를 구분할 수 있습니다.

defaultAttributes

(Attributes, 선택)

모든 Span에 추가되는 전역 속성을 설정합니다. 사용자 정의 속성을 추가하여 텔레메트리 데이터를 보강할 수 있습니다.

samplingProbability

(number | string, 선택)

샘플링 확률을 설정합니다. 0에서 1 사이의 값으로 지정하며, 기본값은 1로 모든 트랜잭션을 샘플링합니다.

advancedNetworkCapture

(boolean, 선택)

네트워크 요청 및 응답의 상세한 추적을 활성화합니다. 기본값은 false이며, 활성화 시 네트워크 관련 데이터를 더 상세히 수집할 수 있습니다.

수집 내용과 설정 인터페이스는 계측 › fetch에서 다룹니다.

blockClass

(string, 선택)

세션 리플레이에서 가려야 할 요소의 CSS 클래스를 지정합니다. 민감한 정보가 포함된 요소를 가릴 때 사용합니다.

consoleCapture

(boolean, 선택)

콘솔 로그를 캡처할지 여부를 설정합니다. 기본값은 false이며, 활성화 시 콘솔에서 발생하는 로그도 텔레메트리 데이터로 수집됩니다.

캡처된 호출 하나는 OpenTelemetry 이벤트 이름 browser.console을 가진 로그 레코드가 되며, 호출된 콘솔 메서드를 담은 browser.console.method 속성이 함께 기록됩니다.

수집 내용과 설정 인터페이스는 계측 › console에서 다룹니다.

debug

(boolean, 선택)

디버깅 모드를 활성화합니다. 기본값은 false이며, 활성화 시 추가적인 로그가 출력되어 문제 해결에 도움이 됩니다.

disableIntercom

(boolean, 선택)

Intercom과의 연동을 비활성화합니다. 기본값은 false이며, 활성화 시 Intercom과의 통합 기능이 비활성화됩니다.

disableReplay

(boolean, 선택)

세션 리플레이 기능을 비활성화합니다. 기본값은 true이며, 비활성화 시 사용자 세션의 리플레이 기능이 동작합니다. 이 기능은 현재 개발 중이며 추후에 활성화될 예정입니다.

sessionStorage

(StorageType, 선택)

type StorageType = 'cookie' | 'localStorage';

세션ID 저장소의 타입을 설정합니다. 기본값은 cookie이며, localStorage로 변경할 수 있습니다. 이 설정은 세션 데이터의 저장 방식을 결정합니다. 일반적으로 cookie를 사용하며, 브라우저 쿠키를 사용할 수 없는 하이브리드 앱의 웹뷰의 경우 localStorage를 사용합니다.

webview.settings.domStorageEnabled = true

let config = WKWebViewConfiguration()
config.websiteDataStore = WKWebsiteDataStore.default()
let webView = WKWebView(frame: .zero, configuration: config)

사용 방법:

SophonzSDK.init({
  collectorUrl: 'https://in.sophonz.ai',
  appName: '{{YOUR_APP_NAME}}',
  appVersion: '{{YOUR_APP_VERSION}}',
  appKey: '{{YOUR_APP_KEY}}',
  sessionStorage: 'localStorage' // or 'cookie'
});

ignoreClass

(string, 선택)

세션 리플레이에서 무시할 요소의 CSS 클래스를 지정합니다. 특정 요소를 기록하지 않으려는 경우 사용합니다.

ignoreUrls

(Array<string | RegExp>, 선택)

추적하지 않을 URL 패턴을 지정합니다. 정규식이나 문자열 배열로 설정할 수 있으며, 부분 일치하거나 정확히 일치하는 URL은 텔레메트리 데이터에 포함되지 않습니다.

maskAllInputs

(boolean, 선택)

모든 입력 요소를 마스킹합니다. 기본값은 true이며, 활성화 시 모든 입력 필드의 값이 마스킹되어 저장됩니다. 민감한 정보가 포함된 경우 사용합니다.

maskAllText

(boolean, 선택)

모든 텍스트를 마스킹합니다. 기본값은 false이며, 활성화 시 모든 텍스트가 마스킹되어 저장됩니다. 민감한 정보가 포함된 경우 사용합니다.

maskClass

(string, 선택)

텍스트 마스킹에 사용할 CSS 클래스를 지정합니다. 이 클래스를 가진 요소의 텍스트는 마스킹되어 저장됩니다. 민감한 정보가 포함된 경우 사용합니다.

recordCanvas

(boolean, 선택)

캔버스 요소 기록 여부를 설정합니다. 기본값은 false이며, 활성화 시 캔버스 요소의 내용이 기록됩니다.

sampling

(number, 선택)

세션 레코더 샘플링 설정을 지정합니다. 기본값은 1이며, 0에서 1 사이의 값을 설정할 수 있습니다. 이 값은 세션 레코더가 얼마나 많은 세션을 기록할지를 결정합니다.

tracePropagationTargets

(Array<string | RegExp>, 선택)

Trace Header를 전파할 대상 도메인 또는 정규식 목록을 지정합니다. 이 목록에 포함된 도메인으로 요청이 발생할 경우 Trace Header가 자동으로 전파됩니다. 정규식이나 문자열 배열로 설정할 수 있습니다.

수집 내용과 설정 인터페이스는 계측 › fetch에서 다룹니다.

webVitals

(boolean, 선택)

Web Vitals 계측을 활성화합니다. 기본값은 true이며, false로 설정하면 Core Web Vitals를 수집하지 않습니다.

수집하는 지표는 lcp, inp, cls, fcp, ttfb이며 각각 페이지 로드당 한 번만 보고됩니다. FID는 INP로 대체된 지표라 수집하지 않습니다.

보고된 지표 하나는 세 가지 형태로 전송됩니다. browser.web_vital 이벤트, app.span.type = "webvitals"를 갖는 0초 Span, 그리고 webvitals 히스토그램 메트릭입니다.

websocket

(boolean, 선택)

WebSocket 계측을 활성화합니다. 기본값은 false이며, 활성화 시 WebSocket 연결 이벤트가 자동으로 계측됩니다. 이 기능은 실시간 데이터 전송을 모니터링하는 데 유용합니다.

수집 내용과 설정 인터페이스는 계측 › websocket에서 다룹니다.

socketio

(boolean, 선택)

Socket.IO 계측을 활성화합니다. 기본값은 false이며, 활성화 시 Socket.IO 클라이언트의 이벤트가 자동으로 계측됩니다. 이 기능은 실시간 통신을 모니터링하는 데 유용합니다.

수집 내용과 설정 인터페이스는 계측 › socketio에서 다룹니다.

captureMetrics

(boolean, 선택)

메트릭 수집을 위해 예약된 옵션입니다. 기본값은 false입니다.

disablePreflight

(boolean, 선택)

• preflight 요청 비활성화 여부를 설정합니다. 기본값은 false이며, 활성화 시 preflight 요청이 비활성화됩니다. preflight는 CORS 요청을 위한 OPTIONS 요청입니다. 보안상 필요한 경우 사용합니다.
• 이 설정은 exporterProtocol이 proto로 설정된 경우 자동으로 true로 설정됩니다. 이는 proto 프로토콜이 preflight 요청을 필요로 하지 않기 때문입니다.
• 이 설정을 true로 설정한 경우 Sophonz 수집기 혹은 프록시에서 이 콘텐츠 타입을 허용해야 합니다.

exporterProtocol

(json | proto, 선택)

exporter 프로토콜을 설정합니다. 기본값은 json이며, proto로 설정할 경우 protobuf 프로토콜을 사용하여 데이터를 전송합니다.

• 기본값은 json이며 json 프로토콜은 JSON 콘텐트 형식(application/json)으로 데이터를 전송하며, Beacon API를 통해 전송합니다.
• proto로 설정할 경우 protobuf 프로토콜을 사용하여 프로토 형식(application/x-protobuf)로 데이터를 전송하며, Fetch API를 통해 전송합니다. proto를 설정하면 disablePreflight 옵션이 자동으로 true로 설정됩니다.

screenNameOption

(ScreenNameOption, 선택)

화면이름 수집 옵션입니다.

type ScreenNameType = 'routeOnly' | 'titleOnly' | 'full';
 
type ScreenNameOption = {
  screenNameType?: ScreenNameType; // default: 'routeOnly'
  urlWithSearchParams?: boolean; // default: false
};

• screenNameType은 routeOnly, titleOnly, full 중 하나를 선택할 수 있습니다.
  • routeOnly: URL 경로만 포함
  • titleOnly: 페이지 제목만 포함
  • full: 페이지 제목과 URL 경로 모두 포함. 기본값은 routeOnly입니다.
• urlWithSearchParams는 true일 경우 URL에 쿼리 파라미터를 포함합니다. 기본값은 false입니다.

예시: 화면이름에 타이틀만 포함하고 쿼리 파라미터를 추가하려면 아래와 같이 설정합니다.

SophonzSDK.init({
  collectorUrl: 'https://in.sophonz.ai',
  appName: '{{YOUR_APP_NAME}}',
  appVersion: '{{YOUR_APP_VERSION}}',
  appKey: '{{YOUR_APP_KEY}}',
  screenNameOption: {
    screenNameType: 'titleOnly', // 타이틀만 포함
    urlWithSearchParams: true // 쿼리 파라미터 추가
  }
});

sanitizeUrl

((url: string) => string, 선택)

url.full 속성과 화면 이름에 쓰이는 URL을 기록 직전에 정제하는 함수입니다.

이 옵션을 지정하지 않아도 URL 편집은 적용됩니다. 생략하면 SDK가 defaultSanitizeUrl을 사용해 user:password@ 형태의 자격 증명과 널리 쓰이는 민감한 쿼리 파라미터 19종의 값을 편집합니다. 직접 함수를 넘기면 이 기본 동작에 더해지는 것이 아니라 기본 동작을 대체합니다.

기본 파라미터 목록, 매칭 규칙, 기본 동작을 대체하지 않고 확장하는 방법은 데이터 편집을 참고하세요.

attributeScrubbers

(AttributeScrubber[], 선택)

모든 Span과 모든 로그 레코드의 속성에 적용되는 키 단위 편집 규칙입니다.

기본 규칙은 없습니다. 이 옵션을 생략하면 프로세서 자체가 만들어지지 않으므로, 전송되는 텔레메트리는 이 기능을 설정한 적이 없던 때와 동일합니다.

SophonzSDK.init({
  collectorUrl: 'https://in.sophonz.ai',
  appName: '{{YOUR_APP_NAME}}',
  appVersion: '{{YOUR_APP_VERSION}}',
  appKey: '{{YOUR_APP_KEY}}',
  attributeScrubbers: [
    { keys: ['app.user.email'] },
    { keyPattern: /^http\.request\.header\./ },
    {
      keys: ['app.query'],
      scrub: (_key, value) =>
        typeof value === 'string' ? value.slice(0, 64) : value,
    },
  ],
});

규칙의 전체 형태와 예외 처리 방식은 데이터 편집을 참고하세요.

spanLimits

(SpanLimits, 선택)

Span당 속성·이벤트·링크 개수와 속성 값 길이의 상한입니다. @opentelemetry/sdk-trace-base의 값을 그대로 전달합니다. 생략하면 OpenTelemetry SDK 기본값이 적용됩니다.

logRecordLimits

(LogRecordLimits, 선택)

로그 레코드당 속성 개수와 속성 값 길이의 상한입니다. @opentelemetry/sdk-logs의 값을 그대로 전달합니다. 생략하면 OpenTelemetry SDK 기본값이 적용됩니다.

batchProcessorConfig

(BufferConfig, 선택)

Span과 로그 레코드 배치 프로세서의 큐 크기와 내보내기 주기입니다. maxQueueSize, maxExportBatchSize, scheduledDelayMillis, exportTimeoutMillis를 받습니다. 생략하면 OpenTelemetry SDK 기본값이 적용됩니다.

SophonzSDK.init({
  collectorUrl: 'https://in.sophonz.ai',
  appName: '{{YOUR_APP_NAME}}',
  appVersion: '{{YOUR_APP_VERSION}}',
  appKey: '{{YOUR_APP_KEY}}',
  batchProcessorConfig: {
    maxQueueSize: 2048,
    scheduledDelayMillis: 5000,
  },
});

restrictedProtocols

(string[], 선택)

SDK를 초기화하지 않을 프로토콜 목록이며 location.protocol과 비교합니다. 기본값은 ['file:']로, file:// 페이지나 패키징된 앱에서 발생한 텔레메트리가 데이터에 섞이지 않도록 막습니다.

매칭되어도 오류로 취급하지 않습니다. init()은 diag로 보고한 뒤 그대로 반환하며, 예외를 던지지 않고 SDK를 동작하지 않는 상태로 둡니다. 이 가드를 끄려면 restrictedProtocols: []를 지정하세요.

instrumentations

(Instrumentations, 선택)

계측별로 끄거나 세부 설정을 담는 객체입니다. 기본값은 빈 객체 {}입니다.

false를 지정하면 해당 계측이 비활성화되고, 객체를 지정하면 SDK가 설정하는 값에 병합됩니다. 규칙과 계측별 설정 인터페이스는 계측 문서에서 다룹니다.

SophonzSDK.init({
  // ...
  instrumentations: {
    longtask: false,
    interactions: { events: { click: true, submit: false } },
  },
});