GampKit

GitHub GitHub issues

Cocoapods doc percentage

Using Google Analytics for Tracking Events, Timing, Errors and more

Rather than downloading large amounts of libraries framework in order to understand how your app is used, you can use this library for easy data. The library works directly with Google Analytics using their Measure Protocol API. See all your data right from the Google Analytics dashboard.

Features

Included with this library is the ability to track:

Events with Custom Data
Timing of various operations
Swift Errors and NSExceptions
Custom actions such screens and transactions

Reqirements

iOS 8.0+ / macOS 10.9+ / tvOS 9.0+ / watchOS 2.0+ / Linux
Xcode 10.2+
Swift 5+

Installing

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate GampKit into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'GampKit', '~> 0.1.0'

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. GampKit does support its use on supported platforms.

Once you have your Swift package set up, adding GampKit as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/brightdigit/GampKit.git", .upToNextMajor(from: "0.1.0"))
]

Usage

API Documentation

Before moving forward make sure to setup a property under your Google Analytics account. With your new property for your application, you will need your tracking identifier. Typically a tracking identifier has a format of UA-XXXXXXXXX-XX. You will need the tracking identifier as well as the:

Application Name
Application Version
Client Identifier - this should be a ananymous UUID created on application installation and saved to future use on launch

Configuration

In order to begin tracking, you will need to setup a AnalyticsTracker with the configuration of your application using a AnalyticsConfiguration object:

  let tracker = AnalyticsTracker(configuration: AnalyticsConfiguration(
    trackingIdentifier: "UA-XXXXXXXX-XX",
    applicationName: "GampKitDemo",
    applicationVersion: "1.0",
    clientIdentifier: clientIdentifer
  ))

Now that you have setup your AnalyticsTracker, let’s being tracking events.

Tracking

There are three types of tracking objects: Events, Timing, and Exceptions.

Events

For tracking events, you can create an AnalyticsEvent with a category and action:

    let event = AnalyticsEvent(category: "category", action: "action")
    tracker.track(event) { result in
      if case let .failure(error) = result {
        debugPrint(error)
      }
    }

Timing

For tracking timing, you can create an AnalyticsTiming or use AnalyticsTracker.track(time:...) with a category and action:

    let start : Date
    ...
    let timing = start.timeIntervalSinceNow
    tracker.track(time: -timing, withCategory: "jsonLoader", withVariable: "load") { result in
      if case let .failure(error) = result {
        debugPrint(error)
      }
    }

Errors and Exceptions

For tracking errors and exceptions, you can use AnalyticsTracker.track(error:...):

    do {
      try doSomething()
    } catch let error {
      tracker.track(error: error, isFatal: false) { result in
        if case let .failure(error) = result {
          debugPrint(error)
        }
      }
    }

Custom Items

You can also track custom items by implementing AnalyticsTrackable. This requires the implmentation of two methods:

  var hitType: AnalyticsHitType {
    get
  }

  func parameters() -> AnalyticsParameterDictionary

An AnalyticsParameterDictionary is simply a dictionary with keys of type AnalyticsParameterKey.

public typealias AnalyticsParameterDictionary = [AnalyticsParameterKey: Any]

public enum AnalyticsParameterKey: String, CaseIterable {
  case hitType = "t", version = "v", trackingId = "tid",
    userTimingCategory = "utc", userTimingLabel = "utl", timing = "utt", clientId = "cid",
    userTimingVariable = "utv",
    applicationName = "an", applicationVersion = "av", eventAction = "ea",
    eventCategory = "ec", eventLabel = "el", eventValue = "ev",
    userLanguage = "ul", operatingSystemVersion = "cd1", model = "cd2",
    exceptionDescription = "exd", exceptionFatal = "exf"
}

The rules regarding what are required based on hit type and each parameter is located in the Google Analytics Measurement Protocol Parameter Reference.

Debugging vs. Release

By default, the library will either use the Google Analytics Measurement Protocol API url for validation purposes or the actual url depending on whether the build is DEBUG or RELEASE. When using the validation server, no items will be actually be tracked only validated. You can override this in one of two ways:

Supply a custom URL for the AnalyticsSessionManager

  let tracker = AnalyticsTracker(configuration: AnalyticsConfiguration(
    trackingIdentifier: "UA-XXXXXXXX-XX",
    applicationName: "GampKitDemo",
    applicationVersion: "1.0",
    clientIdentifier: clientIdentifer
  ), sessionManager: AnalyticsURLSession(url : url))

Use the debug mode flag for using the validation server

  let tracker = AnalyticsTracker(configuration: AnalyticsConfiguration(
    trackingIdentifier: "UA-XXXXXXXX-XX",
    applicationName: "GampKitDemo",
    applicationVersion: "1.0",
    clientIdentifier: clientIdentifer
  ), debugMode: false)

License

GampKit is released under the MIT license. See LICENSE for details.