Using Piwik PRO SDK

Tracking is centered on PiwikTracker. Configure it once at startup, then call PiwikTracker.sharedInstance() from your app. See Getting started.

Data anonymization

Anonymization lets you respect visitor consent while still collecting aggregated analytics data.

When isAnonymizationEnabled is true, which is the default, the SDK doesn’t collect personal data, such as user ID, user email, or device ID. The SDK also generates a new visitor ID each time the app starts, when it first needs one in that run.

Turn off anonymization only when your privacy policy allows identified tracking.

PiwikTracker.sharedInstance()?.isAnonymizationEnabled = false

[PiwikTracker sharedInstance].isAnonymizationEnabled = NO;

Tracking screen views

Requires Analytics

During a valid session you can track screen views. The SDK turns the screen name, or hierarchy, into a synthetic URL for the collector. By default, it prefixes screen segment. To turn this off, set isPrefixingEnabled = false. See isPrefixingEnabled.

Single screen:

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    PiwikTracker.sharedInstance()?.sendView(view: "your_screen_path")
}

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [[PiwikTracker sharedInstance] sendView:@"your_screen_path"];
}

view (required)
Logical screen name or path segment.

Hierarchical path in one event, from parent to child:

PiwikTracker.sharedInstance()?.sendViews(views: ["parent", "child"])

[[PiwikTracker sharedInstance] sendViews:@[@"parent", @"child"]];

When you build the UI with View and .onAppear, follow the patterns in Advanced usage: Using the SDK with SwiftUI.

Tracking custom events

Requires Analytics

Use sendEvent(category:action:name:value:path:) for taps, gestures, gameplay actions, and other interactions.

PiwikTracker.sharedInstance()?.sendEvent(
    category: "category",
    action: "action",
    name: "label",
    value: 1000,
    path: "main/actionScreen"
)

[[PiwikTracker sharedInstance]
    sendEventWithCategory:@"category"
                   action:@"action"
                     name:@"label"
                    value:@1000
                     path:@"main/actionScreen"];

category (required): Groups the event, such as gestures or feature areas.
action (required): Specific action inside the category.
name (optional): Label, such as which control was used.
value (optional): Numeric value.
path (optional): Path segment for the synthetic URL. When omitted, the SDK reuses the last generated page URL. See sendEvent. Read more: custom events overview, event tracking guide.

Tracking exceptions

Requires Analytics

Use sendException(description:) to track handled errors in Analytics. The event category is Exception.

This method isn’t a full crash reporter.

do {
    // work
} catch {
    PiwikTracker.sharedInstance()?.sendException(description: "Content download error")
}

[[PiwikTracker sharedInstance] sendExceptionWithDescription:@"Content download error"];

description (required)
Short text. The SDK truncates it to 50 characters.

Tracking social interactions

Requires Analytics

PiwikTracker.sharedInstance()?.sendSocialInteraction(action: "like", network: "Facebook")

[[PiwikTracker sharedInstance] sendSocialInteractionWithAction:@"like" network:@"Facebook"];

action (required)
Interaction type. Example: like, share. Read more: sendSocialInteraction).
network (required)
Social product name. Example: Facebook, Instagram.

Tracking deep links and campaigns

Requires Analytics

Measure campaigns built with the Campaign URL Builder. Pass the full URL, including the query string, to sendCampaign(url:).

Campaign parameters attach to the next analytics event, then clear.

PiwikTracker.sharedInstance()?.sendCampaign(
    url: "https://www.example.com?pk_campaign=Email-SummerDeals&pk_keyword=LearnMore"
)

[[PiwikTracker sharedInstance]
    sendCampaign:@"https://www.example.com?pk_campaign=Email-SummerDeals&pk_keyword=LearnMore"];

For deep links and pk_vid used in cross-device visitor ID tracking, see cross-platform tracking and setVisitorIdFrom.

Tracking downloads

Requires Analytics

PiwikTracker.sharedInstance()?.sendDownload(url: "https://your.server.com/bonusmap.zip")

[[PiwikTracker sharedInstance] sendDownload:@"https://your.server.com/bonusmap.zip"];

url (required)
Resource the user downloads through your app.

Tracking application installs

Requires Analytics

Use applicationInstall() to track app installations. It runs at most onnce per installation. The older sendApplicationDownload() is deprecated. It runs at most once per app version.

