混合内容遥测 (已弃用)¶
混合内容是指作为 Firefox 的一部分加载的 Web 内容，对用户来说是 Firefox 的一部分，并且主要用于 Firefox。这可以是随 Firefox 一起提供的页面，也可以是从我们托管的服务动态加载的页面。混合内容遥测允许 Mozilla 页面检查数据收集是否已启用，并提交遥测数据。
重要
Firefox 中每个新的或更改的数据收集（包括混合内容）都需要来自数据管理员的数据收集审查。
如果已启用收集，则记录的数据将由 Firefox 通过主 Ping发送到 Mozilla 服务器。
添加内容数据收集¶
可以通过以下方式从 Web 内容发送遥测数据：
在 Firefox 代码库中授予 Web 内容的主机权限；
在页面中包含
HybridContentTelemetry-lib.js文件；加载库后注册探针；
使用 API 发送遥测数据。
授予权限¶
出于安全/隐私原因，Mozilla.ContentTelemetry 仅在允许的安全来源列表中工作。允许的来源列表可以在browser/app/permissions中找到。主机需要被授予hc_telemetry权限才能被允许使用 API。
示例
origin hc_telemetry 1 https://discovery.addons.mozilla.org
向permissions文件添加条目需要遵循流程。如果“加速”内容需要向 Mozilla 页面授予权限，则可以使用权限管理器。
function addonInit() {
// The following code must be called before attempting to load a page that uses
// hybrid content telemetry on https://example.mozilla.org.
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin("https://example.mozilla.org");
Services.perms.addFromPrincipal(principal, "hc_telemetry", Services.perms.ALLOW_ACTION);
}
function addonCleanup() {
// The permission must be removed if no longer needed (e.g. the add-on is shut down).
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin("https://example.mozilla.org");
Services.perms.removeFromPrincipal(principal, "hc_telemetry");
}
重要
授予的权限在“加速”附加组件卸载时不会消失，但在浏览器关闭时会清除。如果需要在不关闭浏览器的情况下清除权限，则必须手动执行。此外，权限以来源为键：http://mozilla.com和https://mozilla.com是不同的。
包含库¶
要使用混合内容遥测，相关的页面内容 JS 库需要包含在页面中。我们有不同的集成选项
将
mozilla-hybrid-content-telemetry作为依赖项添加到项目中，并在代码中引入它。从外部 unpkg CDN直接加载它。
从主存储库手动获取最新版本并将其添加到页面存储库中。然后可以将此文件与页面一起部署。
示例（手动包含）：¶
<!DOCTYPE html>
<html>
<head>
<!-- Other head stuff -->
<script type="application/javascript" src="HybridContentTelemetry-lib.js"></script>
</head>
<body> <!-- Other body stuff --> </body>
</html>
示例（NPM 依赖项）：¶
将依赖项添加到您的项目中
npm install --save [email protected]
在您的应用程序中加载模块并使用API
const ContentTelemetry = require("mozilla-hybrid-content-telemetry");
ContentTelemetry.registerEvents("page.interaction", {
"click": {
methods: ["click"],
objects: ["red_button", "blue_button"],
}
});
// Now events can be recorded.
ContentTelemetry.recordEvent("page.interaction", "click", "red_button");
注意
以下示例假设手动包含 JS 库。
注册探针¶
探针注册可以在页面加载库后的任何时间进行，但尽早注册可以确保在进行记录尝试时定义可用。
示例
<!DOCTYPE html>
<html>
<head>
<!-- Other head stuff -->
<script type="application/javascript">
window.onload = function() {
if (!Mozilla || !Mozilla.ContentTelemetry) {
// .. uh-oh, was library loaded? Report the error.
return;
}
// Register the probe.
Mozilla.ContentTelemetry.registerEvents("page.interaction", {
"click": {
methods: ["click"],
objects: ["red_button", "blue_button"],
}
});
};
</script>
</head>
<body> <!-- Other body stuff --> </body>
</html>
记录数据¶
数据记录可以在注册探针后的任何时间进行。如果遥测首选项允许，则数据将被记录并由 Firefox 发送。
示例
<!DOCTYPE html>
<html>
<head>
<!-- Other head stuff -->
<script type="application/javascript">
function triggerEvent() {
if (!Mozilla || !Mozilla.ContentTelemetry) {
// .. uh-oh, was library loaded? Report the error.
return;
}
Mozilla.ContentTelemetry.recordEvent("page.interaction", "click", "red_button");
};
</script>
</head>
<body>
<!-- Other body stuff -->
<div id="content">
<button id='event-recording' onclick="triggerEvent();">
Trigger Recording
</button>
</div>
</body>
</html>
检查是否启用了上传¶
Mozilla 页面可以检查数据上传是否已启用，如遥测首选项中所报告的那样。这对于不使用遥测收集数据的页面但需要遵守我们数据收集策略的页面很有用。
示例
<!DOCTYPE html>
<html>
<head>
<!-- Other head stuff -->
<script type="application/javascript">
function recordData() {
if (!Mozilla || !Mozilla.ContentTelemetry) {
// .. uh-oh, was library loaded? Report the error.
return;
}
if (!Mozilla.ContentTelemetry.canUpload()) {
// User has opted-out of Telemetry. No collection must take place.
return;
}
// ... perform the collection without Telemetry below this point.
};
</script>
</head>
<body>
<!-- Other body stuff -->
<div id="content">
<button id='event-recording' onclick="recordData();">
Trigger Recording
</button>
</div>
</body>
</html>
API¶
混合内容 API 通过包含HybridContentTelemetry-lib.js库提供给 Web 内容。
API 的初始实现允许事件的注册和记录。
JS API¶
授权内容可以使用以下函数
Mozilla.ContentTelemetry.canUpload();
Mozilla.ContentTelemetry.initPromise();
Mozilla.ContentTelemetry.registerEvents(category, eventData);
Mozilla.ContentTelemetry.recordEvent(category, method, object, value, extra);
这些函数不会抛出异常。如果执行了不受支持的操作（例如，记录未知事件），则会将错误记录到浏览器控制台。
注意
使用此 API 收集的数据将始终尊重用户的遥测首选项：如果用户选择不将遥测数据发送到 Mozilla 服务器，则混合内容页面的遥测数据也不会发送。与其他遥测数据一样，它仍将在本地记录，并可通过about:telemetry访问。
Mozilla.ContentTelemetry.canUpload()¶
Mozilla.ContentTelemetry.canUpload();
如果浏览器允许将收集的数据发送到 Mozilla 服务器（即datareporting.healthreport.uploadEnabled为true），则此函数返回 true，否则返回 false。请参阅首选项。
注意
页面应使用此函数检查是否允许收集数据。仅当未将遥测系统用于收集时才需要此操作。如果使用了遥测，则遥测 API 内部会自动处理此操作。页面不应缓存返回值：用户可以随时选择加入或退出数据收集，因此返回值可能会更改。
示例
if (Mozilla.ContentTelemetry.canUpload()) {
// ... perform the data collection here using another measurement system.
}
Mozilla.ContentTelemetry.initPromise()¶
Mozilla.ContentTelemetry.initPromise();
此函数返回一个 Promise，一旦混合内容遥测正确初始化并且可以可靠地读取canUpload的值，该 Promise 就会被解析。如果混合内容遥测被禁用或主机没有足够的权限来使用 API，则该 Promise 将被拒绝。
Mozilla.ContentTelemetry.registerEvents()¶
Mozilla.ContentTelemetry.registerEvents(category, eventData);
注册来自内容的新动态事件。这接受相同的参数，并受与Services.telemetry.registerEvents()相同的限制。请参阅events文档以获取权威参考。
注意
确保在记录事件之前调用此函数，并在加载库后立即调用（例如，窗口加载事件）。这将确保在记录时定义已准备就绪。
使用此函数注册的事件中记录的数据最终将出现在主 Ping 的dynamic进程部分。
示例
Mozilla.ContentTelemetry.registerEvents("page.interaction", {
"click": {
methods: ["click"],
objects: ["red_button", "blue_button"],
}
});
// Now events can be recorded.
Mozilla.ContentTelemetry.recordEvent("page.interaction", "click", "red_button");
Mozilla.ContentTelemetry.recordEvent()¶
Mozilla.ContentTelemetry.recordEvent(category, method, object, value, extra);
记录已注册的事件。这接受相同的参数，并受与Services.telemetry.recordEvent()相同的限制。请参阅events文档以获取权威参考。
示例
Mozilla.ContentTelemetry.recordEvent("ui", "click", "reload-btn");
// event: [543345, "ui", "click", "reload-btn"]
Mozilla.ContentTelemetry.recordEvent("ui", "search", "search-bar", "google");
// event: [89438, "ui", "search", "search-bar", "google"]
Mozilla.ContentTelemetry.recordEvent("ui", "completion", "search-bar", "yahoo",
{"querylen": "7", "results": "23"});
// event: [982134, "ui", "completion", "search-bar", "yahoo",
// {"qerylen": "7", "results": "23"}]
数据审查¶
在browser/app/permissions中为新域名添加hc_telemetry权限需要数据收集审查，因为我们正在启用一种新的数据收集方法。
授予域名使用混合内容遥测的权限也授予在此域名上运行的任何扩展使用混合内容遥测的权限。如果该域名已在受限域名列表（由extensions.webextensions.restrictedDomains首选项配置）中，则扩展不会在此域名上运行，因此无法访问混合内容遥测 API。无需其他批准。
如果该域名不在该列表中，则需要额外的隐私审查。在这种情况下，请寻求遥测团队的帮助。
测试¶
为了测试混合内容遥测集成，可以使用权限 API 来启用某些主机。Services.perms.addFromPrincipal API 在浏览器控制台以及具有访问Services.* API 的xpcshell和mochi测试中可用。
在该主机上的任何页面加载HybridContentTelemetry-lib.js文件之前，需要设置相应的hc_telemetry权限。
手动测试¶
启动浏览器后，打开浏览器控制台（工具 -> Web 开发 -> 浏览器控制台）。要启用 https://example.mozilla.org 上的混合内容遥测，请在控制台中执行此代码片段。
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin("https://example.mozilla.org");
Services.perms.addFromPrincipal(principal, "hc_telemetry", Services.perms.ALLOW_ACTION);
之后加载 https://example.mozilla.org 上的页面，它将能够记录遥测数据。
注意
手动测试需要一个处理 HTTPS 连接的主机，因为此类收集仅在安全主机上允许。为了允许本地测试，需要一个能够处理 HTTPS 连接的本地代理。
自动化测试¶
在具有特权访问权限的测试框架中，可以在 head.js 中或在测试设置期间设置权限。在您的 head.js 中添加代码片段，以在 https://example.mozilla.org 上启用混合内容内容遥测。
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin("https://example.mozilla.org");
Services.perms.addFromPrincipal(principal, "hc_telemetry", Services.perms.ALLOW_ACTION);
版本历史¶
Firefox 59：初始混合内容遥测支持 (bug 1417473).
Firefox 71：删除混合内容遥测 (bug 1520491).