Platform Health API

[FKLC]

Introduction

When there's an issue about CSP, permission policy etc. exists, there are ways to report it to the developer defined endpoints using the Reporting API, but the opposite, automated reporting to browser developers doesn't exist. For example, browsers change their privacy protections and sometimes those changes break websites, increase captchas or their difficultly, or cause usability issues causing friction. Browsers often have more insight into what privacy features are enabled or experiments are running on the browser. The goal of this API is to allow web developers to automatically report issues with their platform to the browser, which the browser can then report to its developers. So that if it is an issue that can be addressed by the browser, browser developers can be aware of it and address it.

Use Cases (Recommended)

A captcha provider tries to reduce friction as much as possible, but a privacy feature enabled on the browser trips up one of the signals for bot-likeliness. After any completed captcha (whether with failure or success), the captcha provider can call this API to report the status of the interaction with one of the enum statuses that is defined in this API. Then, the browser can internally decide if and how to record/report the reported status.

Goals (Optional)

• Implementing a reporting JS API that the browser can use to collect data and report it to browser developers
• Verifying that the JS API call comes from the actual vendor/product, rather than a malicious actor spamming the API

Non-goals (Optional)

• The infrastructure or logic for how the browser reports the collected data to its developers. Browser developers can use whatever telemetry method they wish.

Proposed Solution

Provide a JS API the web developers can call to report friction caused by their product. To prevent spam, a developer attestation could be put in place as well. To prevent the use of API in a way that exposes too much information, only predefined enum values can be utilized.

Examples (Recommended)

This is an example of how a captcha provider might use this API:

function reportToBrowser(state: PlatformHealthState) {
	navigator.reportPlatformHealth({
		vendor: "example-company",
		product: "bot-incinerator-500",
		state,
	});
}

function onUserIsBotLike(isDefinitelyBot: boolean) {
	if (isDefinitelyBot) {
		blockAction();
		reportToBrowser("failure");
	} else {
		showChallenge();
		reportToBrowser("friction");
	}
}

function onCompletion(autoCompleted: boolean) {
	if (autoCompleted) {
		reportToBrowser("success");
	} else {
		reportToBrowser("friction");
	}
}

Alternate Approaches (Optional)

• The browser developers can agree with web developers manually and ask web devs to report to their API, but then the browser won't have visibility into the browser's configuration.
• The browser developers can agree with web developers manually and ask web devs to emit a certain event or call a browser-specific JS API, but the manual process is still present in this approach.
• Webcompat.com this is the strongest alternate approach. It still needs manual reporting. AFAIK browsers don't magically upload anything specific about the browser configuration but if they do in the background, then I didn't know about it.

Privacy & Security Considerations

To prevent PII leaking into state, only certain values should be allowed. Not every user interaction should be thought as something to be reported i.e. if a user doesn't like a video, it shouldn't be reported, only failures/friction alike should be reported.

Let’s Discuss (Optional)

There are some things I'm not sure how they would fit into this API or work in general:

• How should the developer attestation work?
• Which values should be allowed in the state value?
• Having this sort of data could push back the implementation of privacy features if browser developers find out there's a pattern of failure/friction with privacy features implemented.
• My state examples are very captcha oriented, it could be extented to allow for more states. An additional payload attribute could be added, but then the browsers need to somehow determine if it can cause privacy issues, so I'm not really in favour of it.

Note: I'm unaffiliated.