GetAccountUserTrackData - 获取观众的用户画像详情--企业直播-火山引擎

文档中心

立即注册

导航

GetAccountUserTrackData - 获取观众的用户画像详情

最近更新时间：2025.04.29 12:16:34首次发布时间：2023.11.23 14:40:38

您可通过此接口获取指定观众的累计观看数据、互动数据及观看足迹等详细信息。

注意事项

请求频率：单用户请求频率限制为 1 次/秒。
前提条件：确保您拥有火山引擎主账号或具备数据中心 > 用户画像 > 仅查看或可编辑权限的子账号。有关如何添加子账号，详见子账号管理。

请求说明

请求方式：POST
请求地址：https://livesaas.volcengineapi.com/?Action=GetAccountUserTrackData&Version=2023-08-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息详见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`GetAccountUserTrackData`	接口名称。当前 API 的名称为 `GetAccountUserTrackData`。
Version	String	是	`2023-08-01`	接口版本。当前 API 的版本为 `2023-08-01`。

Body

参数	类型	是否必选	示例值	描述
UserId	Long	否	`12****239`	用户 ID，观众在企业直播的唯一标识。您可以通过 ListAccountUserData 接口获取 ID。说明至少传入 `UserId` 和 `ExternalId` 其中之一。如果同时传入，则 `UserId` 优先级更高。
ExternalId	String	否	`abc`	关联用户 ID，即观众在第三方平台的唯一标识。观众通过不同方式登录直播间，关联用户 ID 的取值如下所示。微信：观众在企业直播微信服务号的 OpenID。企业微信：绑定企业直播的企业内部成员 OpenID。自定义：自定义登录时通过 `UserId` 传入的值。详见自定义登录。 OAuth 2.0：您自有账号系统中用户 ID 对应的字段。飞书：绑定企业直播的飞书企业成员 Open ID。手机号：观众通过手机号注册企业直播后生成的 passport_id。白名单：观众输入的白名单校验信息。说明如果您集成了观播 SDK，且 SDK 的鉴权模式为自定义模式，关联用户 ID 的取值为调用 GetSDKTokenAPI 接口时传入的 `UserIdStr`（观众 ID）。至少传入 `UserId` 和 `ExternalId` 其中之一。如果同时传入，则 `UserId` 优先级更高。
WatchType	String	否	`123`	自定义观看限制的登录账号 App，即您自有账号系统的名称。您可调用 GetViewingRestrictionInfo 接口，通过 `CustomApp` 参数获取登录账号 App。当观看限制为自定义时，建议同时传入 `ExternalId` 和 `WatchType` 以便更准确地定位到具体观众。
ActivityId	Long	否	`1781****2348`	直播间 ID。您可以通过 ListActivityAPI 接口查询 ID。说明使用子账号调用接口时，确保该直播间对子账号可见。有关如何配置子账号的可见范围，详见子账号管理。
SelectTags	Array of SelectTags	否	`-`	根据分类标签信息进行筛选。您可以通过 ListSiteTagAPIV2 接口查询标签信息。

SelectTags

参数	类型	是否必选	示例值	描述
Index	Integer	否	`0`	标签的索引值。用于标识标签在控制台展示的位置。索引值越小，位置越靠前。
Value	Array of String	是	`["标签值"]`	分类标签值。
Name	String	否	`标签名称`	分类标签名称。

返回参数

参数	类型	示例值	描述
UserTrackData	Object of UserTrackData	`-`	完整的观众用户画像详情。
FilterUserTrack	Object of FilterUserTrack	`-`	筛选后的观众用户画像详情。说明通过 `ActivityId` 或 `SelectTags` 进行筛选时，该参数返回筛选后的观众用户画像详情，否则该参数为空。

UserTrackData

参数	类型	示例值	描述
UserTracks	Array of UserTracks	`-`	观看足迹。
UserTrackSum	Object of UserTrackSum	`-`	累计观看数据。
InteractData	Object of InteractData	`-`	互动数据。
PayData	Object of PayData	`-`	付费数据。

FilterUserTrack

参数	类型	示例值	描述
UserTracks	Array of UserTracks	`-`	观看足迹。
UserTrackSum	Object of UserTrackSum	`-`	累计观看数据。
InteractData	Object of InteractData	`-`	互动数据。
PayData	Object of PayData	`-`	付费数据。

UserTracks

参数	类型	示例值	描述
ActivityId	Long	`1781****2348`	直播间 ID。
ActivityName	String	`直播间 A`	直播间名称。
JoinTime	Long	`1681800648`	进入直播间的时间。Unix 时间戳，单位为秒。
WatchDurationLive	Integer	`600`	观看直播的时长。单位为秒。
WatchDurationReplay	Integer	`300`	观看回放的时长。单位为秒。
CommentCount	Integer	`868`	发送的评论数量（包括已删除评论和未通过聊天审核的评论等，但不包括图片评论）以及参与抽奖、红包等互动活动时发送的弹幕口令数。
LotteryAwards	Array of String	`["实物抽奖"]`	在实时抽奖中获得的奖品名称列表。
PayAmount	String	`2`	付费金额。

