Docs

Using Piwik PRO SDK

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

Data anonymization

Anonymization lets you respect consent while still collecting aggregated analytics. When isAnonymizationEnabled is true (the default), personal data such as user ID, user email and device ID are not collected, and the SDK generates a new visitor ID each time the application 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 a screen segment is prefixed. Disable that with 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 (parent → 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 (e.g. gestures vs. feature areas).
  • action (required): specific action inside the category.
  • name (optional): label, e.g. 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.

More background: Custom Events Overview, Event tracking guide.

Tracking exceptions

Requires Analytics

Use sendException(description:) for handled errors you want in Analytics (category Exception). This is not 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 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 (see 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 query) to sendCampaign(url:). 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"];

Deep links and pk_vid for cross-device visitor ID: Cross-platform tracking, 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

Prefer applicationInstall() (once per installation). The older sendApplicationDownload() is deprecated (fires at most once per app version).

PiwikTracker.sharedInstance()?.applicationInstall()
[[PiwikTracker sharedInstance] applicationInstall];

Returns true if a new install event was queued; false if this install was already tracked, see applicationInstall(). Call it right after tracker configuration; use applicationUpdate() on the same lifecycle for version bumps.

Tracking outlinks

Requires Analytics

PiwikTracker.sharedInstance()?.sendOutlink(url: "https://partner.example/path")
[[PiwikTracker sharedInstance] sendOutlink:@"https://partner.example/path"];
  • url (required): 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): pass the number of results shown; the SDK only includes the hit count for zero or positive values, 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)
  • interaction (required): e.g. click, tap
  • piece / target (optional)

Tracking goals

Requires Analytics

Call sendGoal(ID:revenue:) (and optional currencyCode) for manual conversions. Goals configured with automatic rules in Analytics may not need this. 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 e-commerce (V2)

Use EcommerceProducts and Product (or addProductWithSku:... helpers) with the V2 methods below. Product fields match the tables on each method page; in short:

  • sku (required)
  • name, category (string or array of up to 5), price, quantity, brand, variant, customDimensions (optional)

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.

Updated 14 days ago