Telemetry

For clients that have "send anonymous usage data" enabled Focus sends a "core" ping and an "event" ping to Mozilla's telemetry service. Sending telemetry can be disabled in the app's settings. Builds of "Focus for Android" have telemetry enabled by default ("opt-out") while builds of "Klar for Android" have telemetry disabled by default.

Core ping

Focus for Android creates and tries to send a "core" ping whenever the app goes to the background. This core ping uses the same format as Firefox for Android and is documented on firefox-source-docs.mozilla.org.

Event ping

In addition to the core ping an event ping for UI telemetry is generated and sent as soon as the app is sent to the background.

Settings

As part of the event ping the most recent state of the user's setting is sent (default values in bold):

Setting	Key	Value
Default search engine	pref_search_engine	bundled engine name/custom(*)
Block ad trackers	pref_privacy_block_ads	true/false
Block analytics trackers	pref_privacy_block_analytics	true/false
Block social trackers	pref_privacy_block_social	true/false
Block content trackers	pref_privacy_block_other	true/false
Block web fonts	pref_performance_block_webfonts	true/false
Block images	pref_performance_block_images	true/false
Locale override	pref_locale	empty string/locale-code(*)
Default browser	pref_default_browser	true/false
Stealth mode	pref_secure	true/false
Autocomplete (Default)	pref_autocomplete_preinstalled	true/false
Autocomplete (Custom)	pref_autocomplete_custom	true/false

(*) If the default is one of the bundled engines, the name of the engine. Otherwise, just custom.

(*) An empty string value indicates "System Default" locale is selected.

Events

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

Sessions

Event	category	method	object	value
Start session (App is in the foreground)	action	foreground	app
Stop session (App is in the background)	action	background	app

Browsing

Event	category	method	object	value	extras.
URL entered	action	type_url	search_bar		options*
Search entered	action	type_search	search_bar
Search hint clicked ("Search for ..")	action	select_query	search_bar
Link from third-party app	action	intent_url	app
Text selection action from app	action	text_selection_intent	app
Long press on image / link	action	long_press	browser
"Pull to refresh"	action	swipe	browser	reload
Autofill popup is shown	action	show	autofill
Autofill performed	action	click	autofill

(*) options is a JSON map containing:

{
  "autocomplete": true,  // Was the URL autocompleted?
  "source":  "default",  // Which autocomplete list was used ("default" or "custom")?  (Only present if autocomplete is true)
  "total": 25            // Total number of items in the used autocomplete list (Only present if autocomplete is true)
}

Custom Tabs

Event	category	method	object	value	extras
Custom tab opened	action	intent_custom_tab	app		options*
"Close" button clicked	action	click	custom_tab_close_bu		tabs*
"Action" button clicked	action	click	custom_tab_action_bu
Custom menu item selected	action	open	menu	custom_tab

(*) options is a JSON map of enabled custom tab options as requested by the third-party app, e.g. [hasToolbarColor, hasCloseButton]

(*) tabs is a JSON map containing the position of the currently selected tab and the total number of open tabs:

{
  "selected": "2"  // Currently selected tab (Zero-based numbering; -1 if no tab is selected)
  "total": "5"     // Total number of open tabs
}

Context Menu

Event	category	method	object	value
Context menu dismissed without selection	action	cancel	browser_contextmenu
Share Link menu item selected	action	share	browser_contextmenu	link
Copy link menu item selected	action	copy	browser_contextmenu	link
Share Image menu item selected	action	share	browser_contextmenu	image
Copy Image menu item selected	action	copy	browser_contextmenu	image
Save Image menu item selected	action	save	browser_contextmenu	image
Open link in new tab	action	open	browser_contextmenu	tab

Erasing session

Event	category	method	object	value	extras
Floating action button clicked	action	click	erase_button		tabs*
Back button clicked: Home screen	action	click	back_button	erase_home	tabs*
Back button clicked: Previous app	action	click	back_button	erase_app	tabs*
Notification clicked	action	click	notification	erase	tabs*
Notification "Erase and Open" click	action	click	notification_action	erase_open	tabs*
Home screen shortcut clicked	action	click	shortcut	erase	tabs*
Erase history in tabs tray	action	click	tabs_tray	erase	tabs*
App removed by user from "recent apps"	action	click	recent_apps	erase	tabs*

(*) tabs is a JSON map containing the position of the currently selected tab and the total number of open tabs:

{
  "selected": "2"  // Currently selected tab (Zero-based numbering; -1 if no tab is selected)
  "total": "5"     // Total number of open tabs
}

Menu

Event	category	method	object	value	extras
Enable/Disable content blocking for session	action	click	blocking_switch	true/false
Share URL with third-party app	action	share	menu
Open default app for URL	action	open	menu	default
Open Firefox	action	open	menu	firefox
Open with ... (Show app chooser)	action	open	menu	selection
"Download Firefox" clicked (in app chooser)	action	install	app	firefox
"What's new"	action	click	menu	whats_new	state*
Reload current page	action	click	menu	reload

