iOS/Pods/MatomoTracker/README.md

   1 # MatomoTracker (former PiwikTracker) iOS SDK
   2
   3 The MatomoTracker is an iOS, tvOS and macOS SDK for sending app analytics to a Matomo server. MatomoTracker can be used from Swift and [Objective-C](#objective-c-compatibility).
   4
   5 **Fancy help improve this SDK? Check [this list](https://github.com/matomo-org/matomo-sdk-ios/issues?utf8=✓&q=is%3Aopen%20is%3Aissue%20label%3Adiscussion%20label%3Aswift3) to see what is left and can be improved.**
   6
   7 [![Build Status](https://travis-ci.org/matomo-org/matomo-sdk-ios.svg?branch=develop)](https://travis-ci.org/matomo-org/matomo-sdk-ios)
   8
   9 ## Installation
  10 ### [CocoaPods](https://cocoapods.org)
  11
  12 Use the following in your Podfile.
  13
  14 ```
  15 pod 'MatomoTracker', '~> 5.2'
  16 ```
  17
  18 Then run `pod install`. In every file you want to use the MatomoTracker, don't forget to import the framework with `import MatomoTracker`.
  19
  20 ### Carthage
  21
  22 [Carthage](https://github.com/Carthage/Carthage) is a non intrusive way to install MatomoTracker to your project. It makes no changes to your Xcode project and workspace. Add the following to your Cartfile:
  23
  24 ```
  25 github "matomo-org/matomo-sdk-ios"
  26 ```
  27
  28 ## Usage
  29 ### Matomo Instance
  30
  31 The Matomo iOS SDK doesn't provide a instance of the PiwikTracker. In order to be able to track data you have to create an instance first.
  32
  33 ```Swift
  34 let matomoTracker = MatomoTracker(siteId: "23", baseURL: URL(string: "https://demo2.matomo.org/piwik.php")!)
  35 ```
  36
  37
  38 The `siteId` is the ID that you can get if you [add a website](https://matomo.org/docs/manage-websites/#add-a-website) within the Matomo web interface. The `baseURL` it the URL to your Matomo web instance and has to include the "piwik.php" string.
  39
  40 You can either pass around this instance, or add an extension to the `MatomoTracker` class and add a shared instance property.
  41
  42 ```Swift
  43 extension MatomoTracker {
  44     static let shared: MatomoTracker = MatomoTracker(siteId: "1", baseURL: URL(string: "https://example.com/piwik.php")!)
  45 }
  46 ```
  47
  48 The `siteId` is the ID that you can get if you [add a website](https://matomo.org/docs/manage-websites/#add-a-website) within the Matomo web interface. The `baseURL` is the URL to your Matomo web instance and has to include the "piwik.php" string.
  49
  50 You can use multiple instances within one application.
  51
  52 #### Opting Out
  53
  54 The MatomoTracker SDK supports opting out of tracking. Please use the `isOptedOut` property of the MatomoTracker to define if the user opted out of tracking.
  55
  56 ```Swift
  57 matomoTracker.isOptedOut = true
  58 ```
  59
  60 ### Tracking Page Views
  61
  62 The MatomoTracker can track hierarchical screen names, e.g. screen/settings/register. Use this to create a hierarchical and logical grouping of screen views in the Matomo web interface.
  63
  64 ```Swift
  65 matomoTracker.track(view: ["path","to","your","page"])
  66 ```
  67
  68 You can also set the url of the page.
  69 ```Swift
  70 let url = URL(string: "https://matomo.org/get-involved/")
  71 matomoTracker.track(view: ["community","get-involved"], url: url)
  72 ```
  73
  74 ### Tracking Events
  75
  76 Events can be used to track user interactions such as taps on a button. An event consists of four parts:
  77
  78 - Category
  79 - Action
  80 - Name (optional, recommended)
  81 - Value (optional)
  82
  83 ```Swift
  84 matomoTracker.track(eventWithCategory: "player", action: "slide", name: "volume", value: 35.1)
  85 ```
  86
  87 This will log that the user slid the volume slider on the player to 35.1%.
  88
  89 ### Tracking search
  90
  91 The `MatomoTracker` can track how users use your app internal search. You can track what keywords were searched for, what categories they use, the number of results for a certain search and what searches resulted in no results.
  92
  93 ```Swift
  94 matomoTracker.trackSearch(query: "Best mobile tracking", category: "Technology", resultCount: 15)
  95 ```
  96
  97 ### Custom Dimension
  98
  99 The Matomo 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 are [properly installed and configured](https://matomo.org/docs/custom-dimensions/). You will need the `ID` of your configured Dimension.
 100
 101 After that you can set a new Dimension,
 102
 103 ```Swift
 104 matomoTracker.set(value: "1.0.0-beta2", forIndex: 1)
 105 ```
 106
 107 or remove an already set dimension.
 108
 109 ```Swift
 110 matomoTracker.remove(dimensionAtIndex: 1)
 111 ```
 112
 113 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.
 114
 115 ### Custom User ID
 116
 117 To add a [custom User ID](https://matomo.org/docs/user-id/), simply set the value you'd like to use on the `visitorId` field of the tracker:
 118
 119 ```Swift
 120 matomoTracker.visitorId = "coolUsername123"
 121 ```
 122
 123 All future events being tracked by the SDK will be associated with this userID, as opposed to the default UUID created for each Visitor.
 124
 125 ### Campaign Tracking
 126
 127 The Matomo iOS SDK supports [campaign tracking](https://matomo.org/docs/tracking-campaigns/).
 128
 129 ```Swift
 130 matomoTracker.trackCampaign(name: @"campaign_name", keyword: @"campaign_keyword")
 131 ```
 132
 133 ### Content Tracking
 134
 135 The Matomo iOS SDK supports [content tracking](https://matomo.org/docs/content-tracking/).
 136
 137 ```Swift
 138 matomoTracker.trackContentImpression(name: "preview-liveaboard", piece: "Malaysia", target: "https://dummy.matomo.org/liveaboard/malaysia")
 139 matomoTracker.trackContentInteraction(name: "preview-liveaboard", interaction: "tap", piece: "Malaysia", target: "https://dummy.matomo.org/liveaboard/malaysia")
 140 ```
 141
 142 ## Advanced Usage
 143 ### Manual dispatching
 144
 145 The MatomoTracker will dispatch events every 30 seconds automatically. If you want to dispatch events manually, you can use the `dispatch()` function. You can, for example, dispatch whenever the application enter the background.
 146
 147 ```Swift
 148 func applicationDidEnterBackground(_ application: UIApplication) {
 149   matomoTracker.dispatch()
 150 }
 151 ```
 152
 153 ### Session Management
 154
 155 The MatomoTracker starts a new session whenever the application starts. If you want to start a new session manually, you can use the `startNewSession()` function. You can, for example, start a new session whenever the user enters the application.
 156
 157 ```Swift
 158 func applicationWillEnterForeground(_ application: UIApplication) {
 159   matomoTracker.startNewSession()
 160 }
 161 ```
 162
 163 ### Logging
 164
 165 The MatomoTracker per default logs `warning` and `error` messages to the console. You can change the `LogLevel`.
 166
 167 ```Swift
 168 matomoTracker.logger = DefaultLogger(minLevel: .verbose)
 169 matomoTracker.logger = DefaultLogger(minLevel: .debug)
 170 matomoTracker.logger = DefaultLogger(minLevel: .info)
 171 matomoTracker.logger = DefaultLogger(minLevel: .warning)
 172 matomoTracker.logger = DefaultLogger(minLevel: .error)
 173 ```
 174
 175 You can also write your own `Logger` and send the logs wherever you want. Just write a new class/struct and let it conform to the `Logger` protocol.
 176
 177 ### Custom User Agent
 178 The `MatomoTracker` will create a default user agent derived from the WKWebView user agent.
 179 You can instantiate the `MatomoTracker` using your own user agent.
 180
 181 ```Swift
 182 let matomoTracker = MatomoTracker(siteId: "5", baseURL: URL(string: "http://your.server.org/path-to-matomo/piwik.php")!, userAgent: "Your custom user agent")
 183 ```
 184
 185 ### Objective-C compatibility
 186
 187 Version 4 (and higher) 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 older [version 3](https://github.com/matomo-org/matomo-sdk-ios/tree/version-3). Using the Swift SDK from Objective-C should be pretty straight forward.
 188
 189 ```objc
 190 MatomoTracker *matomoTracker = [[MatomoTracker alloc] initWithSiteId:@"5" baseURL:[NSURL URLWithString:@"http://your.server.org/path-to-matomo/piwik.php"] userAgent:nil];
 191 [matomoTracker trackWithView:@[@"example"] url:nil];
 192 [matomoTracker trackWithEventWithCategory:@"category" action:@"action" name:nil number:nil url:nil];
 193 [matomoTracker dispatch];
 194 matomoTracker.logger = [[DefaultLogger alloc] initWithMinLevel:LogLevelVerbose];
 195 ```
 196
 197 ### Sending custom events
 198
 199 Instead of using the convenience functions for events and screen views for example you can create your event manually and even send custom tracking parameters. This feature isn't available from Objective-C.
 200
 201 ```Swift
 202 func sendCustomEvent() {
 203   guard let matomoTracker = MatomoTracker.shared else { return }
 204   let downloadURL = URL(string: "https://builds.matomo.org/piwik.zip")!
 205   let event = Event(tracker: matomoTracker, action: ["menu", "custom tracking parameters"], url: downloadURL, customTrackingParameters: ["download": downloadURL.absoluteString])
 206   matomoTracker.track(event)
 207 }
 208 ```
 209
 210 All custom events will be URL-encoded and dispatched along with the default Event parameters. Please read the [Tracking API Documentation](https://developer.matomo.org/api-reference/tracking-api) for more information on which parameters can be used.
 211
 212 Also: You cannot override Custom Parameter keys that are already defined by the Event itself. If you set those keys in the `customTrackingParameters` they will be discarded.
 213
 214 ### Automatic url generation
 215
 216 You can define the url property on every `Event`. If none is defined, the SDK will try to generate a url based on the `contentBase` of the `MatomoTracker`. If the `contentBase` is nil, no url will be generated. If the `contentBase` is set, it will append the actions of the event to it and use it as the url. Per default the `contentBase` is generated using the application bundle identifier. For example `http://org.matomo.skd`. This will not result in resolvable urls, but enables the backend to analyse and structure them.
 217
 218 ### Event dispatching
 219
 220 Whenever you track an event or a page view it is stored in memory first. In every dispatch run a batch of those events are sent to the server. If the device is offline or the server doesn't respond these events will be kept and resent at a later time. Events currently aren't stored on disk and will be lost if the application is terminated. [#137](https://github.com/matomo-org/matomo-sdk-ios/issues/137)
 221
 222 ## Contributing
 223 Please read [CONTRIBUTING.md](https://github.com/matomo-org/matomo-sdk-ios/blob/swift3/CONTRIBUTING.md) for details.
 224
 225 ## ToDo
 226 ### These features aren't implemented yet
 227
 228 - Basic functionality
 229   - [Persisting non dispatched events](https://github.com/matomo-org/matomo-sdk-ios/issues/137)
 230 - Tracking of more things
 231   - Social Interactions
 232   - Goals and Conversions
 233   - Outlinks
 234   - Downloads
 235   - [Ecommerce Transactions](https://github.com/matomo-org/matomo-sdk-ios/issues/110)
 236   - Content Impressions / Content Interactions
 237 - Customizing the tracker
 238   - set the dispatch interval
 239   - use different dispatchers (Alamofire)
 240
 241 ## License
 242
 243 MatomoTracker is available under the [MIT license](LICENSE.md).