Matomo设备检测库中的Client Hints技术解析

什么是Client Hints

Client Hints是一项现代Web技术，允许服务器从浏览器获取更详细的客户端设备信息，而无需依赖传统的User-Agent字符串。这项技术在Matomo的device-detector库中得到了实现，为网站分析提供了更精确的设备检测能力。

Client Hints的两种获取方式

1. HTTP Header方式

通过HTTP头部获取Client Hints是传统的方式，需要服务器明确声明希望接收哪些提示信息。服务器可以通过以下三种方式请求客户端提示：

1. PHP header函数：

header('accept-ch', implode(', ', [
    'sec-ch-ua-full-version',
    'sec-ch-ua-full-version-list',
    'sec-ch-ua-platform',
    'sec-ch-ua-platform-version',
    'sec-ch-ua-arch',
    'sec-ch-ua-bitness',
    'sec-ch-prefers-color-scheme'
]));

2. NGINX配置：

server {
   add_header accept-ch "sec-ch-ua-full-version, sec-ch-ua-full-version-list, sec-ch-ua-platform, sec-ch-ua-platform-version, sec-ch-ua-arch, sec-ch-ua-bitness, sec-ch-prefers-color-scheme";
}

3. HTML meta标签：

<meta http-equiv="Accept-CH" content="sec-ch-ua-full-version, sec-ch-ua-full-version-list, sec-ch-ua-platform, sec-ch-ua-platform-version, sec-ch-ua-arch, sec-ch-ua-bitness, sec-ch-prefers-color-scheme" />

需要注意的是，使用HTTP方式获取的Client Hints通常只在第二次请求时才会生效，因为第一次请求时浏览器还不知道服务器需要哪些提示信息。

2. JavaScript API方式

通过JavaScript的User-Agent Client Hints API可以更直接地获取客户端信息，这种方式能立即获得提示数据，不需要等待第二次请求。以下是典型的实现代码：

async function getClientHints() {
  let hints = [
    'brands',
    'mobile',
    'platform',
    'platformVersion',
    'architecture',
    'bitness',
    'wow64',
    'model',
    'uaFullVersion',
    'fullVersionList'
  ];
  let hintsData = await navigator.userAgentData.getHighEntropyValues(hints);
  return JSON.parse(JSON.stringify(hintsData));
}

获取到数据后，可以通过AJAX等方式将数据发送到服务器进行分析。

Matomo设备检测库的实现

Matomo的device-detector库设计了一个灵活的ClientHints类，能够同时处理来自HTTP头部和JavaScript API的数据。这种设计使得开发者可以根据实际情况选择最适合的获取方式。

在内部实现上，库会将不同来源的数据统一处理，确保无论数据来自HTTP头部还是JavaScript API，都能得到一致的解析结果。例如，对于浏览器品牌和版本信息，无论是通过sec-ch-ua头部传递的字符串格式，还是通过JavaScript API传递的JSON格式，都会被转换为统一的数据结构。

技术优势与应用场景

Client Hints相比传统User-Agent字符串具有多个优势：

1. 更精确的数据：直接从浏览器获取信息，减少了UA字符串解析的误差
2. 按需获取：只请求需要的提示信息，减少不必要的数据传输
3. 更好的隐私控制：用户可以更精细地控制分享哪些设备信息

这项技术特别适合需要精确设备信息的场景，如：

• 网站分析工具
• 响应式设计适配
• 功能兼容性检测
• 性能优化决策

总结

Matomo的device-detector库通过支持Client Hints技术，为开发者提供了更现代、更精确的设备检测方案。无论是通过HTTP头部还是JavaScript API获取数据，都能得到一致且可靠的结果。随着浏览器对这项技术支持的不断完善，Client Hints有望成为未来Web开发中设备检测的标准方式。