방문자 식별자(Visitor ID)¶

ft-sdk >= 1.7.6-alpha04에서는 FTRUMConfig.setVisitorIdConfig(...)을 통해 익명 방문자 식별 기능을 활성화할 수 있습니다. URL이 일치하는 OkHttp HTTP/HTTPS 요청에 지정된 Header를 주입하고, 네이티브 RUM 데이터에 visitor_id를 연결합니다. 이 식별자는 로그인 인증에 사용되지 않으며, bindRumUserData로 설정한 사용자 정보를 대체하지 않습니다.

초기화 설정¶

SDK 기본 초기화를 완료한 후, 비즈니스 OkHttpClient를 생성하기 전에 Visitor ID를 설정합니다. 다음 예시는 https://api.example.com/v1/ 접두사에 해당하는 비즈니스 API에만 Header를 주입하도록 허용하며, 실제 비즈니스 주소로 교체하세요.

JavaKotlin

FTVisitorIdConfig visitorIdConfig = new FTVisitorIdConfig()
    .setHeader("x-visitor-id")
    .setTtlHours(24)
    .addMatch("https://api.example.com/v1/");

FTSdk.initRUMWithConfig(new FTRUMConfig()
    .setRumAppId(RUM_APP_ID)
    .setVisitorIdConfig(visitorIdConfig));

val visitorIdConfig = FTVisitorIdConfig()
    .setHeader("x-visitor-id")
    .setTtlHours(24.0)
    .addMatch("https://api.example.com/v1/")

FTSdk.initRUMWithConfig(
    FTRUMConfig()
        .setRumAppId(RUM_APP_ID)
        .setVisitorIdConfig(visitorIdConfig)
)

값을 설정하지 않거나 null을 전달하면 이 기능이 비활성화되며 별도의 스위치를 켤 필요가 없습니다. 설정은 initRUMWithConfig 호출 시 검증되어 복사본으로 저장되며, 이후 원본 설정 객체를 수정해도 이미 적용된 설정은 업데이트되지 않습니다. Header, 유효 기간 또는 매칭 규칙 검증에 실패하면 SDK는 오류 로그를 출력하고 Visitor ID를 비활성화합니다.

FTVisitorIdConfig 메서드	유형	필수	설명
setHeader	String	예	사용자 정의 요청 Header 이름이며 기본값이 없습니다. 소문자여야 하고 HTTP Header 이름 형식을 따라야 합니다. 인증, 서명, 분산 추적 또는 SDK 예약 Header(예: `authorization`, `cookie`, `traceparent`, `x-rum-resource-id`)는 사용할 수 없으며, `proxy-`, `sec-`, `x-datadog-`, `x-b3-` 접두사도 사용할 수 없습니다. `x-visitor-id` 사용을 권장합니다.
setTtlHours	double	아니요	고정 유효 기간(단위: 시간)이며 기본값은 `24`이고 소수점을 지원합니다. 유한한 양수여야 하며, 밀리초로 환산했을 때 최소 1 이상이면서 `Long.MAX_VALUE`보다 작아야 합니다. ID가 생성된 시점부터 시간이 계산되며 요청이나 방문으로 갱신되지 않습니다.
addMatch	String / Pattern / FTVisitorIdConfig.UrlMatcher	예	비어 있지 않은 매칭 규칙을 최소 1개 추가해야 하며, 여러 규칙 간에는 '또는(or)' 관계가 적용됩니다. 매칭된 대상에만 Header가 주입됩니다.

addMatch는 다음 세 가지 규칙을 지원합니다.

문자열: 전체 URL 접두사를 매칭하며 프로토콜, 호스트, 유효 포트가 동일해야 합니다. 예를 들어 https://api.example.com/v1/는 다른 도메인이나 HTTP 주소와 매칭되지 않습니다.
java.util.regex.Pattern: 전체 URL에 대해 matcher.find()를 수행합니다. 프로토콜, 도메인, 경로를 제한하려면 표현식에 범위를 명시적으로 지정하세요.
FTVisitorIdConfig.UrlMatcher: matches(String url)를 통해 매칭 여부를 반환합니다. 콜백은 동시에 실행될 수 있으므로 스레드 안전성을 보장하고 시간이 오래 걸리는 작업을 피해야 합니다. 런타임 예외가 발생하면 해당 규칙은 불일치로 처리됩니다.

