Docs

visitorIDLifetime

The visitorIDLifetime property sets how long, in seconds, the current visitor ID may be used before the SDK treats it as expired. When it expires, the SDK assigns a new random visitor ID and clears visit-scoped state: custom variables and custom dimensions you attached at visit scope, dimensions still queued for the next hit at action scope, sendCampaign() parameters waiting to attach to the next event, and visit / activity counters held for that visitor (see Notes). That behaves like starting a new visitor in reporting.

If visitorIDLifetime is 0 or negative, expiry is off (default). The SDK checks for expiry when it queues an analytics event (before the event is persisted for upload).

Syntax

PiwikTracker.sharedInstance()?.visitorIDLifetime = seconds
[PiwikTracker sharedInstance].visitorIDLifetime = seconds;

Parameters

  • visitorIDLifetime number, required. Lifetime in seconds. 0 or less means no expiry (default 0).

Examples

To set the visitor ID lifetime to 30 days:

PiwikTracker.sharedInstance()?.visitorIDLifetime = 30 * 24 * 60 * 60
[PiwikTracker sharedInstance].visitorIDLifetime = 30 * 24 * 60 * 60;

To disable visitor ID expiry:

PiwikTracker.sharedInstance()?.visitorIDLifetime = 0
[PiwikTracker sharedInstance].visitorIDLifetime = 0;

Notes

  • When the visitor ID expires (just before an analytics event is queued): the SDK assigns a new random visitor ID and clears visit-scoped custom variables. Values you set in visit scope are removed; if includeDefaultCustomVariable is still enabled (the default), the SDK’s built-in visit variables are recreated when that event is built. It also clears visit-scoped custom dimensions, any action-scoped custom dimensions still waiting for the next request, sendCampaign() query parameters stored for the next event, and internal visit and activity counters (visit counts and related timestamps, including the session clock used for those metrics).
  • Replacement of the visitor ID through expiry also triggers the Session Hash rule in sessionHash (forced sh=0 for 31 minutes after the ID change). Manual setVisitorID counts as a change too for that rule.
  • The lifetime is counted from when the current visitor ID was last assigned. That moment resets whenever the ID is replaced (for example after expiry or setVisitorID). The same visitor ID is reused across app launches until something replaces it.
  • With isAnonymizationEnabled on, visitorID can change between app launches; see visitorID. The same rule applies: the lifetime is counted from when that visitor ID was assigned, and it can still expire and be replaced under the same rules.

Related methods

Updated 15 days ago