Getting started

Our SDK for iOS lets you collect user data from iOS mobile apps. It contains over 50 methods that make it easy to track screen views, goals, ecommerce orders and more. To get started, you need to set up your account in Piwik PRO, install our library and set up the tracker.

📘

Fully compatible with Swift projects

The SDK is written in Objective-C and exposes a Swift-friendly API via NS_SWIFT_NAME. It integrates natively into Swift projects and no Objective-C bridging header is required. All examples in this documentation show both Objective-C and Swift. See Using the SDK from Swift below.

Set up Piwik PRO

Before you install our library for iOS, you need to set up Piwik PRO. Here's what you need to do:

1. Log in to Piwik PRO.
2. Go to Menu > Administration.
3. Navigate to Sites & apps.
4. Click Add a site or app.
5. Type the app name and address and click Save.
6. Set the time zone and currency.
7. Note the site/app ID. The ID is under the app name. Example: 00000000-0000-0000-0000-000000000000.
8. Note your tracking endpoint URL - the base URL where the SDK will send collected events. By default this is the same as your Piwik PRO instance address (for example https://example.piwik.pro). If your organization uses a custom tracking endpoint, check with your Piwik PRO administrator.

Install the library (Swift Package Manager)

Available from 1.1.4

We recommend using Swift Package Manager (SPM) for new projects.

1. Make sure you're using Xcode 12 or newer.
2. If you are migrating a project from CocoaPods, run pod deintegrate first to remove CocoaPods from your Xcode project, then remove any remaining Piwik PRO SDK files.
3. In Xcode, navigate to File > Add Package Dependencies... (or open your project's settings, click Package Dependencies and click the + button).
4. Enter the URL of the Piwik PRO SDK GitHub repository:

https://github.com/PiwikPRO/piwik-pro-sdk-framework-ios

5. Choose the version of Piwik PRO SDK you would like to use. For new projects we recommend the latest version.
6. Click Add Package. Wait for Xcode to finish downloading the Swift Package.
7. In Project Navigator, select your project.
8. In the target list, select the target that builds the application and click Build Settings.
9. Find Other Linker Flags. If the -ObjC flag is not in the list, click + and add it.

Note: If you don't add the -ObjC flag, some parts of our API may not be visible and the SDK may behave incorrectly. For example, you may see error messages such as +[NSString visitorID]: unrecognized selector sent to class 0x1ef0739a8.

Note: Don't use versions below 1.1.4 - Swift Package Manager is only supported from 1.1.4 onwards.

Install the library (CocoaPods)

To install the library on CocoaPods:

1. In your Podfile, add the dependency:

pod 'PiwikPROSDK', '~> VERSION'

Note: Replace VERSION with the latest release name. Example: 1.1.6. (Where to find it?)

2. Run pod install.
3. Import PiwikPROSDK in any source file that uses the SDK.

Set up the tracker

Once the SDK is installed, configure it once during app startup. Provide your tracking endpoint URL (the base URL where the SDK posts events, for example https://example.piwik.pro/) and the site/app ID (Where to find it?).

The SDK works with both UIKit (UIApplicationDelegate) and SwiftUI (App protocol) lifecycles. Pick the example that matches your project.

UIKit lifecycle (AppDelegate)

import UIKit
import PiwikPROSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        PiwikTracker.sharedInstance(siteID: "site-id", baseURL: URL(string: "https://example.piwik.pro")!)
        return true
    }
}

#import <PiwikPROSDK/PiwikPROSDK.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [PiwikTracker sharedInstanceWithSiteID:@"site-id" baseURL:[NSURL URLWithString:@"https://example.piwik.pro"]];
    return YES;
}

@end

SwiftUI lifecycle (App protocol)

For projects using the @main struct App lifecycle (the default for new Xcode projects), configure the tracker in the App initializer:

import SwiftUI
import PiwikPROSDK

@main
struct MyApp: App {
    init() {
        PiwikTracker.sharedInstance(
            siteID: "site-id",
            baseURL: URL(string: "https://example.piwik.pro")!
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

If you also need standard UIApplicationDelegate callbacks (push notifications, deep links via application:openURL:options:, integration with UIKit-only SDKs), add a minimal AppDelegate with @UIApplicationDelegateAdaptor:

import SwiftUI
import UIKit
import PiwikPROSDK

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        PiwikTracker.sharedInstance(
            siteID: "site-id",
            baseURL: URL(string: "https://example.piwik.pro")!
        )
        return true
    }
}

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Note: Call sharedInstance(siteID:baseURL:) once during app startup. Subsequent uses can call PiwikTracker.sharedInstance() to get the configured tracker.

Tip: For more SwiftUI-specific patterns (tracking screens with .onAppear, deep links with .onOpenURL, a reusable view modifier), see Advanced usage > Using the SDK with SwiftUI.

Track your first event

After the tracker is configured you can use the API anywhere in your app. Here's an example of sendView() in both languages:

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

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

Using the SDK from Swift

Short answer: yes, the SDK works natively in Swift projects. You only need import PiwikPROSDK.

Is the SDK compatible with modern Swift-based applications?

Yes. The SDK works with modern Swift-based applications. After installing it with Swift Package Manager, or with CocoaPods exposed to Swift as a module, you can import it directly in Swift with import PiwikPROSDK. The framework annotates every public symbol with NS_SWIFT_NAME, so the API appears in Swift with idiomatic naming. For example:

Does the SDK require an Objective-C bridging header?

No. If you install the SDK with Swift Package Manager, no Objective-C bridging header is required. With CocoaPods, a bridging header is not required when the SDK is exposed to Swift as a module, for example by using use_frameworks! or modular headers.

A bridging header may be needed only in legacy CocoaPods setups where Objective-C pods are integrated as non-modular static libraries, or when you add the SDK source files manually to your Swift target.

For these legacy setups, see Apple's tutorial "Importing Objective-C into Swift". For new projects, we recommend Swift Package Manager.

Minimum Swift / Xcode

Pure-Swift alternative

There is no separate "Swift edition" of the SDK - there is one SDK and it serves both Objective-C and Swift consumers from the same artifact. This is the same pattern Apple uses for its first-party frameworks.

What's next?

• Read Using Piwik PRO SDK for how PiwikTracker fits together after installation.
• Browse the Methods reference to discover all 50+ methods exposed by the SDK.
• Learn about Cross-platform tracking when your app talks to a webview or you handle deep links.
• See Advanced usage for sessions, dispatching, anonymization, opt-out and dry-run options.