Visitor identification

How do we manage visitor identification

What is visitor identification

Visitor identification is the basis of all calculations in Analytics.

Without a perfect management of this identifier, and a real persistence, we would not be able to calculate an exact number of visits and visitors.

This visitor identifier, present on all the events we collect, is personal data. More information is available in our Privacy Center.

How it works

JavaScript

The visitor identification is created the first time you use a pa.sendEvent() / pa.sendEvents() method.

The information is first stored in a cookie, and then sent to all future events into a query parameter.

Cookie	Querystring parameter	Format	SDK version
pa_vid	idclient	GUID	< 6.7.0
_pcid	idclient	16 char.	≥ 6.7.0

The visitor ID must be 16 or 36 characters long.

Apple

The visitor identification is created the first time you use a pa.sendEvent() / pa.sendEvents() method.

Here is the decision tree leading to the output depending on configurations:

HTTP

The management of the visitor identification is delegated to you when you use our Collection API.

Please, note that a break in the identifier will create a new visit and the detection of a new visitor.

A GUID format is recommended.

caution

As the visitor identification is a key notion in Analytics (visits, visitors, ...), we recommend that you do not change our SDKs behavior regarding its management.

Legacy visitor management

More information about legacy visitor management in our Cookies & storage article.

Visitor identification configuration

You can configure the visitor identifier to suit your needs.

JavaScript

Visitor identification behavior you can modify:

Name	Description	Type	Value
storageLifetimeVisitor	Lifetime Storage Visitor value	int	395 (days)
visitorStorageMode	Relative or fixed cookie lifetime value for visitor	string	fixed (default), relative
isVisitorClientSide	Is cookie deposit client side ? If false, server side	boolean	true (default), false

To set up the configuration, see the JavaScript SDK article.

Android (3.3.0+)

Visitor identification behavior you can modify:

Name	Description	Type	Value
visitorStorageLifetime	Lifetime Storage Visitor value	int	395 (days)
visitorStorageMode	Relative or fixed cookie lifetime value for visitor	string	fixed (default), relative
ignoreLimitedAdTracking	Whether the SDK should ignore (true) or not (false) the end-user choice to limit ad tracking.	boolean	true, false (default)
visitorIDType	Visitor ID type	string	VisitorIDType.UUID (default), VisitorIDType.ADVERTISING_ID, VisitorIDType.GOOGLE_ADVERTISING_ID, VisitorIDType.HUAWEI_OPEN_ADVERTISING_ID , VisitorIDType.CUSTOM
visitorId	Custom visitor ID	string	39001HUFEKK977894

To set up the configuration, see the Android (3.3.0+) SDK article.

Android

Visitor identification behavior you can modify:

Name	Description	Type	Value
visitorStorageLifetime	Lifetime Storage Visitor value	int	395 (days)
visitorStorageMode	Relative or fixed cookie lifetime value for visitor	string	VisitorStorageMode.fixed (default), VisitorStorageMode.relative
ignoreLimitedAdTracking	Whether the SDK should ignore (true) or not (false) the end-user choice to limit ad tracking.	boolean	true, false (default)
visitorIDType	Visitor ID type	string	VisitorIDType.uuid (default), VisitorIDType.adid, VisitorIDType.custom
visitorId	Custom visitor ID (only for VisitorIDType.custom)	string	39001HUFEKK977894

Apple

Visitor identification behavior you can modify:

Name	Description	Type	Value
storageLifetimeVisitor	Lifetime Storage Visitor value	int	395 (days)
visitorStorageMode	Relative or fixed cookie lifetime value for visitor	string	fixed (default), relative
ignoreLimitedAdvertisingTracking	Whether the SDK should ignore (true) or not (false) the end-user choice to limit ad tracking.	boolean	true, false (default)
visitorIdType	Visitor ID type	string	uuid (default), androidId, advertisingId, googleAdvertisingId, huaweiOpenAdvertisingId , custom
visitorId	Custom visitor ID	string	39001HUFEKK977894

