Repository files navigation

The PiwikTracker is an iOS, tvOS and macOS SDK for sending app analytics to a Piwik server.

Fancy help improving this SDK? Checkthis list to see what is left and can be improved.

Use the following in your Podfile.

pod 'PiwikTracker', '~> 4.1.0'

Then runpod install. In every file you want to use the PiwikTracker, don't forget to import the framwork withimport PiwikTracker.

Befor the first usage, the PiwikTracker has to be configured. This is best to be done in theapplication(_:, didFinishLaunchingWithOptions:) method in theAppDelegate.

PiwikTracker.configureSharedInstance(withSiteID: "5", baseURL: URL(string: "http://your.server.org/path-to-piwik/piwik.php")!)

ThesiteId is the id that you can get if youadd a website within the Piwik web interface. ThebaseURL it the URL to your Piwik web instance and has to include the "piwik.php" string.

The PiwikTracker SDK supports opting out of tracking. Please use theisOptedOut property of the PiwikTracker to define if the user opted out of tracking.

PiwikTracker.shared?.isOptedOut = true

The PiwikTracker can track hierarchical screen names, e.g. screen/settings/register. Use this to create a hierarchical and logical grouping of screen views in the Piwik web interface.

PiwikTracker.shared?.track(view: ["path","to","your","page"])

You can also set the url of the page.

let url = URL(string: "https://piwik.org/get-involved/")PiwikTracker.shared?.track(view: ["community","get-involved"], url: url)

Events can be used to track user interactions such as taps on a button. An event consists of four parts:

• Category
• Action
• Name (optional, recommended)
• Value (optional)

PiwikTracker.shared?.track(eventWithCategory: "player", action: "slide", name: "volume", value: 35.1)

This will log that the user slided the volume slider on the player to 35.1%.

The Piwik SDK currently supports Custom Dimensions for the Visit Scope. Using Custom Dimensions you can add properties to the whole visit, such as "Did the user finish the tutorial?", "Is the user a paying user?" or "Which version of the Application is being used?" and such. Before sending custom dimensions please make sure Custom Dimensions areproperly installed and configured. You will need theID of your configured Dimension.

After that you can set a new Dimension,

PiwikTracker.shared?.set(value: "1.0.0-beta2", forIndex: 1)

or remove an already set dimension.

PiwikTracker.shared?.remove(dimensionAtIndex: 1)

Dimensions in the Visit Scope will be sent along every Page View or Event. Custom Dimensions are not persisted by the SDK and have to be re-configured upon application startup.

The PiwikTracker will dispatch events every 30 seconds automatically. If you want to dispatch events manually, you can use thedispatch() function. You can, for example, dispatch whenever the application enter the background.

func applicationDidEnterBackground(_ application: UIApplication) {  PiwikTracker.shared?.dispatch()}

The PiwikTracker starts a new session whenever the application starts. If you want to start a new session manually, you can use thestartNewSession() function. You can, for example, start a new session whenever the user enters the application.

func applicationWillEnterForeground(_ application: UIApplication) {  PiwikTracker.shared?.startNewSession()}

The PiwikTracker per default loggswarning anderror messages to the console. You can change theLogLevel.

PiwikTracker.shared?.logger = DefaultLogger(minLevel: .verbose)PiwikTracker.shared?.logger = DefaultLogger(minLevel: .debug)PiwikTracker.shared?.logger = DefaultLogger(minLevel: .info)PiwikTracker.shared?.logger = DefaultLogger(minLevel: .warning)PiwikTracker.shared?.logger = DefaultLogger(minLevel: .error)

You can also write your ownLogger and send the logs whereever you want. Just write a new class/struct an let it conform to theLogger protocol.

ThePiwikTracker will create a default user agent derived from the WKWebView user agent. This is why you should always instantiate and configure thePiwikTracker on the main thread.You can instantiate thePiwikTracker using your own user agent.

PiwikTracker.configureSharedInstance(withSiteID: "5", baseURL: URL(string: "http://your.server.org/path-to-piwik/piwik.php")!, userAgent: "Your custom user agent")

Version 4 of this SDK is written in Swift, but you can use it in your Objective-C project as well. If you don't want to update you can still use the unsupported olderversion 3. Using the Swift SDK from Objective-C should be pretty straight forward.

[PiwikTracker configureSharedInstanceWithSiteID:@"5" baseURL:[NSURL URLWithString:@"http://your.server.org/path-to-piwik/piwik.php"] userAgent:nil];[PiwikTracker shared] trackWithView:@[@"example"] url:nil];[[PiwikTracker shared] trackWithEventWithCategory:@"category" action:@"action" name:nil number:nil];[[PiwikTracker shared] dispatch];

Please readCONTRIBUTING.md for details.

• Basic functionality
  • Sessions
  • OptOut
  • Persisting non dispatched events
  • Custom Dimensions (Action Scope is not implemented yet)
• Tracking of more things
  • Exceptions
  • Social Interactions
  • Search
  • Goals and Conversions
  • Outlinks
  • Downloads
  • Ecommerce Transactions
  • Campaigns
  • Content Impressions / Content Interactions
• Customizing the tracker
  • Custom User Agent
  • userID
  • add prefixing? (The objc-SDK had a prefixing functionality)
  • set the dispatch interval
  • use different dispatchers (Alamofire)

PiwikTracker is available under theMIT license.