Skip to content

Visitor ID

SDK 1.6.8 and later support generating and managing an anonymous Visitor ID via the SDK. Once enabled, a custom request header can be injected into matching URLSession requests and visitor_id is associated in Native RUM; Web SDKs that support Native Bridge can also read the current ID on allowed WebView pages.

This feature is disabled by default. The Visitor ID is not equivalent to the user_id set through the User Binding API, and must not be used as a login credential or authentication information.

Initialization Configuration

First complete SDK initialization, then set a valid FTVisitorIDConfig to FTRumConfig.visitorIDConfig and start RUM. Configuration must be completed before RUM initialization.

#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)
Configuration Type Default Description
FTRumConfig.visitorIDConfig FTVisitorIDConfig nil Visitor ID is disabled when not configured. The feature is also not enabled when the configuration is invalid.
FTVisitorIDConfig.header NSString nil Required. Custom lowercase HTTP request header name, such as x-visitor-id. Must not use reserved headers such as authentication, Cookie, signature, CSRF, or Trace headers.
FTVisitorIDConfig.ttlHours NSTimeInterval 24 Fixed validity period in hours; must be a positive finite number. Reading does not extend the validity period.

You must also add at least one valid URL matching rule. The SDK generates the ID itself; passing custom ID values from the application is not supported.

URL Matching and Request Header Injection

Rules match only HTTP(S) URLs. Multiple rules are evaluated with OR logic, and any single match is sufficient; if a rule throws an exception, it is treated as not matched.

Method Rule
addMatchWithURLPrefix: / Swift addMatch(urlPrefix:) Matches the prefix of the full URL string and also requires the scheme, host, and effective port to match. It is recommended to use a prefix with a path separator for business APIs.
addMatchWithRegularExpression: / Swift addMatch(regularExpression:) Performs regular expression matching against the full URL string. Use ^ and $ when an exact match is required.
addMatchWithHandler: / Swift addMatch(handler:) Custom URL evaluation; returns YES / true to indicate a match. The callback should be fast and thread-safe, avoiding network, disk, or synchronous wait operations. 
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"];
}];

let expression = try NSRegularExpression(pattern: #"^https://api\.example\.com/v[12]/"#)
visitorConfig.addMatch(regularExpression: expression)
visitorConfig.addMatch { url in
    url.host == "checkout.example.com"
}

After adding these rules to the configuration object, assign it to rumConfig.visitorIDConfig and start RUM.

Injection covers matching URLSession data, upload, and download requests; it does not represent injection into all network protocols in the process. This feature does not depend on whether RUM or Trace sampling is hit, and does not require enabling automatic Resource collection; to observe the corresponding Resource events, you still need to configure Resource collection and sampling.

Validity Period, Persistence, and Reset

The ID is persisted locally and can be reused after restarting the app within its validity period. The validity period is calculated from the time the ID is created and is not sliding-extended by accesses; after expiration, the next retrieval of the ID generates a new value. Uninstalling the app or clearing app data may cause the local ID to be lost.

To rotate the ID proactively, call:

[FTSDKAgent resetVisitorID];

FTSDKAgent.resetVisitorID()

When enabled, resetting generates a new ID; when disabled, resetting only clears the local record. Events already generated and requests already sent retain the ID captured at the time they occurred, and are not retroactively replaced by a later reset or expiration.

WebView Sharing

Web pages need to integrate a Web SDK that supports obtaining the Visitor ID through Native Bridge, and WebView Bridge must be allowed. The current ID is returned according to the Native state at the time of reading; after a reset or TTL expiration, the new value can be read.

  • URL matching rules control whether the request header is injected into URLSession requests.
  • FTSDKConfig.allowWebViewHost controls which WebView pages can use automatic Bridge and read the Native Visitor ID, and is configured separately from request URL rules.
  • Visitor ID reading is allowed only on the main frame; if the feature is not enabled, the configuration is invalid, or the host is not allowed, the Native ID is not returned.

Set the WebView allowlist before SDK initialization; see WebView Data Monitoring for an example. Configuring only the Visitor ID request URL rules does not automatically restrict the WebView host scope.

Feedback

Is this page helpful?