Mozilla's Telemetry Service Pings

NOTE: If there is anything in this document that is not clear, is incorrect, or that requires more detail, please file a request through Bugzilla. Also feel free to submit corrections or additional information.

Firefox for iOS uses Mozilla's own Telemetry service for anonymous insight into usage of various app features. This event tracking is turned on by default for Firefox for iOS (opt-out).

The app uses Mozilla's own framework linked into Firefox for iOS and a data collection service run by Mozilla. The framework is open source and MPL 2.0 licensed. It is hosted at https://github.com/mozilla-mobile/telemetry-ios. Firefox for iOS pulls in an unmodified copy of the framework via Carthage.

^{Example of bug to add telemetry: https://bugzilla.mozilla.org/show_bug.cgi?id=1455672}

Telemetry Pings

The Telemetry framework collects and sends two types of pings to Mozilla's Telemetry backend:

• A Core Ping with basic system info and usage times.
• An Event Ping with details about user preferences and UI actions with timestamps relative to the app start time.

The messages are also documented below in more detail of what is sent in each HTTP request. All messages are posted to a secure endpoint at https://incoming.telemetry.mozilla.org. They are all application/json HTTP POST requests. Details about the HTTP edge server can be found at https://wiki.mozilla.org/CloudServices/DataPipeline/HTTPEdgeServerSpecification.

Core Ping

Request

tz:                 -240
sessions:           1
durations:          1
searches:
  suggestion.google: 13
  listitem.google:   7
  actionbar.google:  4
clientId:           610A1520-4D47-498E-B20F-F3B46216372B
profileDate:        17326
v:                  7
device:             iPad
defaultSearch:      google
locale:             en-US
seq:                1
os:                 iOS
osversion:          11.1
created:            2017-12-12
arch:               arm64

These parameters are documented at https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/data/core-ping.html.

Response

If the ping was received successfully, the server responds with an HTTP 200 status code.

Additional items added to the Core Ping

• defaultMailClient

The defaultMailClient field contains the URL scheme of the mail client that the user wants to use for mailto: links. It is used to measure usage of this feature, to see how effective feature promotion campaigns are and to report back to third-party mail clients what percentage of users is using their client. Duration: There is no intent to remove this field.

• defaultNewTabExperience

The defaultNewTabExperience field contains the name of the view that the user wants to see on new tabs. For example History, Homepage or Blank. It is used to measure usage of this feature, to see how effective feature promotion campaigns are and to establish a baseline number for when we introduce the new Activity Stream features. Duration: There is no intent to remove this field.

Event Ping

Request

tz:            -240
seq:           1
os:            iOS
created:       1497026730320
clientId:      2AF1A5A8-29B3-44B0-9653-346B67811E99
osversion:     11.2
settings:
  BlockAds:    true
  BlockSocial: false
},
v:             1
events:
  [ 2147, action, type_query, search_bar   ]
  [ 2213, action, type_url,   search_bar   ]
locale:        en-US

These parameters are documented at https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/events.html.

You can find the full list of Event Pings sent by Focus here.

Response

If the ping was received successfully, the server responds with an HTTP 200 status code.

Events

The event ping contains a list of events (see event format on readthedocs.io) for the following actions:

App Lifecycle

Event	category	method	object	value
App is foregrounded (session start)	action	foreground	app
App is backgrounded (session end)	action	background	app

Bookmarks

Event	category	method	object	value	extras
View Bookmarks list from Home Panel tab button	action	view	bookmarks-panel	home-panel-tab-button
View Bookmarks list from App Menu	action	view	bookmarks-panel	app-menu
Add Bookmark from Page Action Menu	action	add	bookmark	page-action-menu
Add Bookmark from Share Menu	action	add	bookmark	share-menu
Add Bookmark from Activity Stream context menu	action	add	bookmark	activity-stream
Delete Bookmark from Page Action Menu	action	delete	bookmark	page-action-menu
Delete Bookmark from Activity Stream context menu	action	delete	bookmark	activity-stream
Delete Bookmark from Home Panel via long-press	action	delete	bookmark	bookmarks-panel	{ "gesture": "long-press" }
Delete Bookmark from Home Panel via swipe	action	delete	bookmark	bookmarks-panel	{ "gesture": "swipe" }
Open Bookmark from Awesomebar search results	action	open	bookmark	awesomebar-results
Open Bookmark from Home Panel	action	open	bookmark	bookmarks-panel

Reader Mode

Event	category	method	object	value	extras
Open Reader Mode	action	tap	reader-mode-open-button
Leave Reader Mode	action	tap	reader-mode-close-button

Reading List

Event	category	method	object	value	extras
Add item to Reading List from Toolbar	action	add	reading-list-item	reader-mode-toolbar
Add item to Reading List from Share Extension	action	add	reading-list-item	share-extension
Add item to Reading List from Page Action Menu	action	add	reading-list-item	page-action-menu
Open item from Reading List	action	open	reading-list-item
Delete item from Reading List from Toolbar	action	delete	reading-list-item	reader-mode-toolbar
Delete item from Reading List from Home Panel	action	delete	reading-list-item	reading-list-panel
Mark Item As Read	action	tap	reading-list-item	mark-as-read
Mark Item As Unread	action	tap	reading-list-item	mark-as-unread

Settings

Event	category	method	object	value	extras
Setting changed	action	change	setting		{ "to": (value) }

QR Codes

Event	category	method	object
URL-based QR code scanned	action	scan	qr-code-url
Non-URL-based QR code scanned	action	scan	qr-code-text

App Share Extension

Event	category	method	object
Send to device tapped	app-extension-action	send-to-device	"url"
Open in firefox tapped	app-extension-action	application-open-url	"url"/"searcText"
Bookmark this page tapped	app-extension-action	bookmark-this-page	"url"
Add to reading list tapped	app-extension-action	add-to-reading-list	"url"

"url" is an object code, literally "url", not an URL itself.

Limits

• An event ping will not be sent until at least 3 events are recorded
• An event ping will contain up to but no more than 500 events
• No more than 40 pings per type (core/event) are stored on disk for upload at a later time
• No more than 100 pings are sent per day