自定义观众标签接口

作用

为不同观众动态展示等级、会员身份、认证标识等图片标签。标签显示在聊天区普通观众的昵称附近。

自定义观众标签接口由观看端浏览器直接请求，不是保利威服务端回调。观看端会将配置地址中的占位符替换为当前观众信息，再将生成的地址作为图片地址加载。

地址模板

接口地址支持使用占位符。例如：

https://example.com/viewer-label?userId={userId}

假设当前聊天室用户 ID 为 viewer_1001，观看端实际请求的地址为：

https://example.com/viewer-label?userId=viewer_1001

当前支持的占位符：

占位符使用规则：

• 占位符区分大小写，必须保留英文花括号。
• 同一地址中的多个相同占位符都会被替换。
• 如果地址中不包含占位符，所有普通观众将加载同一个标签图片。
• 不在上表中的占位符不会被替换，例如 {viewerId}、{userid} 或 %7BuserId%7D。

请求说明

观看端会将替换后的完整地址直接设置为 <img> 标签的 src。因此，接口地址及其查询参数对终端用户可见，接口不能依赖保利威服务端 IP、回调签名或自定义请求头完成鉴权。

响应要求

客户接口必须直接返回浏览器可加载的图片资源。

响应示例：

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: private, max-age=300

<图片二进制数据>

不要返回 JSON、HTML、Base64 文本或图片 URL 字符串。例如，{"imageUrl":"https://example.com/label.png"} 无法作为标签图片展示。

标签在页面中的展示高度为 14px，宽度会按原图比例自适应。建议使用透明背景的横向图片，并提供适合高分屏显示的清晰图片资源。某个观众没有标签时，建议返回有效的透明图片，避免出现图片加载失败的图标。

如何设置

1. 登录直播管理后台。
2. 进入【设置】→【开发设置】→【回调与接口】→【接口设置】。
3. 在【自定义观众标签接口】中填写地址模板并保存。

该配置为账号级配置，账号下的频道共用同一地址模板。清空接口地址并保存后，将不再展示自定义观众标签。

注意事项

• 建议使用 HTTPS 地址。HTTPS 观看页加载 HTTP 图片时，可能被浏览器作为混合内容拦截。
• 接口需要能够被观看端浏览器从公网直接访问。普通跨域 <img> 图片展示通常不要求配置 CORS；如果服务端启用了防盗链，请确保观看页可以正常访问图片。
• 不要在配置地址中放置 AppSecret、固定访问令牌等敏感信息，完整地址可能出现在页面源码、浏览器网络面板及访问日志中。
• 请根据访问量做好并发控制、限流和缓存。标签内容会变化时，可通过 Cache-Control、ETag 或地址中的固定版本参数控制缓存。
• 请校验 userId 参数，不要直接将其拼接到文件路径或数据库语句中。
• 仅普通观众展示自定义标签，讲师、助教、管理员等特殊身份不展示。
• 接口请求失败或返回的内容无法解析为图片时，对应标签将无法正常展示。