ad · 广告
ts
import { AdDomain } from '@hfyidu/api/ad'广告领域负责广告位列表拉取与广告事件（曝光/点击等）上报，服务前缀 adPlay。
用例总览
| 用例 | 说明 | 请求方式 |
|---|---|---|
AdDomain.cases.list | 获取广告位列表 | GET adPlay/list |
AdDomain.cases.event | 广告事件上报 | POST adPlay/event |
此外 AdDomain 实例还提供一个便捷方法 onAdReport，对 event 用例做了一层上报类型校验。
list · 获取广告位列表
ts
const { data } = await AdDomain.cases.list.run({
provider_code: 'csj',
})
console.log(data) // AdListDto[]请求参数 AdListQueryParams
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
provider_code | string | 是 | 广告平台代码 |
响应 AdListDto[]
AdListDto
| 字段 | 类型 | 后台原始字段 | 说明 |
|---|---|---|---|
id | Identity（number | string） | id | 广告位分组 ID，必填 |
adLocation | AdLocationDto[] | ad_location | 该分组下的广告位置列表，默认 [] |
AdLocationDto
| 字段 | 类型 | 后台原始字段 | 说明 |
|---|---|---|---|
id | Identity | id | 广告位置 ID，必填 |
code | AdUnitType | code | 广告位置编码，默认 AdUnitType.OTHER |
playList | PlayListDto[] | play_list | 该位置下可播放的广告素材列表，默认 [] |
PlayListDto
| 字段 | 类型 | 后台原始字段 | 说明 |
|---|---|---|---|
id | Identity | id | 广告素材 ID，必填 |
adId | string | ad_id | 广告 ID，必填 |
adExt | string | ad_ext | 广告扩展参数，默认 '' |
adType | AdShowType | ad_type | 广告展示类型，默认 AdShowType.BANNER |
adProviderId | Identity | ad_provider_id | 广告平台侧 ID，必填 |
adLocationId | Identity | ad_location_id | 关联的广告位置 ID，必填 |
locationInfo | LocationInfoDto | — | 广告位置附加信息，默认新建一个 LocationInfoDto 实例 |
LocationInfoDto（不可变，@Freeze）
| 字段 | 类型 | 说明 |
|---|---|---|
code | AdUnitType | 广告位置编码，默认 AdUnitType.OTHER |
event · 广告事件上报
ts
await AdDomain.cases.event.run({
page: 'novel_read',
ad_provider_id: '1001',
ad_provider_code: 'csj',
ad_type: AdShowType.REWARDED_VIDEO,
ad_id: 'ad_xxx',
ad_ext: '',
ad_location_id: '2001',
event: AdEventType.SHOW,
})请求参数 AdEventBodyParams
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | string | 是 | 上报所在页面标识 |
ad_provider_id | string | 是 | 广告平台侧 ID |
ad_provider_code | string | 是 | 广告平台代码 |
ad_type | AdShowType | 是 | 广告展示类型 |
ad_id | string | 是 | 广告 ID |
ad_ext | string | 是 | 广告扩展参数 |
ad_location_id | string | 是 | 广告位置 ID |
event | AdEventType | 是 | 上报的事件类型 |
响应
无格式化 DTO，直接透传后台原始返回。
onAdReport · 广告上报便捷方法
AdDomain 实例方法，在调用 event 用例之前先校验 ad_type 是否属于允许上报的展示类型（BANNER / INTERSTITIAL / NATIVE / REWARDED_VIDEO / TEMPLATE），不属于则直接跳过、不发起请求：
ts
const ad = new AdDomain()
await ad.onAdReport(params) // 内部会做类型校验后再决定是否调用 event 用例枚举
AdShowType 广告展示类型
| 枚举成员 | value | code | 说明 |
|---|---|---|---|
BANNER | 1 | banner | 横幅 |
INTERSTITIAL | 2 | interstitial | 插屏 |
NATIVE | 3 | native | 原生 |
REWARDED_VIDEO | 4 | rewardedVideo | 激励 |
APP_START | 5 | appStart | 开屏广告 |
VIDEO | 6 | video | 视频广告 |
APP_LIST | 7 | appList | 应用榜单 |
APP_BOX | 8 | appBox | 互推盒子 |
APP_BOX_BANNER | 9 | appBoxBanner | 互推盒子横划榜单广告 |
TEMPLATE | 10 | template | 模板 |
AdEventType 广告事件类型
| 枚举成员 | value | code | 说明 |
|---|---|---|---|
PULL | 1 | pull | 拉取 |
SHOW | 2 | show | 展示 |
CLICK | 3 | click | 点击 |
ERROR | 4 | error | 异常 |
VIDEO_FINISH | 5 | videoFinish | 视频结束 |
AdUnitType 广告位编码
| 枚举成员 | value | code | 说明 |
|---|---|---|---|
OPEN | 0 | open | 开屏广告 |
RF | 1 | readFooter | 阅读器页脚 |
RC | 2 | readCenter | 阅读器文中(前) |
SF | 3 | signFooter | 签到页脚 |
SPF | 4 | signPopupFooter | 签到弹窗 |
SR | 5 | signReward | 签到双倍激励 |
TBF | 6 | turntableFooter | 抽奖底部广告 |
TBPF | 7 | turntablePopupFooter | 抽奖通用弹窗 |
TBR | 8 | turntableReward | 抽奖双倍激励 |
ATC | 9 | activityCenter | 福利通用原生 |
ATBR | 10 | activityBtnReward | 福利领取激励 |
VUR | 11 | videoUnlockReward | 短剧解锁激励 |
GN | 12 | generalNative | 通用原生广告 |
GR | 13 | generalReward | 通用激励广告 |
VF | 14 | videoFooter | 播放器页脚 |
RR | 15 | readReward | 阅读器激励 |
GI | 16 | generalInsert | 通用插屏广告 |
GTP | 17 | templatead | 通用模板广告(上图下文) |
GVTP | 18 | templatead | 通用视频模板广告 |
GBANNER | 19 | generalBanner | 通用横幅广告 |
EXIT | 20 | appExit | 应用退出弹窗 |
BCOVER | 21 | bookCover | 书架封面模仿广告 |
VCOVER | 22 | videoCover | 短剧封面模仿广告 |
RQ | 23 | readQuit | 阅读器退出弹窗 |
VQ | 24 | videoQuit | 播放器退出弹窗 |
GPN | 25 | generalPopupNative | 通用弹窗广告 |
RC2 | 26 | readCenter2 | 阅读器文中(后) |
OTHER | -1 | other | 其他（未按要求配置的广告类型） |