Polyv Help Center

Help Center

Query Viewer Reward Details Paginated List

Updated: 2025-09-25 11:46:33

API Description

1、观众查询奖励明细分页列表
2、接口支持https协议

API URL

https://api.polyv.net/live/v4/user/viewer-task-reward/page

Request Method

GET

API Constraints

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

Request Parameters Description

Parameter Required Type Description
appId true String Account appId See details on obtaining keys
timestamp true Long Current 13-digit millisecond timestamp, valid for 3 minutes
sign true String Signature, a 32-character uppercase MD5 value. The appSecret key used to generate the signature is critical for communication data security. It must never be saved or used directly on the client side. All APIs must be called through the customer's own server to relay requests to the POLYV server and retrieve response data. See signature generation rules
viewerId true String Viewer ID
pageSize false Integer Page size (default 10, max 1000)
pageNumber false Integer Page number (currently limited to max 1000 pages)

Example

https://api.polyv.net/live/v4/user/viewer-task-reward/page?viewerId=123&pageSize=10&pageNumber=1&appId=frlr1zazn3&sign=012332FBD8DBCFC068AFCB484A2ADECB&timestamp=1670550787318

Response body JSON:

{
    "code": 200,
    "status": "success",
    "requestId": "c2318da1-7dec-417a-9be4-25980b6372eb",
    "data": {
        "pageNumber": 1,
        "pageSize": 10,
        "totalPages": 1,
        "totalItems": 6,
        "contents": [
            {
                "id": 1693913,
                "viewerId": "2_844u9odbkqq8eum0rpotqbexwqlio6pq",
                "taskId": 10550,
                "sort": 1,
                "taskReach": {
                    "type": "online",
                    "amount": 1,
                    "questionnaireId": null,
                    "customEvent": null,
                    "customEventName": null,
                    "customIcon": null,
                    "customUnit": null,
                    "customButtonText": null,
                    "customReachText": "{customEventName}{amount}{customUnit}"
                },
                "taskReward": {
                    "type": "cash",
                    "amount": "0.3",
                    "limit": -1,
                    "customReward": ""
                },
                "acceptInfo": {
                    "activeAcceptEnabled": "Y",
                    "acceptType": "form",
                    "received": "N",
                    "formInfo": {
                        "field": "姓名",
                        "tips": "请输入您的名称",
                        "type": "userName",
                        "required": true
                    },
                    "prizeUrl": null,
                    "qrCode": null,
                    "qrCodeTips": null
                },
                "taskStatus": 1,
                "rewardStatus": 1,
                "finishTime": 1742284276000,
                "outTradeErrCode": null,
                "outTradeErrDesc": null,
                "participated": true
            }
        ]
    },
    "success": true
}

Response Parameters Description

Parameter Type Description
code Integer Response status code, 200 for success, non-200 for failure
status String Response result, determined by business logic, returns success on success, error on failure
success Boolean Response result, determined by business logic, returns true on success, false on failure
data Object Viewer task reward details See Data field description
error Object Error information when status code is non-200 See Error field description
requestId String Request ID, a unique UUID generated for each request, for troubleshooting and debugging only, not for business logic

Data Parameters Description

Parameter Type Description
pageNumber Integer Page number
pageSize String Page size
totalPages Boolean Total number of pages
totalItems Object Total number of records
contents Array Activity data list See Contents field description

Contents Parameters Description

Parameter Type Description
channelId Integer Channel ID
activityId Long Activity ID
viewerId String Viewer ID
taskId Integer Task ID
sort Long Sort order
taskStatus Long Achievement status (0: Not achieved, 1: Achieved)
rewardStatus Long Reward distribution status (-1: No distribution needed, 0: Pending distribution, 1: Distributed, 2: Quota full, 3: Distribution failed, 4: Distributing)
finishTime Long Achievement time
taskReach Object Achievement conditions See taskReach field description
taskReward Object Reward data See taskReward field description
acceptInfo Object Acceptance information See acceptInfo field description

taskReach Parameters Description

Parameter Type Description
type String Achievement condition (sign: Check-in, online: Online duration)
amount Integer Achievement value

taskReward Parameters Description