UserTrackSum

参数	类型	示例值	描述
WatchCount	Integer	`6`	观众累计观看的直播间数量。
WatchDuration	Integer	`170843`	观众访问观看页的累计页面访问时长。单位为秒。

InteractData

参数	类型	示例值	描述
ReservationCount	Integer	`1`	观众预约直播的次数。
VoteCount	Integer	`2`	观众参与投票的次数。
CommentCount	Integer	`89`	观众发送的评论数量（包括已删除评论和未通过聊天审核的评论等，但不包括图片评论）以及参与抽奖、红包等互动活动时发送的弹幕口令数。
QuestionnaireCount	Integer	`7`	观众填写问卷的次数。
LotteryCount	Integer	`1`	观众参与实时抽奖的次数。
LotteryHitCount	Integer	`1`	观众中奖的次数。
InviteCount	Integer	`1`	观众分享直播的次数，即有多少用户通过观众分享的专属链接、二维码或海报进入并登录直播间。
ShiftScreenNumber	Integer	`1`	观众触发切屏检测提醒弹窗的次数。
MuteNumber	Integer	`0`	观众触发静音停播提醒弹窗的次数。
NoInteractNumber	Integer	`1`	观众触发无互动检测提醒弹窗的次数。
ThumbUpNumber	Long	`1`	观众的直播间点赞数量。
CouponPickupCount	Long	`1`	观众领取的卡券数量。

PayData

参数	类型	示例值	描述
TotalAmount	String	`2`	付费金额。
PayCount	Integer	`1`	付费观看次数。

请求示例

POST https://livesaas.volcengineapi.com/?Action=GetAccountUserTrackData&Version=2023-08-01
{
    "UserId": 12****239,
    "ActivityId": 178123412348,
    "SelectTags": [
        {
            "Index": 0,
            "Value": [
                "标签值"
            ],
            "Name": "标签名称"
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "GetAccountUserTrackData",
        "Version": "2023-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1",
        "SystemTime": 1697446406
    },
    "Result": {
        "UserTrackData": {
            "UserTracks": [
                {
                    "ActivityId": 1781****2348,
                    "ActivityName": "直播间 A",
                    "JoinTime": 1681800648,
                    "WatchDurationLive": 600,
                    "WatchDurationReplay": 300,
                    "CommentCount": 868,
                    "PayAmount": "2",
                    "LotteryAwards": [
                        "实物抽奖"
                    ]
                }
            ],
            "PayData": {
                "TotalAmount": "2",
                "PayCount": 1
            },
            "InteractData": {
                "ReservationCount": 1,
                "MuteNumber": 0,
                "NoInteractNumber": 1,
                "ShiftScreenNumber": 1,
                "InviteCount": 1,
                "LotteryHitCount": 1,
                "LotteryCount": 1,
                "QuestionnaireCount": 7,
                "CommentCount": 89,
                "VoteCount": 2,
                "CouponPickupCount": 1,
                "ThumbUpNumber": 1
            },
            "UserTrackSum": {
                "WatchCount": 6,
                "WatchDuration": 170843
            }
        },
        "FilterUserTrack": {
            "UserTracks": [
                {
                    "ActivityId": 17****648,
                    "ActivityName": "直播间 A",
                    "JoinTime": 1681822654,
                    "WatchDurationLive": 600,
                    "WatchDurationReplay": 300,
                    "CommentCount": 86,
                    "PayAmount": "2",
                    "LotteryAwards": [
                        "实物抽奖"
                    ]
                }
            ],
            "PayData": {
                "TotalAmount": "2",
                "PayCount": 1
            },
            "InteractData": {
                "ReservationCount": 1,
                "MuteNumber": 0,
                "NoInteractNumber": 1,
                "ShiftScreenNumber": 1,
                "InviteCount": 1,
                "LotteryHitCount": 1,
                "LotteryCount": 1,
                "QuestionnaireCount": 7,
                "CommentCount": 89,
                "VoteCount": 2,
                "CouponPickupCount": 1,
                "ThumbUpNumber": 1
            },
            "UserTrackSum": {
                "WatchCount": 6,
                "WatchDuration": 170843
            }
        }
    }
}

错误码

下表提供了该接口特有的错误码，公共错误码请参见公共错误码和错误码文档。

状态码	错误码	错误信息	说明
400	InvalidParameter.InvalidAccountId	The specified parameter AccountId is invalid.	当前账号的鉴权信息错误。
400	InvalidParameter.InvalidUserId	The specified parameter UserId is invalid.	`UserId` 参数不符合规范，请修改后重试。
500	InternalError	Data search inner error, please try again.	数据搜索服务出现内部错误。请重试。