提交自定义 Ping

可以使用 JavaScript 提交自定义 Ping

TelemetryController.submitExternalPing(type, payload, options)

  • type - 一个 string，表示 Ping 的类型，限制为 /^[a-z0-9][a-z0-9-]+[a-z0-9]$/i。

  • payload - Ping 的实际有效负载数据，必须是 JSON 样式的对象。

  • options - 可选，包含其他选项的对象

    • addClientId - 是否将客户端 ID 和配置文件组 ID 添加到 Ping 中，默认为 false

    • addEnvironment - 是否将环境数据添加到 Ping 中，默认为 false

    • overrideEnvironment - 一个 JSON 样式的对象，覆盖环境数据

TelemetryController 将使用传递的有效负载和指定的选项组装一个 Ping。该 Ping 将在本地存档，以供 Shield 使用并在 about:telemetry 中检查。如果首选项允许上传遥测 Ping，则 Ping 将在下一次机会上传（这受限于节流、故障重试等）。

重要

Firefox 中的每个新的或更改的数据收集都需要来自数据管理员的 数据收集审查。

提交约束

在关闭时提交 Ping 时，不应在遥测关闭后提交。Ping 应至迟在以下时间提交：

还有其他约束可能导致 Ping 提交被丢弃

  • 无效的 Ping 类型字符串。

  • 无效的有效负载类型：例如，字符串而不是对象。

  • 有效负载过大：我们目前仅丢弃 >1MB 的 Ping，但建议目标大小为 <=10KB。

工具

用于设计新 Ping 的有用工具包括

  • gzipServer - 一个可以在本地运行并接收和保存遥测 Ping 的 Python 脚本。使 Firefox 发送到它可以轻松地检查传出的 Ping。

  • about:telemetry - 允许检查本地存档中提交的 Ping，包括所有自定义 Ping。

设计自定义 Ping

通常，创建新的自定义 Ping 意味着您不会自动从现有的工具中受益。需要进一步的工作才能使数据显示在 re:dash 或其他分析工具中。

除了 数据收集审查 之外，指导新 Ping 设计的问题还有

  • 提交间隔 & 触发器

    • 哪些事件会触发 Ping 提交？

    • Ping 以什么间隔提交？

    • 是否存在节流机制？

    • 所需的延迟是多少？(提交“至少每天”仍然会导致某些延迟尾部)

    • Ping 是基于时钟计划提交的吗？还是基于“自会话开始以来的时间”、“自上次 Ping 以来的时间”等？（即，提交量是否会出现尖峰？）

  • 大小和数量

    • 提交的有效负载的大小是多少？

    • 包括管道中元数据的完整 Ping 大小是多少？

    • 目标人群是谁？

    • 总体估计数量是多少？

  • 数据集

    • 它是选择退出吗？

    • 它是否需要选择退出？

    • 它是否需要在单独的 Ping 中？(为什么数据不能存在于探测器中？)

  • 隐私

    • 是否存在泄露 PII 的风险？

    • 如何降低该风险？

  • 数据内容

    • 提交的数据是否回答了提出的产品问题？

    • 数据的形状是否允许有效地回答问题？

    • 数据是否仅限于回答问题所需的内容？

    • 数据是否使用通用格式？(即，我们能否重用工具或分析专业知识)