Parameter Type Description
type String cash: Cash, custom: Custom, nothing: No reward, externalPoint: External points
amount Integer Reward value (when type is cash, the unit is cents)
limit Integer Reward limit quota
customReward String Custom reward, optional

acceptInfo Parameters Description

Parameter Type Description
activeAcceptEnabled String Custom acceptance info (Y: Enabled, N: Disabled)
acceptType String Acceptance method (form, link, qrCode)
received String Whether received (Y: Yes, N: No)
formInfo Array Acceptance form information See formInfo field description
prizeUrl String Redirect URL
qrCode String QR code URL
qrCodeTips String QR code tips

formInfo Parameters Description

Parameter Type Description
type String Type, userName: Name, userPhone: Phone number, custom: Custom
field String Field name
tips String Prompt text
required Boolean Whether required, true/false
value String Filled content

error Parameters Description

Parameter Type Description
code Integer Error code, used to identify the specific error
desc String Error description, corresponding to error.code

Java Request Example

For quick integration of basic code, download the relevant dependency source code. Click here to download the 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 packaging and optimization for API call logic, exception handling, data signing, and HTTP request thread pools.

private final Logger log = LoggerFactory.getLogger(getClass());
/**
 * 查询任务奖励活动观众奖励明细分页列表
 * @throws IOException
 * @throws NoSuchAlgorithmException
 */
@Test
public void pageTaskRewardTest() throws IOException, NoSuchAlgorithmException {
        //公共参数,填写自己的实际参数
        String appId = super.appId;
        String appSecret = super.appSecret;
        String timestamp = String.valueOf(System.currentTimeMillis());
        String viewerId = "123";
        Integer pageNumber = 1;
        Integer pageSize = 10;
        //业务参数
        String url = "https://api.polyv.net/live/v4/channel/task-reward-activity/page";
        
        //http 调用逻辑
        Map<String, String> requestMap = new HashMap<>();
        requestMap.put("appId", appId);
        requestMap.put("timestamp", timestamp);
        requestMap.put("viewerId", viewerId);
        requestMap.put("pageSize", pageSize);
        requestMap.put("pageNumber", pageNumber);
        requestMap.put("sign", LiveSignUtil.getSign(requestMap, appSecret));
        String response = HttpUtil.get(url, requestMap);
        log.info("测试查询任务奖励活动观众奖励明细分页列表成功：{}", response);
        //do somethings
}

Response Example

For system-wide error descriptions, see Global Error Descriptions

Success Example

{
    "code": 200,
    "status": "success",
    "requestId": "c2318da1-7dec-417a-9be4-25980b6372eb",
    "data": {
        "pageNumber": 1,
        "pageSize": 10,
        "totalPages": 1,
        "totalItems": 6,
        "contents": [
            {
                "id": 1693913,
                "viewerId": "2_844u9odbkqq8eum0rpotqbexwqlio6pq",
                "taskId": 10550,
                "sort": 1,
                "taskReach": {
                    "type": "online",
                    "amount": 1,
                    "questionnaireId": null,
                    "customEvent": null,
                    "customEventName": null,
                    "customIcon": null,
                    "customUnit": null,
                    "customButtonText": null,
                    "customReachText": "{customEventName}{amount}{customUnit}"
                },
                "taskReward": {
                    "type": "cash",
                    "amount": "0.3",
                    "limit": -1,
                    "customReward": ""
                },
                "acceptInfo": {
                    "activeAcceptEnabled": "Y",
                    "acceptType": "form",
                    "received": "N",
                    "formInfo": {
                        "field": "姓名",
                        "tips": "请输入您的名称",
                        "type": "userName",
                        "required": true
                    },
                    "prizeUrl": null,
                    "qrCode": null,
                    "qrCodeTips": null
                },
                "taskStatus": 1,
                "rewardStatus": 1,
                "finishTime": 1742284276000,
                "outTradeErrCode": null,
                "outTradeErrDesc": null,
                "participated": true
            }
        ]
    },
    "success": true
}

Error Example

{
    "code": 400,
    "status": "error",
    "requestId": "d310b70bc329403f87f77f9203d50f89.128.16360831552223589",
    "error": {
        "code": 20001,
        "desc": "application not found."
    },
    "success": false
}
联系客服，在线咨询
在线咨询