A generic library for sending telemetry pings from iOS applications to Mozilla's telemetry service.

The goal of this library is to provide a generic set of components to support a variety of telemetry use cases. It tries to not be opinionated about frameworks or HTTP clients. The only dependency is AliSoftware/OHHTTPStubs for supporting tests.

In your application's AppDelegate, setup your configuration options:

let configuration = Telemetry.default.configuration
configuration.appName = "My App"
configuration.appVersion = "1.0"
configuration.updateChannel = "release"
configuration.buildId = "1"
...

This library can automatically measure user preferences stored with NSUserDefaults for certain ping types. To do this, specify the NSUserDefaults key and a default value in the configuration:

configuration.measureUserDefaultsSetting(forKey: "foo", withDefaultValue: true)
configuration.measureUserDefaultsSetting(forKey: "bar", withDefaultValue: false)

The AppDelegate is also a good place to add a TelemetryPingBuilder for each type of ping you plan on using. This library includes two by default: CorePingBuilder and FocusEventPingBuilder. Additional ping types can be added by extending the base TelemetryPingBuilder class. Simply add the classes for the ping builder types you intend to use:

Telemetry.default.add(pingBuilderType: CorePingBuilder.self)
Telemetry.default.add(pingBuilderType: FocusEventPingBuilder.self)

How you record data in your application depends largely on the ping builder types you are using. For convenience, several methods are accessible right off the root Telemetry class for interfacing with the built-in ping builder types.

• recordSessionStart() -- Marks the start of a "session" for CorePingBuilder. This is typically called from applicationDidBecomeActive(_ application: UIApplication) in the AppDelegate.
• recordSessionEnd() -- Marks the end of a "session" for CorePingBuilder. This is typically called from applicationWillResignActive(_ application: UIApplication) in the AppDelegate.
• recordEvent(_ event: TelemetryEvent) -- Adds a UI event to be batched and sent for FocusEventPingBuilder. There are also several convenience methods for constructing a TelemetryEvent and recording it at the same time such as recordEvent(category: String, method: String, object: String, value: String?, extras: [String : Any?]?) where value and extras are both optional.
• recordSearch(location: SearchesMeasurement.SearchLocation, searchEngine: String) -- Records that a search was performed for CorePingBuilder.

After recording data, it is stored locally in FileManager.SearchPathDirectory.cachesDirectory by default. Before sending a ping, it needs to be queued to capture all of the measurements and store the finalized ping to the filesystem. This is typically done in applicationDidEnterBackground(_ application: UIApplication) in the AppDelegate:

Telemetry.default.queue(pingType: CorePingBuilder.PingType)

Finally, the stored pings for a specified ping type need to be scheduled for uploading. This is also typically done in applicationDidEnterBackground(_ application: UIApplication) in the AppDelegate:

Telemetry.default.scheduleUpload(pingType: CorePingBuilder.PingType)

All stored pings for the scheduled ping types will be uploaded with a URLSessionConfiguration configured for background uploading. This means iOS will automatically schedule the HTTP task to happen in the background at an appropriate time at its discretion. In practice, this HTTP request usually happens almost immediately after the application enters the background.

We encourage you to participate in this open source project. We love Pull Requests, Bug Reports, ideas, (security) code reviews or any kind of positive contribution. Please read the Community Participation Guidelines.

• Issues: https://github.com/mozilla-mobile/telemetry-ios/issues

• IRC: #mobile (irc.mozilla.org)

• Mailing list: mobile-firefox-dev

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/