방문자 식별자 Visitor ID¶
SDK 1.6.8 이상에서는 SDK가 익명 방문자 식별자(Visitor ID)를 생성하고 관리할 수 있습니다. 활성화하면 일치하는 URLSession 요청에 사용자 정의 요청 헤더를 주입하고 Native RUM에서 visitor_id를 연결할 수 있습니다. Native Bridge를 지원하는 Web SDK는 허용된 WebView 페이지에서 현재 식별자를 읽을 수도 있습니다.
이 기능은 기본적으로 비활성화되어 있습니다. Visitor ID는 사용자 바인딩 API로 설정하는 user_id와 동일하지 않으며, 로그인 자격 증명이나 인증 정보로 사용할 수 없습니다.
초기화 구성¶
먼저 SDK 초기화를 완료한 다음, 유효한 FTVisitorIDConfig를 FTRumConfig.visitorIDConfig에 설정하고 RUM을 시작하세요. 구성은 RUM 초기화 전에 완료해야 합니다.
#import <GuanceSDK/GuanceSDK.h>
FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appid];
FTVisitorIDConfig *visitorConfig = [[FTVisitorIDConfig alloc] init];
visitorConfig.header = @"x-visitor-id";
visitorConfig.ttlHours = 24;
[visitorConfig addMatchWithURLPrefix:@"https://api.example.com/"];
rumConfig.visitorIDConfig = visitorConfig;
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];
import GuanceSDK
let rumConfig = FTRumConfig(appid: appid)
let visitorConfig = FTVisitorIDConfig()
visitorConfig.header = "x-visitor-id"
visitorConfig.ttlHours = 24
visitorConfig.addMatch(urlPrefix: "https://api.example.com/")
rumConfig.visitorIDConfig = visitorConfig
FTSDKAgent.sharedInstance().startRum(withConfigOptions: rumConfig)
| 구성 | 유형 | 기본값 | 설명 |
|---|---|---|---|
FTRumConfig.visitorIDConfig |
FTVisitorIDConfig |
nil |
구성하지 않으면 Visitor ID가 비활성화됩니다. 구성이 유효하지 않아도 이 기능은 활성화되지 않습니다. |
FTVisitorIDConfig.header |
NSString |
nil |
필수 항목입니다. 소문자로 된 사용자 정의 HTTP 요청 헤더 이름입니다(예: x-visitor-id). 인증, Cookie, 서명, CSRF 또는 Trace 등 예약된 요청 헤더는 사용할 수 없습니다. |
FTVisitorIDConfig.ttlHours |
NSTimeInterval |
24 |
고정 유효 시간(단위: 시간)입니다. 양수인 유한한 값이어야 합니다. 조회해도 유효 기간이 연장되지 않습니다. |
또한 유효한 URL 일치 규칙을 하나 이상 추가해야 합니다. SDK가 식별자를 직접 생성하며, 앱에서 사용자 정의 식별자 값을 전달하는 방식은 지원하지 않습니다.
URL 일치 및 요청 헤더 주입¶
규칙은 HTTP(S) URL만 일치합니다. 여러 규칙은 OR 관계이므로 하나라도 일치하면 됩니다. 규칙에서 예외가 발생하면 일치하지 않은 것으로 처리합니다.
| 메서드 | 규칙 |
|---|---|
addMatchWithURLPrefix: / Swift addMatch(urlPrefix:) |
전체 URL 문자열의 접두사를 일치시키며, scheme, host, 유효한 포트도 일치해야 합니다. 비즈니스 API에는 경로 구분 기호가 포함된 접두사를 사용하는 것이 좋습니다. |
addMatchWithRegularExpression: / Swift addMatch(regularExpression:) |
전체 URL 문자열에서 정규식 일치를 수행합니다. 전체 일치가 필요하면 ^와 $를 사용하세요. |
addMatchWithHandler: / Swift addMatch(handler:) |
사용자 정의 URL 판단입니다. YES/true를 반환하면 일치한 것으로 간주합니다. 콜백은 빠르고 스레드 안전해야 하며, 네트워크·디스크 작업이나 동기 대기를 피해야 합니다. |
NSRegularExpression *expression = [NSRegularExpression
regularExpressionWithPattern:@"^https://api\\.example\\.com/v[12]/"
options:0 error:nil];
[visitorConfig addMatchWithRegularExpression:expression];
[visitorConfig addMatchWithHandler:^BOOL(NSURL *url) {
return [url.host isEqualToString:@"checkout.example.com"];
}];
이 규칙들을 구성 객체에 추가한 다음 rumConfig.visitorIDConfig에 할당하고 RUM을 시작하세요.
주입 범위는 일치하는 URLSession data, upload, download 요청입니다. 프로세스 내 모든 네트워크 프로토콜에 주입된다는 의미는 아닙니다. 이 기능은 RUM 또는 Trace 샘플링 적용 여부와 무관하며, 자동 Resource 수집을 활성화할 필요도 없습니다. 해당 Resource 이벤트를 관찰해야 하는 경우에도 Resource 수집과 샘플링을 구성해야 합니다.
유효 기간, 영속화 및 재설정¶
식별자는 로컬에 영속화되며, 유효 기간 내에 앱을 다시 시작해도 계속 사용할 수 있습니다. 유효 기간은 식별자가 생성된 시점부터 계산되며, 접근해도 유효 기간이 슬라이딩 방식으로 연장되지 않습니다. 만료된 후 다음에 식별자를 가져오면 새 값이 생성됩니다. 앱을 제거하거나 앱 데이터를 지우는 등의 작업으로 로컬 식별자가 유실될 수 있습니다.
식별자를 수동으로 교체해야 하는 경우 다음을 호출하세요.
활성화된 상태에서 재설정하면 새 식별자가 생성됩니다. 비활성화된 상태에서 재설정하면 로컬 기록만 삭제됩니다. 이미 생성된 이벤트와 이미 전송된 요청에는 발생 당시 캡처된 식별자가 유지되며, 이후 재설정이나 만료로 인해 소급 교체되지 않습니다.
WebView 공유¶
Web 페이지는 Native Bridge를 통해 Visitor ID를 가져올 수 있는 Web SDK를 통합해야 하며, WebView Bridge 설정이 허용되어야 합니다. 현재 식별자는 읽는 시점의 Native 상태를 기준으로 반환되며, 재설정 또는 TTL 만료 후에는 새 값을 읽을 수 있습니다.
- URL 일치 규칙은 URLSession 요청에 요청 헤더를 주입할지 여부를 제어합니다.
FTSDKConfig.allowWebViewHost는 어떤 WebView 페이지에서 자동 Bridge를 사용하고 Native Visitor ID를 읽을 수 있는지를 제어하며, 요청 URL 규칙과 별도로 구성합니다.- Visitor ID 읽기는 메인 프레임에서만 허용됩니다. 비활성화된 상태, 유효하지 않은 구성 또는 허용되지 않은 host에서는 Native 식별자가 반환되지 않습니다.
SDK 초기화 전에 WebView 허용 목록을 설정하세요. 예시는 WebView 데이터 모니터링을 참조하세요. Visitor ID의 요청 URL 규칙만 구성한다고 WebView host 범위가 자동으로 제한되지는 않습니다.