🔬 Telemetry

Telemetry is an open-source SDK for Google Analytics. We believe in transparency and security, hence the open-source approach.

Installation

You can add Telemetry to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/sentryco/Telemetry", from: "1.0.0")
]

Why Use Telemetry?

• 🤖 Google Analytics (GA) provides valuable insights into user engagement and traction. Telemetry helps you leverage these insights to improve your application.
• 🐛 GA is an excellent tool for error and crash reporting. Stay ahead of UX issues by receiving notifications about bugs.
• 🌍 GA helps you understand the geographical distribution of your app's users.

Important

We currently use the GA3 API, which will be deprecated in July. We plan to migrate to GA4 before then. GA4 is now available here https://github.com/sentryco/Telemetric

Event Tracking

With Telemetry's event() method, you can monitor any event of interest.

Telemetry.event("Authorize", action: "Access granted")

Screenviews

It's important to track the "screens" that users navigate to. A logical place to do this is in your ViewController's viewDidAppear method. Use Telemetry's screenView() method for this purpose.

Telemetry.screenView("Cheers")

Sessions

By calling session(start: true) when the application opens and session(start: false) when it closes, you can track individual user sessions. Here's an example of how to do this in your UIApplicationDelegate application:

Telemetry.trackerID = "UA-XXXXX-XX")
Telemetry.session(start: true) // applicationDidBecomeActive
Telemetry.session(start: false) // applicationDidEnterBackground

Exception

Use the exception method to report warnings and errors.

Telemetry.exception("Error - database not available", isFatal: false)

Timing

This example tracks the time to fetch user data from a database. The 'category' parameter denotes the operation type ("Database"). The 'variable' parameter specifies the operation ("Fetch"). The 'time' parameter records elapsed time in milliseconds. The optional 'label' parameter can provide additional details.

// Start the timer
let startTime = Date()

// Perform some operation
// ...

// Calculate the elapsed time
let elapsedTime = Date().timeIntervalSince(startTime)

// Log the timing event
Telemetry.timing(category: "Database", variable: "Fetch", time: elapsedTime, label: "User data fetch")

Gotchas:

• Telemetry automatically requests Google Analytics to anonymize user IPs to comply with GDPR.
• Obtain the token from the admin page of the tracked Google Analytics entity.
• While Firebase Crashlytics is a popular choice, it can be complex due to the need to use their SDK. Sometimes, simplicity is key.
• When setting up your Google Analytics account, ensure to use the legacy Universal Analytics property and not GA4. This legacy option is under the advanced menu during account setup.
• Why are closed-source SDKs a concern? According to Apple's app-review guidelines: Ensure that all software frameworks and dependencies also adhere to the App Store Review Guidelines.

Resources:

• Anonymous GA: https://stackoverflow.com/questions/50392242/how-anonymize-google-analytics-for-ios-for-gdpr-rgpd-purpose
• Guide on fingerprinting in iOS: https://nshipster.com/device-identifiers/
• Guide on identifiers: https://gist.github.com/hujunfeng/6265995
• Noteworthy tracker project: https://github.com/kafejo/Tracker-Aggregator
• Another noteworthy tracker project: https://github.com/devxoul/Umbrella
• Using Google Analytics for Tracking SaaS: https://reflectivedata.com/using-google-analytics-for-tracking-saas/

Todo:

• Add info to this readme on how to setup Google analytics for your google account etc 🚧