PiwikTracker.sharedInstance()?.applicationInstall()

[[PiwikTracker sharedInstance] applicationInstall];

Returns true if a new install event was queued and false if this install was already tracked. See applicationInstall().

Call this method immediately after configuring the tracker. To track app updates, call applicationUpdate() during app startup.

Tracking outlinks

Requires Analytics

PiwikTracker.sharedInstance()?.sendOutlink(url: "https://partner.example/path")

[[PiwikTracker sharedInstance] sendOutlink:@"https://partner.example/path"];

url (required)
The destination opened from your app.

Tracking search operations

Requires Analytics

PiwikTracker.sharedInstance()?.sendSearch(
    keyword: "Space",
    category: "Movies",
    numberOfHits: 3
)

[[PiwikTracker sharedInstance]
    sendSearchWithKeyword:@"Space"
                 category:@"Movies"
             numberOfHits:@3];

keyword (required)
category (optional)
numberOfHits (optional)
The number of results shown. The SDK includes the hit count only when the value is zero or greater. See sendSearch.

Tracking content impressions and interactions

Requires Analytics

Impression:

PiwikTracker.sharedInstance()?.sendContentImpression(
    name: "iOS content impression",
    piece: "banner",
    target: "https://www.example.com/",
    url: nil
)

[[PiwikTracker sharedInstance]
    sendContentImpressionWithName:@"iOS content impression"
                          piece:@"banner"
                         target:@"https://www.example.com/"
                            url:nil];

Interaction (e.g. tap):

PiwikTracker.sharedInstance()?.sendContentInteraction(
    name: "iOS content impression",
    interaction: "click",
    piece: "banner",
    target: "https://www.example.com/"
)

[[PiwikTracker sharedInstance]
    sendContentInteractionWithName:@"iOS content impression"
                      interaction:@"click"
                            piece:@"banner"
                           target:@"https://www.example.com/"];

name (required)
The name of the tracked content.
interaction (required)
The type of interaction with the content, for example, a click, tap.
piece / target (optional)
Additional information about the content or interaction.

Tracking goals

Requires Analytics

Call sendGoal(ID:revenue:) to track manual conversions. You can also provide an optional currencyCode.

If you've configured goals with automatic rules in Analytics, you may not need to call this method. What is a goal?

PiwikTracker.sharedInstance()?.sendGoal(ID: "27ecc5e3-8ae0-40c3-964b-5bd8ee3da059", revenue: 20)

[[PiwikTracker sharedInstance] sendGoalWithID:@"27ecc5e3-8ae0-40c3-964b-5bd8ee3da059" revenue:@20];

Tracking ecommerce (V2)

Use EcommerceProducts and Product (or addProductWithSku:... helper methods) with the V2 methods below.
The product fields are described in detail on each method page. In summary:

sku (required)
The product SKU.

name (optional)
The product name.

category (optional)
A string or an array of up to 5 category values.

price (optional)
The product price.

quantity (optional)
The product quantity.

brand (optional)
The product brand.

variant (optional)
The product variant.

customDimensions (optional)
Product-level custom dimensions.

Product detail view

ecommerceProductDetailView(products:)

let products = EcommerceProducts()
products.addProduct(
    sku: "craft-311",
    name: "Unicorn Iron on Patch",
    category: ["Crafts & Sewing", "Toys"],
    price: "49.90",
    quantity: 3,
    brand: "DMZ",
    variant: "blue",
    customDimensions: [1: "coupon-2020", 2: "20%"]
)
PiwikTracker.sharedInstance()?.ecommerceProductDetailView(products: products)

Add to cart

ecommerceAddToCart(products:)

PiwikTracker.sharedInstance()?.ecommerceAddToCart(products: products)

Remove from cart

ecommerceRemoveFromCart(products:)

PiwikTracker.sharedInstance()?.ecommerceRemoveFromCart(products: products)

Cart update

ecommerceCartUpdate(products:grandTotal:)

PiwikTracker.sharedInstance()?.ecommerceCartUpdate(products: products, grandTotal: "60000.78")

Order (conversion)

ecommerceOrder(products:orderId:grandTotal:subTotal:tax:shipping:discount:)