To set up the configuration, see the Android SDK article.

Flutter

Visitor identification behavior you can modify:

Name	Description	Type	Value
storageLifetimeVisitor	Lifetime Storage Visitor value	int	395 (days)
visitorStorageMode	Relative or fixed cookie lifetime value for visitor	string	fixed (default), relative
ignoreLimitedAdvertisingTracking	Whether the SDK should ignore (true) or not (false) the end-user choice to limit ad tracking.	boolean	true, false (default)
visitorIdType	Visitor ID type	string	uuid (default), idfa, idfv, custom
visitorId	Custom visitor ID	string	39001HUFEKK977894

To set up the configuration, see the Apple SDK article.

HTTP

When using the Collection API, you manage the visitor identifier.

Visitor identification management

In some specific cases, it can be useful to manage the visitor identifier yourself. Depending on the platform, use dedicated configuration or methods for that matter.

JavaScript

≥ 6.15.0 Custom visitor ID: To force or set the visitor identifier, use the global window.pdl object:

window.pdl = window.pdl || {};
window.pdl.browserId = "CUSTOM_BROWSER_ID";

Set window.pdl.browserId before loading the Piano Analytics script so the value is picked up on SDK initialization (same timing as other window.pdl settings, for example consent).

The visitor ID must be 16 or 36 characters long (see the JavaScript tab in How it works above).

Deprecated API

The pa.setVisitorId(visitorId) method is deprecated; prefer window.pdl.browserId for new implementations.

For reference, the previous usage was:

pa.setVisitorId("97c7db4e-4514-4b8e-b693-bd6b57043cc1");

You can also retrieve the visitor ID with a dedicated method. This can be useful to synchronize an ID between native and webviews.

Method:

pa.getVisitorId()

const PAVisitorId = pa.getVisitorId();

Android (3.3.0+)

PianoAnalytics.getInstance().customVisitorId = "97c7db4e-4514-4b8e-b693-bd6b57043cc1"

This will be taken into account only if visitorIDType is set to VisitorIDType.CUSTOM.

You can also retrieve the visitor ID. This can be useful to synchronize an ID between native and webviews.

val visitorId = PianoAnalytics.getInstance().visitorId

Android

await _pianoAnalytics.setVisitorId(
  visitorId: "97c7db4e-4514-4b8e-b693-bd6b57043cc1"
);

This will be taken into account only if visitorIDType is set to VisitorIDType.custom.

You can also retrieve the visitor ID. This can be useful to synchronize an ID between native and webviews.

var visitorId = await _pianoAnalytics.getVisitorId();

Apple

Method:

func PianoAnalytics.setVisitorId(_ visitorId: String) -> void

Parameter	Type	Description
visitorId	String	Visitor identifier (GUID recommended)

pa.setVisitorId("97c7db4e-4514-4b8e-b693-bd6b57043cc1")

You can also retrieve the visitor ID with a dedicated method. This can be useful to synchronize an ID between native and webviews.

Method:

func PianoAnalytics.getVisitorId(PianoAnalytics.OnGetVisitorIdListener) -> void

pa.getVisitorId(visitorId -> {
  // visitorId fetched
});

Flutter

Method:

pa.setVisitorId(_ visitorId: String)

Parameter	Type	Description
visitorId	String	Visitor identifier (GUID recommended)

pa.setVisitorId("97c7db4e-4514-4b8e-b693-bd6b57043cc1")

You can also retrieve the visitor ID with a dedicated method. This can be useful to synchronize an ID between native and webviews.

Method:

pa.getVisitorId(completionHandler: ((_ visitorId: String) -> Void)?)

pa.getVisitorId { visitorId in
  print(visitorId)
}

HTTP

When using the Collection API, you have to feed the visitor identifier directly into the idclient querystring parameter.