Custom Audience Tag Interface

Purpose

Dynamically display image tags such as levels, membership status, and verification badges for different audience members. Tags are shown near the nickname of regular audience members in the chat area.

The custom audience tag interface is requested directly by the viewer's browser, not by a Polyv server-side callback. The viewer replaces placeholders in the configured URL with the current audience member's information and loads the generated address as an image.

URL Template

The interface address supports placeholders. For example:

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

Assuming the current chat room user ID is viewer_1001, the actual URL requested by the viewer is:

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

Currently supported placeholders:

Placeholder usage rules:

• Placeholders are case-sensitive and must retain the English curly braces.
• Multiple identical placeholders in the same URL will all be replaced.
• If the URL contains no placeholders, all regular audience members will load the same tag image.
• Placeholders not listed in the table above will not be replaced, e.g., {viewerId}, {userid}, or %7BuserId%7D.

Request Description

The viewer will directly set the complete replaced URL as the <img> attribute of an src tag. Therefore, the interface URL and its query parameters are visible to end users, and the interface cannot rely on Polyv server IPs, callback signatures, or custom headers for authentication.

Response Requirements

The customer interface must directly return an image resource that the browser can load.

Response example:

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

<图片二进制数据>

Do not return JSON, HTML, Base64 text, or image URL strings. For example, {"imageUrl":"https://example.com/label.png"} cannot be displayed as a tag image.

The display height of the tag on the page is 14px, and the width will scale proportionally. It is recommended to use horizontal images with a transparent background and provide clear image resources suitable for high-resolution screens. If a particular audience member has no tag, it is recommended to return a valid transparent image to avoid a broken image icon.

How to Configure

1. Log in to the live streaming management console.
2. Go to [Settings] → [Developer Settings] → [Callbacks & Interfaces] → [Interface Settings].
3. Fill in the URL template under [Custom Audience Tag Interface] and save.

This configuration is account-level; all channels under the account share the same URL template. Clearing the interface URL and saving will disable the custom audience tag display.

Notes

• It is recommended to use HTTPS URLs. Loading HTTP images on an HTTPS viewing page may be blocked by the browser as mixed content.
• The interface must be directly accessible from the viewer's browser over the public internet. Normal cross-origin <img> image display typically does not require CORS configuration; if the server has hotlink protection enabled, ensure the viewing page can access the image normally.
• Do not include sensitive information such as AppSecret or fixed access tokens in the configured URL, as the complete URL may appear in page source code, browser network panels, and access logs.
• Implement concurrency control, rate limiting, and caching based on traffic volume. When tag content changes, cache can be controlled via Cache-Control, ETag, or a fixed version parameter in the URL.
• Validate the userId parameter; do not directly concatenate it into file paths or database queries.
• Only regular audience members display custom tags; special roles such as instructors, teaching assistants, and administrators do not display them.
• If the interface request fails or the returned content cannot be parsed as an image, the corresponding tag will not display properly.