(*) state is a JSON map containing information about whether the menu item was highlighted:

{
  "highlighted":  "true" // Whether the menu item was highlighted or not
}

Notification

Event	category	method	object	value	extras
Notification clicked (Erase)	action	click	notification	erase
Action "Open" clicked	action	click	notification_action	open
Action "Erase and Open" clicked	action	click	notification_action	erase_open	tabs*

(*) tabs is a JSON map containing the position of the currently selected tab and the total number of open tabs:

{
  "selected": "2"  // Currently selected tab (Zero-based numbering; -1 if no tab is selected)
  "total": "5"     // Total number of open tabs
}

Downloads

Event	category	method	object	value
Clicked "Download"	action	click	download_dialog	download
Clicked "Cancel"	action	click	download_dialog	cancel

Open Focus From Icon

Event	category	method	object	value
Launched Focus From Icon	action	click	app_icon	open
Resume Focus From Icon	action	click	app_icon	resume

Add to Home screen

Event	category	method	object	value
Clicked "Add to Home screen" in dialog	action	click	add_to_homescreen_dialog	add_to_homescreen
Clicked "Cancel" in dialog	action	click	add_to_homescreen_dialog	cancel
Open Focus from Home screen shortcut	action	click	homescreen_shortcut	open

Share to Focus Event

Event	category	method	object	value
Shared URL to Focus	action	share_intent	app	url
Shared Search Terms to Focus	action	share_intent	app	search

Settings

Event	category	method	object	value	extras
Setting changed	action	change	setting		{ "to": <value> }
Autocomplete domain added	action	save	autocomplete_domain
Autocomplete domain removed	action	remove	autocomplete_domain		{ "total": 5 }
Autocomplete domain reordered	action	reorder	autocomplete_domain		options*
Default search engine clicked	action	open	search_engine_setting
Change default search engine	action	save	search_engine_setting		{"source": src* }
Select "Remove" engines screen	action	remove	search_engine_setting
Delete search engines	remove	remove	remove_search_engines		{"selected": num* }
Restore bundled engines	action	restore	search_engine_setting
Select "Add another engine"	action	show	custom_search_engine
Save custom search engine	action	save	custom_search_engine		{"success": bool* }
Click "Add search engine" ℹ️	action	click	search_engine_learn_more

(*) options is a JSON map containing:

{
  "from": 5
  "to":   2
}

(*) src can be either bundled or custom

(*) num number of engines selected for deletion

(*) bool true if successfully saved, false if validation error

Firstrun

Event	category	method	object	value
Showing a first run page	action	show	firstrun	page*
Skip button pressed	action	click	firstrun	skip
Finish button pressed	action	click	firstrun	finish

(*) Page numbers start at 0. Initially when the firstrun tour is shown an event for the first page (0) is fired.

Multitasking / Tabs

Event	category	method	object	value	extras
Context menu: Open link in new tab	action	open	browser_contextmenu	tab	tabs*
Open the tabs tray	action	show	tabs_tray
Close the tabs tray (back / click outside)	action	hide	tabs_tray
Switch to tab in tabs tray	action	click	tabs_tray	tab	tabs*
Erase history in tabs tray	action	click	tabs_tray	erase	tabs*

(*) tabs is a JSON map containing the position of the currently selected tab and the total number of open tabs:

{
  "selected": "2"  // Currently selected tab (Zero-based numbering; -1 if no tab is selected)
  "total": "5"     // Total number of open tabs
}

SSL Errors

Event	category	method	object	extras
SSL Error From Page	error	page	browser	error*
SSL Error From Resource	error	resource	browser	error*

(*)error is a JSON map containing the primary SSL Error

{
  "error_code": "SSL_DATE_INVALID"  // Primary SSL Error
}

Possible Error Codes
SSL_DATE_INVALID
SSL_EXPIRED
SSL_IDMISMATCH
SSL_NOTYETVALID
SSL_UNTRUSTED
SSL_INVALID
Undefined SSL Error

Limits

• 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

Implementation notes

• Event pings are generated (and stored on disk) whenever the onStop() callback of the main activity is triggered. This happens whenever the main screen of the app is no longer visible (The app is in the background or another screen is displayed on top of the app).

• Whenever we are storing pings we are also scheduling an upload. We are using Android’s JobScheduler API for that. This allows the system to run the background task whenever it is convenient and certain criterias are met. The only criteria we are specifying is that we require an active network connection. In most cases this job is executed immediately after the app is in the background.

• Whenever an upload fails we are scheduling a retry. The first retry will happen after 30 seconds (or later if there’s no active network connection at this time). For further retries a exponential backoff policy is used: [30 seconds] * 2 ^ (num_failures - 1)

• An earlier retry of the upload can happen whenever the app is coming to the foreground and sent to the background again (the previous scheduled job is reset and we are starting all over again).