Save Full User Level List

API Description

1、全量保存账号的用户等级列表：请求中的等级列表会整体覆盖原有等级，未包含在请求中的等级将被删除，数组顺序即等级顺序
2、（timestamp, appId）参与sign签名，并和sign一起通过url传递，请求体参数不参与签名，通过post请求体传递【请设置请求头contentType:application/json】
3、用户等级为账号级配置，账号下所有频道共用同一套等级；直播模板和频道只控制是否展示等级
4、管理后台【用户】→【用户等级】和开放API读写同一份配置，任一入口保存成功后，另一入口查询到相同结果
5、接口支持https协议

API URL

http://api.polyv.net/live/v4/user/viewer-level/save

Online API Call

Request Method

POST

API Constraints

1. The API supports both HTTP and HTTPS. HTTPS is recommended for security. API calls have frequency limits. See details

2. The target account is determined by appId in the signature. User ID or channel number is not accepted.

3. Each account must retain at least 1 level and can save up to 100 levels. Level identifiers levelId in the same request cannot be duplicated.

4. For accounts with Polyv User System enabled, each level must have a points threshold requiredPoints, which must strictly increase in array order (the threshold of a later level must be greater than the previous one).

5. For accounts without the user system enabled, only display configurations such as level name, icon, background color, and description are saved. The requiredPoints in the request does not take effect: existing levels (matched by levelId) retain their original points threshold, and new levels have a threshold of 0.

6. It is recommended to first call Query User Level List to get the current configuration, modify it, and then submit the entire list to avoid accidentally deleting levels.

7. For details on user level functionality, see User Levels.

Request Parameter Description

Request Body Parameter Description

levels Parameter Description

Example

http://api.polyv.net/live/v4/user/viewer-level/save?appId=frlr1zazn3&sign=49428741C1D7BEE8BE1EE545F066ECC7&timestamp=1677167340447

Request body JSON parameters:

{
    "levels": [
        {
            "levelId": "bronze",
            "levelName": "青铜",
            "levelIcon": "https://s1.videocc.net/default-img/level-icon/v1/bronze.png",
            "levelBgColor": "#FF6456",
            "description": "新用户默认等级",
            "requiredPoints": 1
        },
        {
            "levelId": "silver",
            "levelName": "白银",
            "levelBgColor": "#5E81FF",
            "requiredPoints": 1000
        }
    ]
}

Response Parameter Description

Error Parameter Description

Java Request Example

For quick integration of basic code, download the relevant dependency source code. Click to download source code. After downloading, add it to your own source project. The test cases include HttpUtil.java and LiveSignUtil.java in the downloaded file.

It is strongly recommended to use the Live Java SDK for API integration. The Live Java SDK provides unified encapsulation and optimization for API call logic, exception handling, data signing, and HTTP request thread pooling.

private static final Logger log = LoggerFactory.getLogger(getClass());
/**
* 全量保存用户等级列表
* @throws IOException
* @throws NoSuchAlgorithmException
*/
@Test
public void testViewerLevelSave() throws IOException, NoSuchAlgorithmException {
    //公共参数,填写自己的实际参数
    String appId = super.appId;
    String appSecret = super.appSecret;
    String timestamp = String.valueOf(System.currentTimeMillis());

    //业务参数
    String url = "http://api.polyv.net/live/v4/user/viewer-level/save";
    List<Map<String, Object>> levels = new ArrayList<>();

    Map<String, Object> bronze = new HashMap<>();
    bronze.put("levelId", "bronze");
    bronze.put("levelName", "青铜");
    bronze.put("levelIcon", "https://s1.videocc.net/default-img/level-icon/v1/bronze.png");
    bronze.put("levelBgColor", "#FF6456");
    bronze.put("description", "新用户默认等级");
    bronze.put("requiredPoints", 1);
    levels.add(bronze);

    Map<String, Object> silver = new HashMap<>();
    silver.put("levelId", "silver");
    silver.put("levelName", "白银");
    silver.put("levelBgColor", "#5E81FF");
    silver.put("requiredPoints", 1000);
    levels.add(silver);

    //http 调用逻辑
    Map<String, String> requestMap = new HashMap<>();
    requestMap.put("appId", appId);
    requestMap.put("timestamp", timestamp);

    Map<String, Object> jsonMap = new HashMap<>();
    jsonMap.put("levels", levels);

    requestMap.put("sign", LiveSignUtil.getSign(requestMap, appSecret));

    url = HttpUtil.appendUrl(url, requestMap);
    String response = HttpUtil.postJsonBody(url, JSON.toJSONString(jsonMap), null);

    log.info("测试全量保存用户等级列表，返回值：{}", response);
    //do somethings

}

Response Example

For global error descriptions, see Global Error Description

Success Example

{
    "code": 200,
    "status": "success",
    "requestId": "414afeb28f1c4f0ca17e1c3c1e39d247.71.16771673423081591",
    "data": true,
    "success": true
}

Error Example

{
    "code": 400,
    "status": "error",
    "requestId": "d310b70bc329403f87f77f9203d50f89.128.16360831552223589",
    "error": {
        "code": 25105,
        "desc": "最低积分需大于上一等级的最低积分"
    },
    "success": false
}

Error Code Description