SwiftAnalytics is an API package which tries to establish a common API the ecosystem can use. To make analytics really work for real-world workloads, we need SwiftAnalytics-compatible analytics backends which send events to Firebase, Amplitude, DataDog, etc.

To depend on the analytics API package, you need to declare your dependency in your Package.swift:

.package(url: "https://github.com/dankinsoid/swift-analytics.git", from: "1.9.0"),

and to your application/library target, add "SwiftAnalytics" to your dependencies, e.g. like this:

.target(name: "BestExampleApp", dependencies: [
    .product(name: "SwiftAnalytics", package: "swift-analytics")
],

1. let's import the SwiftAnalytics API package

import SwiftAnalytics

2. we need to bootstrap the analytics system with a default analytics handler, which is usually a custom implementation of AnalyticsHandler protocol. For example you can use FirebaseAnalyticsHandler from the swift-firebase-tools package, or you can implement your own analytics handler, it's a very simple protocol.

AnalyticsSystem.bootstrap(FirebaseAnalyticsHandler())

3. we need to create a Analytics

let analytics = Analytics()

4. we're now ready to use it

analytics.send("hello world")

Analytics are used to send events and therefore the most important type in SwiftAnalytics, so their use should be as simple as possible.

Analytics.Event is a type that represents an event that should be sent. It has a name and a dictionary of parameters. Example:

let event = Analytics.Event("hello world", parameters: ["foo": "bar"])
// or
let event = Analytics.Event("hello world").with("foo", "bar")

Analytics has a parameters that can be shared across all events sent by the same instance of Analytics. Example:

var analytics = Analytics()
analytics.parameters["user-id"] = "\(UUID())"
analytics.send("hello world")

There are some helper functions to set parameters:

let analytics2 = analytics1
	.with("user-id", UUID())
  .with("user-name", "Alice")

let analytics3 = analytics2
    .with(["session-id": UUID()])

SwiftAnalytics provides excellent support for Swift's Codable protocol, making it easy to work with structured data in your analytics events.

You can directly use any Encodable type as parameters:

struct UserInfo: Codable {
    let id: String
    let name: String
    let age: Int
}

let userInfo = UserInfo(id: "123", name: "Alice", age: 30)

// Create an event with Encodable parameters
let event = try Analytics.Event("user_profile_viewed", parameters: userInfo)

// Or add Encodable parameters to existing analytics
let analytics = Analytics()
    .with("user", userInfo)
    .with("session_id", UUID())

You can add individual parameters using any Encodable type:

let analytics = Analytics().with("user_info", userInfo)

// or directly with a dictionary
let analytics = try Analytics().with(userInfo)

All Analytics.ParametersValue instances provide a jsonString property for easy serialization:

let parameters: Analytics.Parameters = [
    "user_id": "123",
    "preferences": ["theme": "dark", "notifications": true],
    "scores": [95, 87, 92]
]

for (key, value) in parameters {
    print("\(key): \(value.jsonString)")
}
// Output:
// user_id: "123"
// preferences: {"notifications":true,"theme":"dark"}
// scores: [95,87,92]

Note: If you don't want to implement a custom analytics backend, everything in this section is probably not very relevant, so please feel free to skip.

To become a compatible analytics backend that all SwiftAnalytics consumers can use, you need to do two things:

1. Implement a type (usually a struct) that implements AnalyticsHandler, a protocol provided by SwiftAnalytics
2. Instruct SwiftAnalytics to use your analytics backend implementation.

an AnalyticsHandler or analytics backend implementation is anything that conforms to the following protocol

public protocol AnalyticsHandler {
    
    var parameters: Analytics.Parameters { get set }
    func send(event: Analytics.Event, file: String, function: String, line: UInt)
}

Where parameters is a dictionary of parameters that can be shared across all events sent by the same instance of AnalyticsHandler, and send(event:file:function:line:) is a function that sends an event.

Instructing SwiftAnalytics to use your analytics backend as the one the whole application (including all libraries) should use is very simple:

AnalyticsSystem.bootstrap(MyAnalyticsHandler())

1. Swift Package Manager

Create a Package.swift file.

// swift-tools-version:5.7
import PackageDescription

let package = Package(
  name: "SomeProject",
  dependencies: [
    .package(url: "https://github.com/dankinsoid/swift-analytics.git", from: "1.9.0")
  ],
  targets: [
    .target(name: "SomeProject", dependencies: ["SwiftAnalytics"])
  ]
)

$ swift build

dankinsoid, voidilov@gmail.com

swift-analytics is available under the MIT license. See the LICENSE file for more info.