iOS/Pods/MatomoTracker/MatomoTracker/MatomoTracker.swift

   1 import Foundation
   2
   3 /// The Matomo Tracker is a Swift framework to send analytics to the Matomo server.
   4 ///
   5 /// ## Basic Usage
   6 /// * Use the track methods to track your views, events and more.
   7 final public class MatomoTracker: NSObject {
   8
   9     /// Defines if the user opted out of tracking. When set to true, every event
  10     /// will be discarded immediately. This property is persisted between app launches.
  11     @objc public var isOptedOut: Bool {
  12         get {
  13             return matomoUserDefaults.optOut
  14         }
  15         set {
  16             matomoUserDefaults.optOut = newValue
  17         }
  18     }
  19
  20     /// Will be used to associate all future events with a given userID. This property
  21     /// is persisted between app launches.
  22     @objc public var visitorId: String? {
  23         get {
  24             return matomoUserDefaults.visitorUserId
  25         }
  26         set {
  27             matomoUserDefaults.visitorUserId = newValue
  28             visitor = Visitor.current(in: matomoUserDefaults)
  29         }
  30     }
  31
  32     internal var matomoUserDefaults: MatomoUserDefaults
  33     private let dispatcher: Dispatcher
  34     private var queue: Queue
  35     internal let siteId: String
  36
  37     internal var dimensions: [CustomDimension] = []
  38
  39     internal var customVariables: [CustomVariable] = []
  40
  41     /// This logger is used to perform logging of all sorts of Matomo related information.
  42     /// Per default it is a `DefaultLogger` with a `minLevel` of `LogLevel.warning`. You can
  43     /// set your own Logger with a custom `minLevel` or a complete custom logging mechanism.
  44     @objc public var logger: Logger = DefaultLogger(minLevel: .warning)
  45
  46     /// The `contentBase` is used to build the url of an Event, if the Event hasn't got a url set.
  47     /// This autogenerated url will then have the format <contentBase>/<actions>.
  48     /// Per default the `contentBase` is http://<Application Bundle Name>.
  49     /// Set the `contentBase` to nil, if you don't want to auto generate a url.
  50     @objc public var contentBase: URL?
  51
  52     internal static var _sharedInstance: MatomoTracker?
  53
  54     /// Create and Configure a new Tracker
  55     ///
  56     /// - Parameters:
  57     ///   - siteId: The unique site id generated by the server when a new site was created.
  58     ///   - queue: The queue to use to store all analytics until it is dispatched to the server.
  59     ///   - dispatcher: The dispatcher to use to transmit all analytics to the server.
  60     required public init(siteId: String, queue: Queue, dispatcher: Dispatcher) {
  61         self.siteId = siteId
  62         self.queue = queue
  63         self.dispatcher = dispatcher
  64         self.contentBase = URL(string: "http://\(Application.makeCurrentApplication().bundleIdentifier ?? "unknown")")
  65         self.matomoUserDefaults = MatomoUserDefaults(suiteName: "\(siteId)\(dispatcher.baseURL.absoluteString)")
  66         self.visitor = Visitor.current(in: matomoUserDefaults)
  67         self.session = Session.current(in: matomoUserDefaults)
  68         super.init()
  69         startNewSession()
  70         startDispatchTimer()
  71     }
  72
  73     /// Create and Configure a new Tracker
  74     ///
  75     /// A volatile memory queue will be used to store the analytics data. All not transmitted data will be lost when the application gets terminated.
  76     /// The URLSessionDispatcher will be used to transmit the data to the server.
  77     ///
  78     /// - Parameters:
  79     ///   - siteId: The unique site id generated by the server when a new site was created.
  80     ///   - baseURL: The url of the Matomo server. This url has to end in `piwik.php`.
  81     ///   - userAgent: An optional parameter for custom user agent.
  82     @objc convenience public init(siteId: String, baseURL: URL, userAgent: String? = nil) {
  83         assert(baseURL.absoluteString.hasSuffix("piwik.php"), "The baseURL is expected to end in piwik.php")
  84
  85         let queue = MemoryQueue()
  86         let dispatcher = URLSessionDispatcher(baseURL: baseURL, userAgent: userAgent)
  87         self.init(siteId: siteId, queue: queue, dispatcher: dispatcher)
  88     }
  89
  90     internal func queue(event: Event) {
  91         guard Thread.isMainThread else {
  92             DispatchQueue.main.sync {
  93                 self.queue(event: event)
  94             }
  95             return
  96         }
  97         guard !isOptedOut else { return }
  98         logger.verbose("Queued event: \(event)")
  99         queue.enqueue(event: event)
 100         nextEventStartsANewSession = false
 101     }
 102
 103     // MARK: dispatching
 104
 105     private let numberOfEventsDispatchedAtOnce = 20
 106     private(set) var isDispatching = false
 107
 108
 109     /// Manually start the dispatching process. You might want to call this method in AppDelegates `applicationDidEnterBackground` to transmit all data
 110     /// whenever the user leaves the application.
 111     @objc public func dispatch() {
 112         guard !isDispatching else {
 113             logger.verbose("MatomoTracker is already dispatching.")
 114             return
 115         }
 116         guard queue.eventCount > 0 else {
 117             logger.info("No need to dispatch. Dispatch queue is empty.")
 118             startDispatchTimer()
 119             return
 120         }
 121         logger.info("Start dispatching events")
 122         isDispatching = true
 123         dispatchBatch()
 124     }
 125
 126     private func dispatchBatch() {
 127         guard Thread.isMainThread else {
 128             DispatchQueue.main.sync {
 129                 self.dispatchBatch()
 130             }
 131             return
 132         }
 133         queue.first(limit: numberOfEventsDispatchedAtOnce) { events in
 134             guard events.count > 0 else {
 135                 // there are no more events queued, finish dispatching
 136                 self.isDispatching = false
 137                 self.startDispatchTimer()
 138                 self.logger.info("Finished dispatching events")
 139                 return
 140             }
 141             self.dispatcher.send(events: events, success: {
 142                 DispatchQueue.main.async {
 143                     self.queue.remove(events: events, completion: {
 144                         self.logger.info("Dispatched batch of \(events.count) events.")
 145                         DispatchQueue.main.async {
 146                             self.dispatchBatch()
 147                         }
 148                     })
 149                 }
 150             }, failure: { error in
 151                 self.isDispatching = false
 152                 self.startDispatchTimer()
 153                 self.logger.warning("Failed dispatching events with error \(error)")
 154             })
 155         }
 156     }
 157
 158     // MARK: dispatch timer
 159
 160     @objc public var dispatchInterval: TimeInterval = 30.0 {
 161         didSet {
 162             startDispatchTimer()
 163         }
 164     }
 165     private var dispatchTimer: Timer?
 166
 167     private func startDispatchTimer() {
 168         guard Thread.isMainThread else {
 169             DispatchQueue.main.sync {
 170                 self.startDispatchTimer()
 171             }
 172             return
 173         }
 174         guard dispatchInterval > 0  else { return } // Discussion: Do we want the possibility to dispatch synchronous? That than would be dispatchInterval = 0
 175         if let dispatchTimer = dispatchTimer {
 176             dispatchTimer.invalidate()
 177             self.dispatchTimer = nil
 178         }
 179         self.dispatchTimer = Timer.scheduledTimer(timeInterval: dispatchInterval, target: self, selector: #selector(dispatch), userInfo: nil, repeats: false)
 180     }
 181
 182     internal var visitor: Visitor
 183     internal var session: Session
 184     internal var nextEventStartsANewSession = true
 185
 186     internal var campaignName: String? = nil
 187     internal var campaignKeyword: String? = nil
 188
 189     /// Adds the name and keyword for the current campaign.
 190     /// This is usually very helpfull if you use deeplinks into your app.
 191     ///
 192     /// More information on campaigns: [https://matomo.org/docs/tracking-campaigns/](https://matomo.org/docs/tracking-campaigns/)
 193     ///
 194     /// - Parameters:
 195     ///   - name: The name of the campaign.
 196     ///   - keyword: The keyword of the campaign.
 197     @objc public func trackCampaign(name: String?, keyword: String?) {
 198         campaignName = name
 199         campaignKeyword = keyword
 200     }
 201
 202     /// There are several ways to track content impressions and interactions manually, semi-automatically and automatically. Please be aware that content impressions will be tracked using bulk tracking which will always send a POST request, even if  GET is configured which is the default. For more details have a look at the in-depth guide to Content Tracking.
 203     /// More information on content: [https://matomo.org/docs/content-tracking/](https://matomo.org/docs/content-tracking/)
 204     ///
 205     /// - Parameters:
 206     ///   - name: The name of the content. For instance 'Ad Foo Bar'
 207     ///   - piece: The actual content piece. For instance the path to an image, video, audio, any text
 208     ///   - target: The target of the content. For instance the URL of a landing page
 209     ///   - interaction: The name of the interaction with the content. For instance a 'click'
 210     @objc public func trackContentImpression(name: String, piece: String?, target: String?) {
 211         track(Event(tracker: self, action: [], contentName: name, contentPiece: piece, contentTarget: target))
 212     }
 213     @objc public func trackContentInteraction(name: String, interaction: String, piece: String?, target: String?) {
 214         track(Event(tracker: self, action: [], contentName: name, contentInteraction: interaction, contentPiece: piece, contentTarget: target))
 215     }
 216 }
 217
 218 extension MatomoTracker {
 219     /// Starts a new Session
 220     ///
 221     /// Use this function to manually start a new Session. A new Session will be automatically created only on app start.
 222     /// You can use the AppDelegates `applicationWillEnterForeground` to start a new visit whenever the app enters foreground.
 223     public func startNewSession() {
 224         matomoUserDefaults.previousVisit = matomoUserDefaults.currentVisit
 225         matomoUserDefaults.currentVisit = Date()
 226         matomoUserDefaults.totalNumberOfVisits += 1
 227         self.session = Session.current(in: matomoUserDefaults)
 228     }
 229 }
 230
 231 extension MatomoTracker {
 232
 233     /// Tracks a custom Event
 234     ///
 235     /// - Parameter event: The event that should be tracked.
 236     public func track(_ event: Event) {
 237         queue(event: event)
 238
 239         if (event.campaignName == campaignName && event.campaignKeyword == campaignKeyword) {
 240             campaignName = nil
 241             campaignKeyword = nil
 242         }
 243     }
 244
 245     /// Tracks a screenview.
 246     ///
 247     /// This method can be used to 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.
 248     ///
 249     /// - Parameter view: An array of hierarchical screen names.
 250     /// - Parameter url: The optional url of the page that was viewed.
 251     /// - Parameter dimensions: An optional array of dimensions, that will be set only in the scope of this view.
 252     public func track(view: [String], url: URL? = nil, dimensions: [CustomDimension] = []) {
 253         let event = Event(tracker: self, action: view, url: url, dimensions: dimensions)
 254         queue(event: event)
 255     }
 256
 257     /// Tracks an event as described here: https://matomo.org/docs/event-tracking/
 258     ///
 259     /// - Parameters:
 260     ///   - category: The Category of the Event
 261     ///   - action: The Action of the Event
 262     ///   - name: The optional name of the Event
 263     ///   - value: The optional value of the Event
 264     ///   - dimensions: An optional array of dimensions, that will be set only in the scope of this event.
 265     ///   - url: The optional url of the page that was viewed.
 266     public func track(eventWithCategory category: String, action: String, name: String? = nil, value: Float? = nil, dimensions: [CustomDimension] = [], url: URL? = nil) {
 267         let event = Event(tracker: self, action: [], url: url, eventCategory: category, eventAction: action, eventName: name, eventValue: value, dimensions: dimensions)
 268         queue(event: event)
 269     }
 270 }
 271
 272 extension MatomoTracker {
 273
 274     /// Tracks a search result page as described here: https://matomo.org/docs/site-search/
 275     ///
 276     /// - Parameters:
 277     ///   - query: The string the user was searching for
 278     ///   - category: An optional category which the user was searching in
 279     ///   - resultCount: The number of results that were displayed for that search
 280     ///   - dimensions: An optional array of dimensions, that will be set only in the scope of this event.
 281     ///   - url: The optional url of the page that was viewed.
 282     public func trackSearch(query: String, category: String?, resultCount: Int?, dimensions: [CustomDimension] = [], url: URL? = nil) {
 283         let event = Event(tracker: self, action: [], url: url, searchQuery: query, searchCategory: category, searchResultsCount: resultCount, dimensions: dimensions)
 284         queue(event: event)
 285     }
 286 }
 287
 288 extension MatomoTracker {
 289     /// Set a permanent custom dimension.
 290     ///
 291     /// Use this method to set a dimension that will be send with every event. This is best for Custom Dimensions in scope "Visit". A typical example could be any device information or the version of the app the visitor is using.
 292     ///
 293     /// For more information on custom dimensions visit https://matomo.org/docs/custom-dimensions/
 294     ///
 295     /// - Parameter value: The value you want to set for this dimension.
 296     /// - Parameter index: The index of the dimension. A dimension with this index must be setup in the Matomo backend.
 297     @available(*, deprecated, message: "use setDimension: instead")
 298     public func set(value: String, forIndex index: Int) {
 299         let dimension = CustomDimension(index: index, value: value)
 300         remove(dimensionAtIndex: dimension.index)
 301         dimensions.append(dimension)
 302     }
 303
 304     /// Set a permanent custom dimension.
 305     ///
 306     /// Use this method to set a dimension that will be send with every event. This is best for Custom Dimensions in scope "Visit". A typical example could be any device information or the version of the app the visitor is using.
 307     ///
 308     /// For more information on custom dimensions visit https://matomo.org/docs/custom-dimensions/
 309     ///
 310     /// - Parameter dimension: The Dimension to set
 311     public func set(dimension: CustomDimension) {
 312         remove(dimensionAtIndex: dimension.index)
 313         dimensions.append(dimension)
 314     }
 315
 316     /// Set a permanent custom dimension by value and index.
 317     ///
 318     /// This is a convenience alternative to set(dimension:) and calls the exact same functionality. Also, it is accessible from Objective-C.
 319     ///
 320     /// - Parameter value: The value for the new Custom Dimension
 321     /// - Parameter forIndex: The index of the new Custom Dimension
 322     @objc public func setDimension(_ value: String, forIndex index: Int) {
 323         set(dimension: CustomDimension( index: index, value: value ));
 324     }
 325
 326     /// Removes a previously set custom dimension.
 327     ///
 328     /// Use this method to remove a dimension that was set using the `set(value: String, forDimension index: Int)` method.
 329     ///
 330     /// - Parameter index: The index of the dimension.
 331     @objc public func remove(dimensionAtIndex index: Int) {
 332         dimensions = dimensions.filter({ dimension in
 333             dimension.index != index
 334         })
 335     }
 336 }
 337
 338
 339 extension MatomoTracker {
 340
 341     /// Set a permanent new Custom Variable.
 342     ///
 343     /// - Parameter dimension: The Custom Variable to set
 344     public func set(customVariable: CustomVariable) {
 345         removeCustomVariable(withIndex: customVariable.index)
 346         customVariables.append(customVariable)
 347     }
 348
 349     /// Set a permanent new Custom Variable.
 350     ///
 351     /// - Parameter name: The index of the new Custom Variable
 352     /// - Parameter name: The name of the new Custom Variable
 353     /// - Parameter value: The value of the new Custom Variable
 354     @objc public func setCustomVariable(withIndex index: UInt, name: String, value: String) {
 355         set(customVariable: CustomVariable(index: index, name: name, value: value))
 356     }
 357
 358     /// Remove a previously set Custom Variable.
 359     ///
 360     /// - Parameter index: The index of the Custom Variable.
 361     @objc public func removeCustomVariable(withIndex index: UInt) {
 362         customVariables = customVariables.filter { $0.index != index }
 363     }
 364 }
 365
 366 // Objective-c compatibility extension
 367 extension MatomoTracker {
 368     @objc public func track(view: [String], url: URL? = nil) {
 369         track(view: view, url: url, dimensions: [])
 370     }
 371
 372     @objc public func track(eventWithCategory category: String, action: String, name: String? = nil, number: NSNumber? = nil, url: URL? = nil) {
 373         let value = number == nil ? nil : number!.floatValue
 374         track(eventWithCategory: category, action: action, name: name, value: value, url: url)
 375     }
 376
 377     @available(*, deprecated, message: "use trackEventWithCategory:action:name:number:url instead")
 378     @objc public func track(eventWithCategory category: String, action: String, name: String? = nil, number: NSNumber? = nil) {
 379         track(eventWithCategory: category, action: action, name: name, number: number, url: nil)
 380     }
 381
 382     @objc public func trackSearch(query: String, category: String?, resultCount: Int, url: URL? = nil) {
 383         trackSearch(query: query, category: category, resultCount: resultCount, url: url)
 384     }}
 385
 386 extension MatomoTracker {
 387     public func copyFromOldSharedInstance() {
 388         matomoUserDefaults.copy(from: UserDefaults.standard)
 389     }
 390 }