Skip to content

Visitor ID

ft-sdk >= 1.7.6-alpha04 supports enabling the anonymous Visitor ID through FTRUMConfig.setVisitorIdConfig(...): it injects the specified header into OkHttp HTTP/HTTPS requests whose URLs match, and associates visitor_id with native RUM data. This ID is not used for login authentication and does not replace the user information set by bindRumUserData.

Initialization Configuration

After completing basic SDK initialization, configure the Visitor ID before creating the business OkHttpClient. The following example injects the header only into business endpoints whose URLs start with https://api.example.com/v1/; replace it with your actual business address:

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)
)

If not configured or null is passed, this capability is disabled without needing an additional switch. The configuration is validated and a copy is saved during initRUMWithConfig; modifying the original configuration object afterward does not update the configuration that has already taken effect. If the header, validity period, or match rules fail validation, the SDK outputs an error log and disables the Visitor ID.

FTVisitorIdConfig Method Type Required Description
setHeader String Yes Custom request header name with no default value; must be lowercase and conform to the HTTP header name format. Headers reserved for authentication, signing, distributed tracing, or SDK use are not allowed, such as authorization, cookie, traceparent, and x-rum-resource-id. Prefixes such as proxy-, sec-, x-datadog-, and x-b3- are also not allowed. x-visitor-id is recommended
setTtlHours double No Fixed validity period in hours, defaulting to 24, with decimals supported. Must be a finite positive number that is at least 1 and less than Long.MAX_VALUE when converted to milliseconds. The timer starts when the ID is created and is not renewed by requests or visits
addMatch String / Pattern / FTVisitorIdConfig.UrlMatcher Yes Add at least one non-empty match rule; multiple rules are treated as OR relations. The header is injected only into matching targets

addMatch supports the following three rule types:

  • String: Matches the full URL prefix and also requires the scheme, host, and effective port to be identical. For example, https://api.example.com/v1/ does not match other domains or HTTP URLs.
  • java.util.regex.Pattern: Runs matcher.find() on the full URL. If you need to restrict the scheme, domain, and path, explicitly constrain the scope in the expression.
  • FTVisitorIdConfig.UrlMatcher: Returns whether the URL matches through matches(String url). The callback may be invoked concurrently, so keep it thread-safe and avoid time-consuming operations. If it throws a runtime exception, the rule is treated as not matching.

OkHttp Integration and Injection Scope

When using ft-plugin for automatic instrumentation, the instrumented OkHttpClient.Builder.build() installs the Visitor ID interceptor after the initialization described above. Clients that have already been created are not automatically retrofitted. If you do not use the plugin or the call site is not instrumented, configure it as described in Manual Visitor ID Integration.

  • Header injection is independent of setEnableTraceUserResource, RUM sampling, and Trace sampling. Enabling only the Visitor ID does not automatically enable Resource or Trace collection.
  • If a matching request already contains a header with the same name, the SDK overwrites it with the Visitor ID it manages and outputs a warning log.
  • The SDK reporting URL, as well as URLs for which isInTakeUrl in setResourceUrlHandler returns true, do not get the Visitor ID header injected.
  • Redirects or retries re-evaluate the target URL. If the target does not match, the header injected by the SDK is removed; if it matches, the ID from the start of the request is used.
  • Native header injection applies to OkHttp HTTP/HTTPS requests and does not cover WebSocket handshakes, HttpURLConnection / HttpsURLConnection, or network requests inside WebView.

Validity Period and Reset

The Visitor ID is stored independently per process in local SharedPreferences. Restarting the same process within the validity period reuses the ID; the ID is not shared across processes. If persistence fails, a stable in-memory ID is used until it expires or is proactively reset. The next read after expiration generates a new ID.

After the business confirms that a user has logged out or switched accounts, you can reset it proactively:

FTSdk.resetVisitorId();

FTSdk.resetVisitorId()

Reset immediately generates a new ID and restarts the validity period. It does not change the bound user, RUM Session, Trace ID, or sampling configuration. The call is ineffective when the Visitor ID is not enabled. Do not reset automatically merely because of HTTP 401 or ordinary request failures. OkHttp requests that have already started, along with their associated Resources and network Errors, retain the ID from the start of the request.

HttpURLConnection / HttpsURLConnection do not get the Visitor ID header injected. Their Resources and network Errors use the event-level visitor_id from native RUM, which is read when the event is generated and is not bound to the ID at the start of the request. The presence of visitor_id in the reported data does not mean the business request sent a header with the same name.

The visitor_id of native RUM is managed by the SDK and cannot be overridden by ordinary global attributes or event attributes. The final DataModifier / LineDataModifier can still modify or remove reported fields. WebView RUM data retains the Browser SDK's own Visitor ID and is not overridden by the native context.