Docs

Advanced usage

User ID

The user ID is an optional, non-empty, unique string that identifies the user. It isn’t set by default.

It can be a unique username, email address, or another identifier.

When the user ID is sent to Analytics with the visitor ID, it helps associate events from different platforms, such as iOS and Android, with the same user. This works as long as the same user ID is used on all platforms.

The visitor ID is always generated automatically by the SDK. Read more.

You can set a user ID with the setUserId method:

await PiwikProSdk.setUserId('testUserId');
  • userId: string – A unique, non-empty string that identifies the user. Pass null to delete the current user ID.

You can read the current user ID using the getUserId method:

const currentUserId = await PiwikProSdk.getUserId();

User email address

The user email address is another string that identifies users. When you send the custom profile attribute configured in the Audience Manager web panel, the provided user email address is sent to Data Activation.

Like the user ID, the user email address helps associate data from different platforms, such as iOS and Android, with the same user. This works as long as the same email address is used on all platforms.

We recommend setting the user email address when you collect Data Activation profile attributes. This helps create a more complete user profile.

You can set a user email with the setUserEmail method:

await PiwikProSdk.setUserEmail('[email protected]');
  • email: string – A string that represents an email address.

You can get the current user email using the getUserEmail method:

const currentUserEmail = await PiwikProSdk.getUserEmail();

Visitor ID

The SDK uses different IDs to identify users. The main ID is the visitor ID, which the SDK randomly generates the first time it’s used and stores locally on the device.

The visitor ID doesn’t change unless the user removes the app from the device. This means events sent from the device are assigned to the same user in the Piwik PRO web panel.

When anonymization is enabled, the SDK generates a new visitor ID each time the app starts.

We recommend using the user ID instead of the visitor ID.

You can stil set a visitor ID using the setVisitorId method:

await PiwikProSdk.setVisitorId('0123456789abcdef');
  • visitorId: string – A 16-character hexadecimal string that contains a new visitor ID.

You can get the current visitor ID using the getVisitorId method:

const currentVisitorId = await PiwikProSdk.getVisitorId();

You can also set the visitor ID from a deep link using the setVisitorIdFromDeepLink method. This links a website visitor to an app visitor:

const ok = await PiwikProSdk.setVisitorIdFromDeepLink('https://example.com?pk_vid=0123456789abcdef');

To set how long the visitor ID is kept, use the setVisitorIDLifetime:

await PiwikProSdk.setVisitorIDLifetime(30 * 24 * 60 * 60); // 30 days in seconds

Setting session timeout

A session is a set of user interactions with your app. By default, Analytics closes the session after 30 minutes of inactivity, counted from the last recorded event in the session.

When the user opens the app again, a new session starts.

You can configure the tracker to automatically close the session when the user keeps your app in the background for a set amount of time. That period is defined by the setSessionTimeout method:

await PiwikProSdk.setSessionTimeout(1800);
  • sessionTimeout: number – session timeout in seconds. Default: 1800 (30 minutes).

You can get the current session timeout using the getSessionTimeout method:

const currentSessionTimeout = await PiwikProSdk.getSessionTimeout();

You can also start manually a new session using the startNewSession method:

await PiwikProSdk.startNewSession();

Setting dispatch interval

All tracking events are saved locally and by default they are automatically sent to the server every 30 seconds. You can change this interval using the setDispatchInterval method:

await PiwikProSdk.setDispatchInterval(25);
  • dispatchInterval: number – The dispatch interval in seconds. Default value: 30. If set to 0, events are dispatched immediately. If set to a negative value, events aren’t dispatched automatically and you need to dispatch them manually.

You can get the current dispatch interval using the getDispatchInterval method:

const currentDispatchInterval = await PiwikProSdk.getDispatchInterval();

You can also manually send all queued events to the server using the dispatch method:

await PiwikProSdk.dispatch();

Default custom variables

The SDK, by default, automatically adds device, operating system, and app version information as custom variables:

  • Index 1: Device.
  • Index 2: Operating system.
  • Index 3: App version.

This setting is enabled by default.

To configure custom variables separately, disable this setting and see Tracking custom variables.

You can disable this setting using the setIncludeDefaultCustomVariables method:

await PiwikProSdk.setIncludeDefaultCustomVariables(false);
  • includeDefaultCustomVariables: boolean – Whether default custom variables are added to each tracking event.

You can check the current state using the getIncludeDefaultCustomVariables method:

const includeDefaultCustomVariables = await PiwikProSdk.getIncludeDefaultCustomVariables();

Opt out

You can disable all tracking in the app using the opt-out feature. No events are sent to the server if the opt-out is set. By default, opt-out is disabled and events are tracked.

You can opt out of tracking using the setOptOut method:

await PiwikProSdk.setOptOut(true);
  • optOut: boolean – flag that determines whether opt-out is enabled.

You can check the current state using the getOptOut method:

const currentOptOutState = await PiwikProSdk.getOptOut();

Dry run

The SDK provides a dry-run flag that prevents any data from being sent to Piwik PRO when enabled. Enable dry-run flag when you test or debug an implementation and don't want test data to appear in your Piwik PRO reports.

You can set the dry-run flag using the setDryRun method:

await PiwikProSdk.setDryRun(true);
  • dryRun: boolean – Whether dry run is enabled

You can check the current state using the getDryRun method:

const currentDryRunState = await PiwikProSdk.getDryRun();

Prefixing

Prefixing

For tracking events like screen views, exceptions, or social interactions, the event path in the tracker contains a prefix, such as screen, social, fatal, caught, or exception. You can disable prefixing using the setPrefixing method:

await PiwikProSdk.setPrefixing(false);
  • prefixingEnabled: boolean – Whether prefixing is enabled.

You can check the current prefixing state using the isPrefixingOn method:

const currentPrefixingState = await PiwikProSdk.isPrefixingOn();

Updated about 5 hours ago