Visitor ID¶
Supported since SDK 0.4.3.
Visitor ID is an anonymous visitor identifier generated and managed by the SDK. When enabled, a custom request header can be injected into matching HTTP(S) requests, and visitor_id is associated in RUM data; WebView pages integrated with the corresponding Web SDK can also read the native identifier.
This feature is disabled by default. Visitor ID is not the same as the user identifier set via bindRUMUserData(), and cannot be used as login credentials or authentication information. The SDK generates the identifier itself; application-specified identifier values are not supported.
Initial Configuration¶
First complete SDK initialization, then configure FTRUMConfig.visitorIdConfig and initialize RUM:
import {
FTMobileReactNative,
FTReactNativeRUM,
FTRUMConfig,
FTVisitorIdConfig,
} from '@truewatchtech/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);
| Field | Type | Required | Description |
|---|---|---|---|
| header | string | Yes | Lowercase custom HTTP request header name, for example x-visitor-id; reserved request headers such as authentication, Cookie, signature, CSRF, and Trace headers cannot be used |
| ttlHours | number | No | Fixed validity period in hours, default 24; reads do not renew it. Decimal values are supported. After conversion to milliseconds, the value must be at least 1 and less than 2^63, and cannot be NaN or Infinity |
| urlPrefixes | string[] | Conditionally required | Full HTTP(S) URL prefix; matching is limited to the same protocol, host, and effective port; provide at least one rule in either this field or regularExpressions |
| regularExpressions | string[] | Conditionally required | Expression string for regular expression matching against the full URL; has an OR relationship with urlPrefixes |
Omitting visitorIdConfig or setting it to null means the feature is not enabled. If the configuration is invalid, FTReactNativeRUM.setConfig() returns a failed Promise; correct the configuration before initializing.
URL Matching and Request Header Injection¶
Multiple rules are combined with OR; matching any one is sufficient. React Native provides two matching methods: URL prefix and regular expression:
- URL prefix: Matches by prefix against the full URL string and also requires the protocol, host, and effective port to be the same. Use prefixes with a path separator, such as
https://api.example.com/orders/, to avoid incorrectly matching paths such asorders-history. - Regular expression: Searches for a match in the full URL; use
^and$when you need to restrict the start or require a full match. The value is a string, so backslashes must be escaped; the expression must be compatible with the regular expression syntax on iOS and Android.
For example, to inject the identifier into requests under /orders/ or under /v1/ and /v2/:
const visitorIdConfig: FTVisitorIdConfig = {
header: 'x-visitor-id',
urlPrefixes: ['https://api.example.com/orders/'],
regularExpressions: ['^https://api\\.example\\.com/v[12]/'],
};
// Assign it to rumConfig.visitorIdConfig before RUM initialization.
FTVisitorIdConfig and FTRUMConfig are imported from the same main React Native SDK package.
Request header injection applies to HTTP(S) network requests integrated with the SDK; WebSocket requests are not injected. On Android, complete the ft-plugin network integration configuration; when using a custom network client, also ensure that the client is integrated with the SDK.
Visitor ID request header injection does not depend on whether RUM or Trace sampling is hit, nor does it require automatic Resource collection to be enabled. To view the corresponding Resource data in the platform, you still need to enable Resource collection and configure the corresponding sampling.
Validity Period, Persistence, and Reset¶
The identifier is persisted locally. If storage is functioning properly and the validity period has not expired, the application can continue to use it after a restart. The validity period starts when the identifier is created; access or reads do not extend the validity period. After expiration, a new value is generated the next time the identifier is obtained.
Operations such as uninstalling the application or clearing application data may cause the local identifier to be lost; if local storage is unavailable, the identifier can only be retained within the current process. In Android multi-process applications, identifiers are managed independently per process.
After enabling Visitor ID, call the following when you need to proactively change the identifier:
Resetting generates a new identifier, and subsequent requests and reads use the new value. Identifiers in cached data and in requests that have already been initiated are not retroactively replaced.
WebView Sharing¶
The web page must integrate a Web SDK that supports obtaining the Visitor ID through the Native Bridge and complete WebView integration. After a valid visitorIdConfig is configured, the Web SDK can read the current native identifier; when Visitor ID is not enabled, the native identifier is not returned.
The two types of rules control different scopes:
visitorIdConfig.urlPrefixesandregularExpressionscontrol whether the Visitor ID request header is injected into business HTTP(S) requests.- React Native's
FTMobileConfig.allowWebViewHostconfigures the WebView host scope, which Web SDKs that support this capability use when reading the native identifier. For details, see WebView host configuration. On iOS, reading is also limited to the main frame.
Configure FTMobileConfig.allowWebViewHost during SDK initialization, and load the WebView page after SDK and RUM initialization are complete. Setting only request URL matching rules does not automatically limit the WebView page scope. After TTL expiration or a reset, subsequent reads use the new current identifier; the web side should not cache the old value permanently.