방문자 식별자 Visitor ID¶
SDK 0.4.3부터 지원합니다.
Visitor ID는 SDK가 생성하고 관리하는 익명 방문자 식별자입니다. 활성화하면 일치하는 HTTP(S) 요청에 사용자 정의 요청 헤더를 주입하고 RUM 데이터에 visitor_id를 연결할 수 있습니다. 또한 해당 Web SDK가 연동된 WebView 페이지에서도 Native 식별자를 읽을 수 있습니다.
이 기능은 기본적으로 비활성화되어 있습니다. Visitor ID는 bindRUMUserData()로 설정한 사용자 식별자와 동일하지 않으며, 로그인 자격 증명이나 인증 정보로 사용할 수 없습니다. SDK가 식별자를 직접 생성하며, 애플리케이션에서 식별자 값을 지정하는 것은 지원하지 않습니다.
초기화 구성¶
먼저 SDK 초기화를 완료한 다음, FTRUMConfig.visitorIdConfig를 통해 RUM을 구성하고 초기화합니다:
import {
FTMobileReactNative,
FTReactNativeRUM,
FTRUMConfig,
FTVisitorIdConfig,
} from '@cloudcare/react-native-mobile';
const rumConfig: FTRUMConfig = {
androidAppId: 'android_app_id',
iOSAppId: 'ios_app_id',
visitorIdConfig: {
header: 'x-visitor-id',
ttlHours: 24,
urlPrefixes: ['https://api.example.com/'],
},
};
await FTReactNativeRUM.setConfig(rumConfig);
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| header | string | 예 | 소문자 사용자 정의 HTTP 요청 헤더 이름입니다. 예: x-visitor-id. 인증, Cookie, 서명, CSRF, Trace 등 예약된 요청 헤더는 사용할 수 없습니다 |
| ttlHours | number | 아니요 | 고정 유효 기간(단위: 시간)이며 기본값은 24입니다. 읽기는 유효 기간을 연장하지 않습니다. 소수를 지원하며, 밀리초로 환산한 값은 1 이상 2^63 미만이어야 하고 NaN 또는 Infinity일 수 없습니다 |
| urlPrefixes | string[] | 조건부 필수 | 전체 HTTP(S) URL 접두사입니다. 일치 범위는 동일한 프로토콜, 호스트 및 유효 포트로 제한됩니다. regularExpressions와 함께 최소 하나의 규칙을 제공해야 합니다 |
| regularExpressions | string[] | 조건부 필수 | 전체 URL에 대해 정규식으로 일치시키는 표현식 문자열입니다. urlPrefixes와 "OR" 관계입니다 |
visitorIdConfig를 생략하거나 null로 설정하면 비활성화됩니다. 구성이 유효하지 않으면 FTReactNativeRUM.setConfig()가 실패한 Promise를 반환하므로, 구성을 수정한 후 다시 초기화해야 합니다.
URL 일치와 요청 헤더 주입¶
여러 규칙은 "OR" 관계이며, 어느 하나만 일치해도 됩니다. React Native는 URL 접두사와 정규식 두 가지 일치 방식을 제공합니다:
- URL 접두사: 전체 URL 문자열의 접두사로 일치하며, 동시에 프로토콜, 호스트 및 유효 포트가 일치해야 합니다. 경로 구분자가 포함된 접두사 사용을 권장합니다. 예:
https://api.example.com/orders/.orders-history와 같은 경로가 잘못 일치하지 않도록 해야 합니다. - 정규식: 전체 URL에서 일치 항목을 찾습니다. 시작점을 제한하거나 전체 일치가 필요하면
^,$를 사용합니다. 문자열로 전달되므로 백슬래시를 이스케이프해야 합니다. 표현식은 iOS와 Android의 정규식 구문과 호환되어야 합니다.
예를 들어 /orders/ 아래의 요청이나 /v1/, /v2/ 아래의 요청에 식별자를 주입합니다:
const visitorIdConfig: FTVisitorIdConfig = {
header: 'x-visitor-id',
urlPrefixes: ['https://api.example.com/orders/'],
regularExpressions: ['^https://api\\.example\\.com/v[12]/'],
};
// RUM 초기화 전에 이를 rumConfig.visitorIdConfig에 할당합니다.
FTVisitorIdConfig와 FTRUMConfig는 동일한 React Native 메인 SDK 패키지에서 가져옵니다.
요청 헤더 주입은 SDK가 연동된 HTTP(S) 네트워크 요청에 적용되며, WebSocket 요청에는 주입되지 않습니다. Android에서는 ft-plugin 네트워크 연동 구성을 완료해야 합니다. 사용자 정의 네트워크 클라이언트를 사용하는 경우에도 해당 클라이언트가 SDK에 연동되어 있어야 합니다.
Visitor ID 요청 헤더 주입은 RUM 또는 Trace의 샘플링 적중 여부에 의존하지 않으며, 자동 Resource 수집을 활성화할 것도 요구하지 않습니다. 플랫폼에서 해당 Resource 데이터를 확인해야 하는 경우에는 여전히 Resource 수집을 활성화하고 해당 샘플링을 구성해야 합니다.
유효 기간, 영속화 및 재설정¶
식별자는 로컬에 영속화되며, 저장소가 정상이고 유효 기간이 만료되지 않은 경우 앱을 다시 시작해도 계속 사용할 수 있습니다. 유효 기간은 식별자 생성 시점부터 계산되며, 접근하거나 읽어도 유효 기간이 연장되지 않습니다. 만료 후 다음에 식별자를 가져올 때 새 값이 생성됩니다.
앱을 제거하거나 앱 데이터를 지우는 등의 작업으로 로컬 식별자가 유실될 수 있습니다. 로컬 저장소를 사용할 수 없으면 식별자는 현재 프로세스 내에서만 유지됩니다. Android 다중 프로세스 앱에서 식별자는 프로세스별로 독립적으로 관리됩니다.
Visitor ID를 활성화한 후 식별자를 직접 교체해야 할 때 다음을 호출합니다:
재설정하면 새 식별자가 생성되며, 이후 요청과 읽기에는 새 값이 사용됩니다. 이미 캐시된 데이터와 이미 시작된 요청에 포함된 식별자는 소급하여 교체되지 않습니다.
WebView 공유¶
Web 페이지는 Native Bridge를 통해 Visitor ID를 가져오는 기능을 지원하는 Web SDK를 연동하고 WebView 연동을 완료해야 합니다. 유효한 visitorIdConfig를 구성하면 Web SDK가 현재 Native 식별자를 읽을 수 있습니다. Visitor ID가 활성화되지 않은 경우 Native 식별자를 반환하지 않습니다.
두 가지 규칙은 각각 다른 범위를 제어합니다:
visitorIdConfig.urlPrefixes,regularExpressions는 비즈니스 HTTP(S) 요청에 Visitor ID 요청 헤더를 주입할지 여부를 제어합니다.- React Native의
FTMobileConfig.allowWebViewHost는 WebView host 범위를 구성하며, 이 기능을 지원하는 Web SDK가 Native 식별자를 읽을 때 사용됩니다. 자세한 내용은 WebView host 구성을 참조하세요. iOS에서는 추가로 메인 프레임에서만 읽도록 제한합니다.
SDK 초기화 시 FTMobileConfig.allowWebViewHost를 구성하고, SDK 및 RUM 초기화가 완료된 후 WebView 페이지를 로드합니다. 요청 URL 일치 규칙만 설정하는 것으로는 WebView 페이지 범위가 자동으로 제한되지 않습니다. TTL이 만료되거나 재설정된 후에는 이후 읽기에 새로운 현재 식별자가 사용되며, Web 측에서는 이전 값을 영구적으로 캐시해서는 안 됩니다.