You need to enable JavaScript to run this app.
导航
获取直播间营销推广点击数据
最近更新时间: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

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

PageNumber

Integer

1

分页查询页码,默认取值为 1

  • 使用滚动查询时,不需要传入该参数。
  • 未使用滚动查询时,接口最多支持返回 10,000 条查询结果,即 PageNumber×PageSize≤10,000。
ChannelString123根据渠道标识进行筛选。默认查询全部渠道数据。您可以通过 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 参数外的查询条件,否则会导致接口查询失败。如需变更滚动查询条件,则需重新进行滚动查询。
SortFieldStringClickTime排序维度。取值固定为 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 取值为 123 时,返回空。
  • 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": ""
    }
}

错误码

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