# `naisi_user_agent_to_mark`

从浏览器 User-Agent 文本生成“操作系统 浏览器 10字符指纹”客户端标记。

指纹部分独立实现 10 位 Base36 HMAC，不共用字符串指纹或路由摘要函数。
使用许可项目私有盐和当前构建的内部指纹材料，不使用服务器设备的机器指纹、
Customer ID、Build ID 或 License ID。相同 User-Agent 字节只有在项目私有盐、内部
指纹材料和算法版本相同时才会生成相同标记。

注意：User-Agent 会随浏览器版本、系统、隐私设置或代理改写而变化。本结果只能用于
客户端分类、风控辅助或展示，不得作为稳定用户 ID、设备唯一 ID 或单独认证凭据。

## 函数签名

```php
function naisi_user_agent_to_mark(string $user_agent): string
```

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/naisi-is-ext-license-valid) 并确认返回 `true`。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：`LICENSE`；执行模式：`PROOF`。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

## 参数

### `$user_agent`

- 类型：`string`
- 必填：是
- 默认值：无
- 方向：输入参数。

需要分类的原始 User-Agent 字节字符串，长度必须为 1 至 8192 字节，并包含“Mozilla/5.0 ”。大小写、空白和版本号差异均可能改变结果。

## 返回值

类型：`string`

有效输入返回“操作系统 浏览器 指纹”，最后一段是 10 字符小写 Base36 指纹；无法识别的操作系统或浏览器使用 "null" 占位；User-Agent 格式不符合要求时返回字面量 "ERROR"；未授权或内部处理失败时返回空字符串。

## 调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

```php
$user_agent = 'Mozilla/5.0 NaisiTest';

$result = naisi_user_agent_to_mark($user_agent);
var_export($result);
```

## 固定返回标记与格式

- 正常结果固定为 `操作系统 浏览器 10字符指纹`；指纹仅使用小写 Base36 字符 `0-9`、`a-z`。
- 无法识别操作系统或浏览器时，对应位置固定使用字面量 `null`。
- User-Agent 为空、超过 8192 字节或不包含 `Mozilla/5.0 ` 时，固定返回字面量 `ERROR`。
- 许可无效、指纹材料不可用或内部处理失败时返回空字符串 `""`，它与 `ERROR` 的含义不同。

## 版本信息

- 自版本：`1.0.6`
- 实现模块：`client`
- 授权类别：`LICENSE` / `PROOF`
- 失败回退：空字符串 `""`
- 文档同步：`2026-10-18`