Cross-platform tracking

Cross-platform tracking lets you recognize the same visitor across both an app and a website. It's useful when a visitor moves from a webview in your app to your website in a mobile browser, or follows a deep link from your website to your app.

Tracking visitors from a website to an app

Use setVisitorIdFrom(deepLink:) or setVisitorIdFrom(url:) to set the visitor ID from the pk_vid query parameter. The deep link must contain pk_vid.

let stringResult = PiwikTracker.sharedInstance()?.setVisitorIdFrom(deepLink: "piwik://example?pk_vid=25a3c7d060a94360") ?? false

let urlResult = PiwikTracker.sharedInstance()?.setVisitorIdFrom(url: URL(string: "piwik://example?pk_vid=35a3c7d060a94360")!) ?? false

BOOL result = [[PiwikTracker sharedInstance] setVisitorIdFromDeepLink:@"piwik://example?pk_vid=25a3c7d060a94360"];

BOOL result = [[PiwikTracker sharedInstance] setVisitorIdFromURL:[NSURL URLWithString:@"piwik://example?pk_vid=35a3c7d060a94360"]];

Call this from your application:openURL:options: delegate callback or SceneDelegate deep-link handler:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    return PiwikTracker.sharedInstance()?.setVisitorIdFrom(url: url) ?? false
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    return [[PiwikTracker sharedInstance] setVisitorIdFromURL:url];
}

When you use the @main App entry point, attach the .onOpenURL modifier to your root view. Initialize the tracker first, for example in App.init(), as in Advanced usage.

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    PiwikTracker.sharedInstance()?.setVisitorIdFrom(url: url)
                }
        }
    }
}

The method returns true if the visitor ID was updated from pk_vid.

It returns false if:

• The URL is missing or can't be parsed.
• pk_vid is missing.
• The parameter value is shorter than 16 characters.
• The first 16 characters aren't valid lowercase hexadecimal values, following the same rules as setVisitorID.

See setVisitorIdFrom for full detail.

Tracking visitors from a mobile application to a website

If the session hash feature is enabled, or if you need more accurate tracking, set the same user agent in your WKWebView that the SDK uses. The userAgent property returns the default user agent built by the Piwik PRO SDK.

import WebKit
import UIKit

// UIViewController subclass: `view` is the controller's root view
let userAgent = PiwikTracker.sharedInstance()?.userAgent

let config = WKWebViewConfiguration()
let webView = WKWebView(frame: view.bounds, configuration: config)
webView.customUserAgent = userAgent

#import <WebKit/WebKit.h>

NSString *userAgent = [PiwikTracker sharedInstance].userAgent;

WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
webView.customUserAgent = userAgent;

Session hash

Session hash adds session-level context so Piwik PRO can match activity more reliably across environments, such as app and web. How this works depends on your analytics configuration.

The sessionHash property tells the SDK how to handle session hash for each event. It can:

• Send sh=1.
• Send sh=0.
• Omit sh and let the Privacy app settings in Piwik PRO decide how to process the event.

The SDK remembers this setting between app launches.

PiwikTracker.sharedInstance()?.sessionHash = .enabled

[PiwikTracker sharedInstance].sessionHash = Enabled;

To omit sh and let Piwik PRO privacy defaults apply:

PiwikTracker.sharedInstance()?.sessionHash = .notSet

[PiwikTracker sharedInstance].sessionHash = NotSet;

The SessionHash enum has three values:

• .enabled: Sends sh=1.
• .disabled: Sends sh=0. This is the default when no value has been stored yet.
• .notSet: Omits sh, so the privacy app settings in Piwik PRO decide how to process the event.

You can read the current value the same way:

let currentValue = PiwikTracker.sharedInstance()?.sessionHash

SessionHash currentValue = [PiwikTracker sharedInstance].sessionHash;

The default value is .disabled.

When visitorIDLifetime is enabled (greater than zero), the SDK always sends sh=0 for 31 minutes after a visitor ID is set.

This also applies when the visitor ID is replaced after it expires.

During that window sessionHash has no effect. After 31 minutes, sessionHash works as described above.

See sessionHash for details.