文档中心

获取观众行为数据信息

最近更新时间：2023.07.25 11:41:07

首次发布时间：2022.03.29 22:10:12

获取当前直播间的观众行为数据。

说明

企业直播新增渠道推广功能，支持创建不同的渠道。有关如何创建渠道，详见渠道推广。对于使用了渠道推广功能的直播间，请调用 ListUserBehaviorDataAPIV2 接口获取不同渠道的数据信息。如果您未使用渠道推广功能，请调用本接口获取观众行为数据信息。

请求说明

接口名称：ListUserBehaviorDataAPI
请求方式：GET
接口地址：http://livesaas.volcengineapi.com/?Action=ListUserBehaviorDataAPI&Version=2020-06-01
请求频率：单用户请求频率限制为 120 次/分钟。

请求参数

以下请求参数列表仅列出了该接口的部分公共参数，完整公共参数列表见公共请求参数。

Query

参数	类型	是否必选	描述
Action	String	是	接口名称
Version	String	是	接口版本。直播当前 API 的版本为 2020-06-01
ActivityId	Int64	是	直播间 ID。您可通过ListActivityAPI 接口查询 ID
PageNo	Int	否	分页查询页码，默认取值为 `1`。使用滚动查询时，`PageNo` 取值范围为 [1,2^64]。有关滚动查询，详见请求参数 `ScrollId`。未使用滚动查询时，接口最多支持返回 10,000 条查询结果，即 `PageNo`×`PageItemCount`≤10,000。
PageItemCount	Int	否	分页查询数量，取值范围为 [1,500]，默认取值为 `10`。
ScrollId	String	否	滚动查询 ID。滚动查询方式适用于查询 10,000 条以上数据的场景。如需使用滚动查询方式，确保满足以下要求：首次调用接口查询数据时无需设置该参数值（即参数值为空），第二次调用接口查询时将该参数值设置为首次查询返回参数中 `ScrollId` 的值，第三次调用接口查询时将该参数值设置为第二次查询返回参数中 `ScrollId` 的值，依次类推。说明当 `IsMerge` 或 `IsMergeUserId` 取值为 `1` 时，若调用接口进行滚动查询，则 `ScrollId` 取值固定为空。返回参数中 `ScrollId` 值的失效时间为 20 分钟，即超过 20 分钟该 `ScrollId` 值会失效，无法使用该值进行下一次查询。首次调用接口查询数据时将 `PageNo` 的值设置为 `1`，第二次调用接口查询时将 `PageNo` 的值设置为 `2`，依次类推。说明 `PageNo` 的值只能按照顺序依次递增且不支持输入重复的数值。在调用接口查询数据时，除 `ScrollId` 和 `PageNo` 参数外，确保 `IsMerge` 和 `IsMergeUserId` 参数的值保持不变。
Name	String	否	模糊查询字符串
StartTime	Int64	否	查询开始时间，Unix 时间戳，单位为秒
EndTime	Int64	否	查询结束时间，Unix 时间戳，单位为秒
IsMerge	Int	否	当同一个设备多次进出直播间时，是否合并为 1 次。支持以下两种取值，默认取值为 `0`。 0：不合并 1：合并
Source	Int32	否	根据页面访问来源进行筛选。支持以下取值，默认取值为 `0`。 -1：查询所有 0：查询默认来源 1：查询来源 A 2：查询来源 B 3：查询来源 C 4：查询来源 D
PlayStatus	Int32	否	根据直播状态进行筛选。支持以下取值，默认取值为 `10`。 1：直播状态观看 2：预告状态观看 3：回放状态观看 10：页面停留 11：所有状态总观看
IsMergeUserId	Int	否	当同一个用户多次进出直播间时，是否合并为 1 次。支持以下取值，默认取值为 `0`。 0：不合并 1：合并
Extra	String	否	根据业务方扩展参数进行筛选。

返回参数

参数	类型	描述
TotalItemCount	Int	观众行为总数
Data	Array of UserBehaviorData	观众行为详细数据
ScrollId	String	滚动查询 ID

UserBehaviorData

参数	类型	描述
UserId	Int64	用户 ID
UserName	String	用户名称
Region	String	所在地区
IP	String	IP 地址，若是合并时，多个 IP 用空格分隔
JoinAt	Array of Int	用户进入直播间的时间，与 `LeaveAt` 一一对应
LeaveAt	Array of Int	用户离开直播间的时间，与 `JoinAt` 一一对应
WatchTime	Int	观看时长，单位为分
UserTel	String	用户手机号
InviteCode	String	用户所用邀请码
AccessTime	String	用户进入时机。支持以下取值。 playing：直播中 playing before：直播前 playing post：直播后
UserDevice	Array of String	用户使用的终端类型
Extra	String	业务方扩展参数
ExternalUserId	String	自定义鉴权传入的客户侧 ID
SilenceStatus	Int32	查询时用户是否被禁言。 1：已禁言；其它：未禁言。
ChannelName	String	已废弃

示例

请求示例

Get http://livesaas.volcengineapi.com/?Action=ListUserBehaviorDataAPI&Version=2020-06-01&ActivityId=1231231231&PageNo=1&PageItemCount=10&StartTime=1643708567&EndTime=1648719767&IsMerge=1&Source=-1&PlayStatus=1&IsMergeUserId=1

正常返回示例

{
      "ResponseMetadata":{
            "RequestId":"2022012018261701***",
            "Action":"ListUserBehaviorDataAPI",
            "Version":"2020-06-01",
            "Service":"livesaas",
            "Region":"cn-north-1",
            "SystemTime":1656067132
      },
      "Result":{
            "TotalItemCount":1,
            "ScrollId":"abc",
            "Data":[{
                  "UserId":11,
                  "UserName":"ab",
                  "Region":"美国",
                  "IP":"127.0.0.1   127.0.0.2",
                  "JoinAt":[xxx],
                  "leaveAt":[xxx],
                  "WatchTime":111,
                  "UserTel":"151xxx",
                  "InviteCode":"21",
                  "AccessTime":"playing",
                  "UserDevice":"[   CPU   iPhone   OS   10_3_1   like   Mac   OS   X   ]",
                  "Extra"   :   "abc",
                  "ExtraUserId"   :   "1efcsds***",
                  "SilenceStatus": 1,
                  "ChannelName":"渠道1"
            }]
      }
}

异常返回示例

{
    "ResponseMetadata":{
        "RequestId":"201806041104200100100232280022D30",
        "Action":"ListUserBehaviorDataAPI",
        "Version":"2020-06-01",
        "Service":"livesaas",
        "Region":"cn-north-1",
        "SystemTime":1656067132,
        "Error":{
            "Code":"200000",
            "Message":"参数异常" 
     }
  }
}

错误码

访问公共错误码和错误码获取详细信息。