OkHttp 연동 및 주입 범위¶

ft-plugin 자동 계측을 사용할 때, 위 초기화를 완료하면 계측된 OkHttpClient.Builder.build()에 Visitor ID 인터셉터가 설치됩니다. 이미 생성된 Client에는 자동으로 추가 설치되지 않습니다. 플러그인을 사용하지 않거나 호출 지점이 계측되지 않은 경우 수동 Visitor ID 연동에 따라 설정하세요.

Header 주입은 setEnableTraceUserResource, RUM 샘플링, Trace 샘플링과 독립적입니다. Visitor ID만 활성화해도 Resource 또는 Trace 수집이 자동으로 켜지지 않습니다.
매칭된 요청에 이미 동일한 이름의 Header가 있으면 SDK는 자체 관리하는 Visitor ID로 덮어쓰고 경고 로그를 출력합니다.
SDK 전송 주소와 setResourceUrlHandler에서 isInTakeUrl이 true를 반환하는 주소에는 Visitor ID Header가 주입되지 않습니다.
리다이렉트나 재시도 시 대상 주소를 다시 판정합니다. 대상이 매칭되지 않으면 SDK가 주입한 Header를 제거하고, 매칭되면 해당 요청 시작 시점의 ID를 계속 사용합니다.
네이티브 Header 주입은 OkHttp HTTP/HTTPS 요청에 적용되며, WebSocket 핸드셰이크, HttpURLConnection / HttpsURLConnection, WebView 내부의 네트워크 요청에는 적용되지 않습니다.

유효 기간 및 리셋¶

Visitor ID는 프로세스별로 로컬 SharedPreferences에 독립적으로 저장되며, 유효 기간 내에 동일 프로세스를 재시작하면 재사용할 수 있습니다. 다중 프로세스 간에는 공유되지 않습니다. 영속화에 실패하면 만료되거나 명시적으로 리셋될 때까지 메모리의 안정적인 ID를 사용합니다. 만료 후 다음 읽기 시 새 ID가 생성됩니다.

비즈니스에서 로그아웃 또는 계정 전환을 확인한 후 명시적으로 리셋할 수 있습니다.

JavaKotlin

FTSdk.resetVisitorId();

FTSdk.resetVisitorId()

리셋하면 즉시 새 ID가 생성되고 유효 기간이 다시 계산되며, 바인딩된 사용자, RUM Session, Trace ID 또는 샘플링 설정은 변경되지 않습니다. Visitor ID가 비활성화된 상태에서는 호출해도 효과가 없습니다. HTTP 401 또는 일반적인 요청 실패만으로 자동 리셋하지 마세요. 이미 시작된 OkHttp 요청과 관련된 Resource, 네트워크 Error는 요청 시작 시점의 ID를 유지합니다.

HttpURLConnection / HttpsURLConnection에는 Visitor ID Header가 주입되지 않으며, 해당 Resource와 네트워크 Error는 네이티브 RUM의 이벤트 레벨 visitor_id를 그대로 사용합니다. 이 값은 이벤트 생성 시점에 가져오므로 요청 시작 시점의 ID에 바인딩되지 않습니다. 전송 데이터에 visitor_id가 있다고 해서 비즈니스 요청에 동일한 이름의 Header가 전송된 것은 아닙니다.

네이티브 RUM의 visitor_id는 SDK가 관리하므로 일반적인 글로벌 속성이나 이벤트 속성으로는 덮어쓸 수 없습니다. 최종 DataModifier / LineDataModifier는 여전히 전송 필드를 수정하거나 제거할 수 있습니다. WebView RUM 데이터는 Browser SDK 자체의 Visitor ID를 유지하며 네이티브 컨텍스트에 의해 덮어쓰이지 않습니다.

방문자 식별자(Visitor ID)¶

초기화 설정¶

OkHttp 연동 및 주입 범위¶

유효 기간 및 리셋¶

이 페이지가 도움이 되었나요? ×

이 페이지가 도움이 되었나요?