Skip to content
A generic library for sending telemetry pings from iOS applications to Mozilla's telemetry service.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
Telemetry Allow library users to subclass PingBuilder (#102) Oct 24, 2018
TestApp [nobug, tests] Example usage of recordEvent added to TestApp Nov 6, 2017
MozillaTelemetry.podspec Bump version to v1.1.0 Apr 19, 2018
tests-only-Cartfile [nobug, buildsys] Add travis yml Oct 18, 2017

Build Status


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.

  • Ensure your ping builders are registered before the UIApplication appDidBecomeActive, as the library uses that event to trigger the start of recording.
  • 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.

When the app is backgrounded, one or more backgroundTasks are started to perform uploading.

Customizing Ping Data

To modify the final key-value data dict before it gets stored as JSON, install a handler using Telemetry.swift: beforeSerializePing(pingType: String, handler: @escaping BeforeSerializePingHandler)

Getting involved

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.


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
You can’t perform that action at this time.