Docs

Cross-platform tracking

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

You can also track how users navigate from a website to an app using deep links.

Tracking users transitioning from the mobile browser to the mobile application

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"]];

The most natural place to do this is in your application:openURL:options: delegate callback or in your 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, and false if the URL is missing or cannot be parsed, pk_vid is missing, the parameter value is shorter than 16 characters, or the first 16 characters are not valid lowercase hexadecimal (same rules as setVisitorID). See setVisitorIdFrom for full detail.

Tracking users transitioning from the mobile application to the web view

If the Session Hash feature is enabled, or if you want more accurate tracking, set the same user agent in your WKWebView as 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 (for example app and web), depending on your analytics configuration. The sessionHash property tells the SDK whether each event should ask for Session Hash on, off, or leave the choice to Privacy app settings in Piwik PRO; the choice is sent as sh, and the SDK remembers it between 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. Default when nothing has been stored yet.
  • .notSet: omits sh so Privacy settings for the app in Piwik PRO decide processing.

You can read the current value the same way:

let currentValue = PiwikTracker.sharedInstance()?.sessionHash
SessionHash currentValue = [PiwikTracker sharedInstance].sessionHash;

The default value is .disabled.

If visitorIDLifetime is enabled (greater than zero), the SDK forces Session Hash off (sh=0) on every analytics event for 31 minutes after the current visitor ID was last set, including right after the ID is replaced because it expired. In that window sessionHash has no effect; the SDK always sends sh=0. After 31 minutes, sessionHash behaves as described above again. See sessionHash for full detail.

Updated 14 days ago