Getting started

Our iOS SDK lets you collect analytics data from iOS apps. It includes more than 50 methods for tracking screen views, goals, ecommerce orders, and more.

To get started, set up your Piwik PRO account, install the SDK, and configure 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 works > natively in Swift projects and doesn't require an Objective-C bridging header.

All examples in this documentation include both Objective-C and Swift. See Using the SDK from Swift.

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 sends 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 with Swift Package Manager (SPM)

Available in version 1.1.4 and later.

For new projects, we recommend Swift Package Manager.

1. Make sure you're using Xcode 12 or newer.
2. If you're 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 want 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 isn't in the list, click + to 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: Swift Package Manager is supported in version 1.1.4 and later. Don't use earlier versions.

Install the library (CocoaPods)

To install the library on CocoaPods, follow these steps:

1. In your Podfile, add the dependency:

pod 'PiwikPROSDK', '~> VERSION'

Note: Replace VERSION with the latest SDK version. Example: 1.1.6. (View the Piwik PRO SDK on CocoaPods)

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

Set up the tracker

After installing the SDK, configure it once during app startup. Provide your tracking endpoint URL (the base URL where the SDK sends events, for example https://example.piwik.pro/) and your site or app ID. (Find your site ID.

The SDK works with both UIKit (UIApplicationDelegate) and SwiftUI (App) lifecycles. Choose 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 that use 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. After that, use PiwikTracker.sharedInstance() to access the configured tracker.

Tip: For more SwiftUI-specific patterns, including screen tracking screens with .onAppear, deep links with .onOpenURL, and 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

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 the SDK 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, you don't need an Objective-C bridging header. With CocoaPods, you also don't need one when the SDK is exposed to Swift as a module, for example, when using use_frameworks! or modular headers.

A bridging header may be needed 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

Is there a separate Swift SDK?

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.