PiwikTracker.sharedInstance()?.ecommerceOrder(
    products: products,
    orderId: "order-3415",
    grandTotal: "180.00",
    subTotal: "120.00",
    tax: "39.60",
    shipping: "60.00",
    discount: "18.00"
)

[[PiwikTracker sharedInstance] ecommerceOrder:products
                                      orderId:@"order-3415"
                                   grandTotal:@"180.00"
                                     subTotal:@"120.00"
                                          tax:@"39.60"
                                     shipping:@"60.00"
                                     discount:@"18.00"];

Build products with EcommerceProducts.addProduct(sku:...) (as below), Product.productWithSku(...) + add(product:), or addProductWithSku:.... All are documented on ecommerceOrder() and sibling pages.

Tracking ecommerce transactions (legacy)

Requires Analytics

Deprecated: prefer ecommerce V2 above (ecommerceOrder, cart actions, etc.). sendTransaction(transaction:) / PiwikTransaction remain only for legacy integrations.

Tracking custom variables

The feature is deprecated; use custom dimensions for new work.

Requires Analytics

setCustomVariable(index:name:value:scope:) supports .visit and .action scopes. With includeDefaultCustomVariable on (default), do not use visit indexes 1-3 for your own variables; use > 3 for visit scope, or any ≥ 1 for action scope; see the method page and Advanced usage.

PiwikTracker.sharedInstance()?.setCustomVariable(
    index: 4,
    name: "User type",
    value: "subscriber",
    scope: .visit
)

[[PiwikTracker sharedInstance] setCustomVariableForIndex:4
                                                      name:@"User type"
                                                     value:@"subscriber"
                                                     scope:CustomVariableScopeVisit];

Tracking custom dimensions

Requires Analytics

Set dimensions before the hit that should carry them using setCustomDimension(identifier:value:). identifier is the dimension ID from Piwik PRO (integer ≥ 1).

PiwikTracker.sharedInstance()?.setCustomDimension(identifier: 1, value: "visit")
PiwikTracker.sharedInstance()?.setCustomDimension(identifier: 2, value: "dashboard")
PiwikTracker.sharedInstance()?.sendView(view: "Home screen")

[[PiwikTracker sharedInstance] setCustomDimensionForID:1 value:@"visit"];
[[PiwikTracker sharedInstance] setCustomDimensionForID:2 value:@"dashboard"];
[[PiwikTracker sharedInstance] sendView:@"Home screen"];

After dimensions are attached to a request, the SDK clears them. Set them again before each tracking call that should include them (method notes).

Tracking user profile attributes

Requires Audience Manager

Deprecated: Audience Manager is sunset; these APIs remain documented for legacy apps only. Learn more.

sendAudienceManagerAttribute(name:value:) queues a standalone Audience Manager update. Set userID and userEmail when anonymization allows, so profiles can merge. See the method page.

PiwikTracker.sharedInstance()?.userID = "crm-123"
PiwikTracker.sharedInstance()?.sendAudienceManagerAttribute(name: "food", value: "pizza")

[PiwikTracker sharedInstance].userID = @"crm-123";
[[PiwikTracker sharedInstance] sendProfileAttributeWithName:@"food" value:@"pizza"];

Reading user profile attributes

Requires Audience Manager

Deprecated: same note as above.

audienceManagerGetProfileAttributes is asynchronous; you only receive attributes allowed for API access in Audience Manager.

PiwikTracker.sharedInstance()?.audienceManagerGetProfileAttributes { profileAttributes, error in
    // handle profileAttributes or error
}

[[PiwikTracker sharedInstance] audienceManagerGetProfileAttributes:^(NSDictionary *profileAttributes, NSError * _Nullable error) {
    // handle profileAttributes or error
}];

Checking audience membership

Requires Audience Manager

Deprecated: same note as above.

Use checkMembership(withAudienceID:completionBlock:); see the method page for parameters and the completion handler.

PiwikTracker.sharedInstance()?.checkMembership(withAudienceID: "ABC123") { isMember, error in
    // use isMember or handle error
}

[[PiwikTracker sharedInstance]
    checkMembershipWithAudienceID:@"ABC123"
                 completionBlock:^(BOOL isMember, NSError * _Nullable error) {
                     // use isMember or handle error
                 }];

Full API reference

Every signature, parameter table and edge case lives in the Methods index and linked pages.