You need to enable JavaScript to run this app.
导航
企业直播
  • 文档首页
    • /企业直播/API 参考/数据查询/Version：2023-08-01/获取直播间营销推广点击数据
获取直播间营销推广点击数据
最近更新时间：2024.06.25 12:10:43首次发布时间：2024.03.01 14:04:34
我的收藏

您可通过此接口获取指定直播间中观众点击页头广告、页中广告、浮标广告、商品卡片或商品列表（即商品卡片菜单）的数据明细。

注意事项

请求频率：单用户请求频率限制为 1 次/秒。

请求说明

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

请求参数

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

Query

参数类型是否必选示例值描述
ActionString是GetAdvertisementDataDetailAPI接口名称。当前 API 的名称为 GetAdvertisementDataDetailAPI。
VersionString是2023-08-01接口版本。当前 API 的版本为 2023-08-01。
ActivityIdLong是1779168287直播间 ID。您可以通过 ListActivityAPI 接口查询 ID。
PageSizeInteger否10分页查询数量。取值范围为 [1,1000]，默认取值为 10。

PageNumber

Integer

否

1

分页查询页码，默认取值为 1。

  • 使用滚动查询时，不需要传入该参数。
  • 未使用滚动查询时，接口最多支持返回 10,000 条查询结果，即 PageNumber×PageSize≤10,000。
ChannelString否123根据渠道标识进行筛选。默认查询全部渠道数据。您可以通过 ListChannelAPI 接口查询渠道标识。

PageAdvertiseTypes

String

否

1,2

营销推广类型。支持以下取值，默认查询所有类型。

  • 1：页头广告
  • 2：页中广告
  • 3：浮标广告
  • 4：商品卡片
  • 5：商品列表（即商品卡片菜单）
    支持同时查询多种类型，类型之间通过英文逗号隔开。例如同时查询页头广告和页中广告，则取值为 1,2。

PageToken

String

否

init

滚动查询 ID。滚动查询方式适用于查询 10,000 条以上数据的场景。
使用滚动查询方式时，首次调用接口查询数据时将该参数值设置为 init，第二次调用接口查询时将该参数值设置为首次查询返回参数中 PageToken 的值，第三次调用接口查询时将该参数值设置为第二次查询返回参数中 PageToken 的值，依次类推。当查询到最后分页，没有更多数据时，返回 finish。

说明

  • 返回参数中 PageToken 值的失效时间为 3 分钟，即超过 3 分钟该 PageToken 值会失效，无法使用该值进行下一次查询。
  • 滚动查询过程中，请勿变更除 PageSize 参数外的查询条件，否则会导致接口查询失败。如需变更滚动查询条件，则需重新进行滚动查询。
SortFieldString否ClickTime排序维度。取值固定为 ClickTime，即观众点击广告或商品卡片等的时间。

SortMode

String

否

desc

排序模式。默认取值为 desc。

  • asc：升序
  • desc：降序

返回参数

参数类型示例值描述
PageSizeInteger10分页查询数量。

PageNumber

Integer

1

分页查询页码。

  • 未使用滚动查询时，返回实际分页查询页码。
  • 使用滚动查询时，返回 0。
TotalCountInteger1查询结果总数。
AdInfoDetailsArray of AdInfoDetails-营销推广详细信息列表。

PageToken

String

finish

滚动查询 ID。

  • 使用滚动查询时，返回下次查询需要传入的 PageToken 参数的值。当查询到最后分页，没有更多数据时，返回 finish。
  • 未使用滚动查询时，返回空。

AdInfoDetails

参数类型示例值描述
ClickTimeLong1705992283点击营销推广内容的时间。Unix 时间戳，单位为秒。

Content

String

https://p1-live.byteimg.com/tos-cn-i-gjr78lqtd0/ed73ec26febe31dbc7c0e1c51e252573.png~tplv-gjr78lqtd0-image.image

营销推广图的 URL。具体内容如下：

  • PageAdvertiseType 取值为 1 时，返回页头图的 URL。
  • PageAdvertiseType 取值为 2 时，返回页中广告图的 URL。
  • PageAdvertiseType 取值为 3 时，返回浮标广告图的 URL。
  • PageAdvertiseType 取值为 4 时，返回商品卡片跳转图的 URL。
  • PageAdvertiseType 取值为 5 时，返回空。
ExternalUserIdString1482148456观众在第三方平台的唯一标识。您可以根据该关联用户 ID 识别企业自身的用户身份，以便于按需实现用户洞察和进行数据分析。观众通过不同方式登录直播间时，关联用户 ID 取值不同，具体取值情况详见数据统计。

Link

String

www.example.com

营销推广内容的跳转链接。具体内容如下：

  • PageAdvertiseType 取值为 1 时，返回页头广告的跳转链接。
  • PageAdvertiseType 取值为 2 时，返回页中广告的跳转链接。
  • PageAdvertiseType 取值为 3 时，返回浮标广告的跳转链接。
  • PageAdvertiseType 取值为 4 时，返回商品卡片的跳转链接。
  • PageAdvertiseType 取值为 5 时，返回空。
NickNameString观众 A观众昵称。

PageAdvertiseType

Integer

4

营销推广类型。支持以下取值：

  • 1：页头广告
  • 2：页中广告
  • 3：浮标广告
  • 4：商品卡片
  • 5：商品列表（即商品卡片菜单）

Title

String

商品 1

营销推广内容的标题。具体内容如下：

  • PageAdvertiseType 取值为 1、2 和 3 时，返回空。
  • PageAdvertiseType 取值为 4 时，返回商品卡片的名称。
  • PageAdvertiseType 取值为 5 时，返回商品卡片菜单的名称。

UserId

Long

1451518515

观众在企业直播的唯一标识。

说明

如果观众未通过输入昵称或其他方式登录直播间，则返回 0。

UserTelString17525485846观众登录直播间的手机号。

请求示例

GET https://livesaas.volcengineapi.com/?Action=GetAdvertisementDataDetailAPI&Version=2023-08-01&ActivityId=1779168287&PageAdvertiseTypes=4

返回示例

{
    "ResponseMetadata": {
        "Action": "GetAdvertisementDataDetailAPI",
        "Region": "cn-north-1",
        "RequestId": "202306041104200100100232280022D31",
        "Service": "livesaas",
        "SystemTime": 1705992306,
        "Version": "2023-08-01"
    },
    "Result": {
        "PageSize": 10,
        "PageNumber": 1,
        "TotalCount": 1,
        "AdInfoDetails": [
            {
                "ClickTime": 1705992283,
                "Content": "https://p1-live.byteimg.com/tos-cn-i-gjr78lqtd0/ed73ec26febe31dbc7c0e1c51e252573.png~tplv-gjr78lqtd0-image.image",
                "ExternalUserId": "1482148456",
                "Link": "www.example.com",
                "NickName": "观众 A",
                "PageAdvertiseType": 4,
                "Title": "商品 1",
                "UserId": 1451518515,
                "UserTel": "17525485846"
            }
        ],
        "PageToken": ""
    }
}

错误码

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