更新记录

1.3.2（2026-09-09） 下载此版本

删除无用文件，减少代码体积

1.3.1（2026-09-08） 下载此版本

更新开屏功能，优化加载过程

1.3.0（2026-08-13） 下载此版本

增加负反馈功能

平台兼容性

uni-app(4.85)

# WL-Track 广告组件使用文档

一个简单易用的 uniapp 广告组件库，按广告类型提供独立组件标签，自动拉取数据、渲染与埋点。

组件列表

🚀 快速对接

一、初始化埋点 SDK（必需）

在 App.vue 中初始化平台对应的埋点 SDK，并挂载到全局：

<!-- App.vue -->
<script setup lang="ts">

// #ifdef MP-WEIXIN
import { wlydTrack } from '@wlydfe/track-js'

// 初始化微信小程序埋点
wlydTrack.init({
  isProd: false,                         // 是否生产环境
  debug: true,                           // 是否开启调试
  autoTrack: true,                       // 是否自动埋点
  trackerType: 'quick_tracking_wx',      // 埋点类型
  config: {
    project: 'your_project_id',          // qt应用key
    serverUrl: 'https://your-server-url.com',  // 收数服务器地址
  },
})
// #endif

// #ifdef APP-PLUS
import * as QtAnalytics from '@/uni_modules/QT-Analytics'

const platform = uni.getSystemInfoSync().platform

// 根据不同平台初始化
if (platform === 'android') {
  QtAnalytics.init()
} else if (platform === 'ios') {
  QtAnalytics.setCustomDomain('https://your-server-url.com')
  QtAnalytics.initWithAppkey('your_app_key')
  QtAnalytics.setLogEnabled(true)
} else if (platform === 'harmony') {
  QtAnalytics.init()
}
// #endif

</script>

二、初始化广告 SDK（必需）

在完成埋点 SDK 初始化后，初始化广告 SDK：

<!-- App.vue（续） -->
<script setup lang="ts">
import { initGlobalAdSDK } from '@/uni_modules/wl-track/utils/ad-sdk'

onLaunch(() => {
  // 初始化广告 SDK
  initGlobalAdSDK({
    app_key: 'your_app_key',             // 替换为实际的应用Key（必填）
    // webviewPath: '/subs/common/web-view/index?url=${jumpAdUrl}',
    // #ifdef MP-WEIXIN
    wlydTrack: wlydTrack,            // 微信小程序埋点实例（必填）
    // #endif
    // #ifdef APP-PLUS
    QtAnalytics: QtAnalytics,        // APP 埋点实例（必填）
    // #endif
  })
})
</script>

⚠️ 重要提示：

• 必须先初始化埋点 SDK，再初始化广告 SDK
• 微信小程序需要安装 @wlydfe/track-js 依赖
• APP 需要集成 QT-Analytics 插件
• 微信小程序必须传入 wlydTrack 参数，否则会报错
• APP 必须传入 QtAnalytics 参数，否则会报错

webview 承接页（可选）

广告点击后默认打开插件内置承接页。业务方使用自己的 webview 页时，在初始化传入 webviewPath：

// 业务自定义模板（含占位符）
initGlobalAdSDK({
  appKey: 'your_app_key',
  webviewPath: '/subs/common/web-view/index?url=${jumpAdUrl}',
})

// 不传 webviewPath：使用插件默认页，自动拼接 ?url=
initGlobalAdSDK({ appKey: 'your_app_key' })

业务模板中的 ${jumpAdUrl} / ${url} 会替换为编码后的落地链接；未配置时使用插件默认承接页并拼接 ?url=。

微信小程序：承接页建议注册为分包（见 pages_init.json 的 subPackages），避免主包 uni_modules 页面被「代码依赖分析」忽略。跳转路径仍为 /uni_modules/wl-track/pages/landing/index。

三、使用组件

方式一：Easycom 自动导入（推荐，已配置）

项目已在 pages.config.ts 中配置 easycom，所有页面可直接使用各广告组件，无需 import：

// pages.config.ts
easycom: {
  custom: {
    '^wl-(splash|banner|carousel)-ad$':
      '@/uni_modules/wl-track/components/wl-$1-ad.vue',
  },
}

直接在页面中使用（按广告位类型选择对应标签）：

<template>
  <view class="page">
    <!-- 开屏广告 -->
    <wl-splash-ad ad-slot-key="549" />

    <!-- Banner 广告 -->
    <wl-banner-ad ad-slot-key="550" />

    <!-- 轮播广告 -->
    <wl-carousel-ad ad-slot-key="551" />
  </view>
</template>

💡 注意：每种标签对应一种广告类型，请根据广告位类型选择正确组件；类型不匹配时会报错提示。

组件会自动：

• ✅ 获取广告数据
• ✅ 渲染对应类型的广告
• ✅ 处理加载/错误状态
• ✅ 上报埋点数据（请求、响应、曝光、点击、播放等）

💡 埋点会根据平台自动使用对应的 SDK（微信小程序用 wlydTrack，APP 用 QtAnalytics）

📱 使用示例

基础用法

开屏广告

<template>
  <wl-splash-ad
    ad-slot-key="549"
    :countdown-seconds="5"
  />
</template>

🎯 常用配置

事件监听

<template>
  <wl-splash-ad
    ad-slot-key="549"
    @ad-layer-close="onAdLayerClose"
    @close="onClose"
    @click="onClick"
    @error="onError"
  />
</template>

<script setup lang="ts">
const onAdLayerClose = (type: 'skip' | 'click' | 'auto') => console.log('广告层即将关闭', type)
const onClose = (type: 'skip' | 'click' | 'auto') => console.log('广告关闭', type)
const onClick = (adData) => console.log('广告点击', adData)
const onError = (error) => console.error('加载失败', error)
</script>

🔧 组件参数

自定义跳转时机拦截 (before-jump)

所有广告组件均已支持：wl-splash-ad / wl-banner-ad / wl-carousel-ad / wl-feed-ad / wl-interstitial-ad。

默认点击素材区会立即新开落地页。若业务需在跳转前执行自己的逻辑（如弹窗确认、登录校验），可配置 :before-jump 属性：

const handleBeforeJump = (context, proceed) => {
  // context.adData 为当前广告数据
  // context.index：Banner / 开屏 / 信息流 / 插屏为 0，轮播为当前帧索引
  doYourLogic().then(() => {
    proceed(); // 准备好后再跳转
  });
  // 不调用 proceed() 则不会跳转
}

• 未配置 beforeJump：行为与原来一致，点击后立即跳转
• 已配置 beforeJump：SDK 不会自动跳转，需业务在合适时机调用 proceed()
• @click 事件仍会在点击时触发（用于通知），与跳转时机无关
• 开屏 / 插屏额外行为：进入 beforeJump 时会暂停倒计时；业务调用 proceed() 后会从完整秒数重新倒计时，再执行跳转。不调用 proceed() 则倒计时保持暂停（仍可点「跳过/关闭」）

开屏广告（wl-splash-ad）overlay 样式

默认布局：左上角一行 [广告] [跳过 5s]（两个独立元素）。如需改位置，分别给两个 style 传入 top、left、right、bottom 即可，组件会自动清理冲突边（无需手写 auto）。

<!-- 默认 -->
<wl-splash-ad ad-slot-key="549" />

<!-- 自定义：跳过放右上，广告标放左下 -->
<wl-splash-ad
  ad-slot-key="549"
  :skip-button-style="{ top: '80px', right: '40rpx' }"
  :ad-tag-style="{ bottom: '40rpx', left: '40rpx' }"
/>

📡 组件事件

各广告组件均支持以下事件，可用于监听广告生命周期并在业务侧做相应处理：

开屏特有：

预取模式（所有广告组件均支持）：

开屏关闭事件顺序：

轮播特有：

<wl-splash-ad
  ad-slot-key="549"
  @ad-layer-close="onAdLayerClose"
  @close="onClose"
  @click="onClick"
  @load="onLoad"
  @error="onError"
  @request="onRequest"
  @response="onResponse"
/>

组件内部已自动上报埋点（请求、曝光、点击、关闭等），业务侧监听事件主要用于 UI 联动或自定义逻辑，无需重复上报。

负反馈（屏蔽广告）功能

SDK 原生支持广告“负反馈”功能，允许用户点击广告角标主动屏蔽当前不喜欢的广告。

开启与配置

当 API 接口下发的广告数据满足以下字段时，wl-banner-ad / wl-carousel-ad 会开启负反馈：

neFeedback 每一项（NeFeedbackItemDTO）：

两种 UI 模式：

位置可分别配置：

<wl-banner-ad
  ad-tag-position="bl"
  :ad-tag-style="{ bottom: '24rpx', left: '24rpx' }"
  close-position="tr"
  :close-style="{ top: '24rpx', right: '24rpx' }"
/>

• 选项来源： 优先使用接口 neFeedback；若开启但列表为空，回退默认五项
• 关闭回调： 用户提交负反馈后，SDK 会先通过内部 v-if 销毁广告展示，再触发 @close（无额外参数）。业务侧监听 @close 后清空 adData / 关掉外层 v-if 即可。选择结果仅用于内部埋点，不抛给业务。

事件监听

<template>
  <wl-banner-ad
    v-if="adData"
    :ad-slot-key="slotId"
    :ad-data="adData"
    :auto-fetch="false"
    @close="handleClose"
  />
</template>

<script setup>
const adData = ref(null)

const handleClose = () => {
  // 负反馈提交后也会走到这里，销毁组件即可
  adData.value = null
}
</script>

注意： 负反馈选择结果不会抛给业务侧；底层仍会做 QT 埋点上报（ad_feedback_show / ad_feedback_submit / ad_feedback_cancel）。公共参数与其它广告埋点一致：position_key、request_id、ads；提交时额外带 feedback_reason、feedback_text。

支持哪些广告类型？

每种广告类型对应独立组件标签，请在页面中显式选用：

• 开屏广告 → wl-splash-ad
• Banner 广告 → wl-banner-ad
• 轮播广告 → wl-carousel-ad
• 信息流广告 → wl-feed-ad
• 插屏广告 → wl-interstitial-ad

先请求后加载（预取模式）

推荐分工

非开屏推荐：sdk.loadAd

import { getGlobalAdSDK } from '@/uni_modules/wl-track/utils/ad-sdk'

const result = await getGlobalAdSDK()?.loadAd({
  adSlotKey: 'banner_home_top'
})

if (result.hasAd) {
  swiperItems.push({
    type: 'ad',
    adData: result.data,
  })
}

<wl-banner-ad
  v-if="item.type === 'ad'"
  :ad-slot-key="item.adSlotKey"
  :ad-data="item.adData"
  :auto-fetch="false"
/>

要点：loadAd 返回 hasAd=true 后再挂载组件（v-if），通过 :ad-data 传入数据即可，无需 ref 调用。

LoadAdResult 结构：

interface LoadAdResult {
  hasAd: boolean
  data: AdData | null
  reason?: 'no_fill' | 'not_renderable' | 'network_error' | 'sdk_not_ready' | 'invalid_params' | 'unknown'
  error?: unknown
  requestId?: string
}

开屏：常规模式（autoFetch）

开屏组件在 :auto-fetch="true"（默认）时，内部不再调用 getFalco，而是与 sdk.prefetch 共用同一套 prefetchAd 管道：

• 本地 JSON 缓存 → validateAd 校验复用
• 无缓存或无效 → requestAd（自动传 cache_status + request_scene：cold_direct / refresh_next）
• 拉取成功 → 写入预取缓存并后台下载 OSS 素材
• 展示层 → 500ms 竞态 / 弱网跳过 / 本地素材 0ms 展示
• 展示成功 → 清除当前缓存并后台预取下一条

<wl-splash-ad
  :ad-slot-key="SLOT_KEY"
  :auto-fetch="true"
  :auto-show="true"
/>

若 App 启动非常早、希望在组件挂载前就完成预取，仍推荐在 onLaunch 额外调用 sdk.prefetch，与常规 autoFetch 共用同一 adSlotKey + name 缓存，不会重复请求（命中本地缓存后仅复用）。

开屏：预请求模式（sdk.prefetch + loadFromPrefetch）

import {
  getGlobalAdSDK,
  hasPrefetchedAd,
  clearPrefetchedAd,
} from '@/uni_modules/wl-track/utils/ad-sdk'

const SLOT_KEY = 'your_ad_slot_key'

// 1. 预取（可传 name 区分同一广告位的多份缓存）
await getGlobalAdSDK()?.prefetch({ adSlotKey: SLOT_KEY, name: 'home_banner' })

// 2. 需要展示时再加载
const loaded = adRef.value?.loadFromPrefetch?.()
if (!loaded) {
  // 无缓存，可降级为实时请求
  await adRef.value?.fetchAd?.()
}

<template>
  <wl-splash-ad
    ref="splashRef"
    :ad-slot-key="SLOT_KEY"
    name="splash_launch"
    :auto-fetch="false"
    :auto-show="true"
    @prefetch-consumed="onPrefetchConsumed"
  />
</template>

工具函数：hasPrefetchedAd(adSlotKey, name?)、clearPrefetchedAd(adSlotKey, name?)

注意：同一 adSlotKey 多条预取必须传不同 name，否则缓存会互相覆盖。预取请用 await 串行或独立 name，不要用 void forEach 并发无 name 预取。

非开屏广告请使用上文 sdk.loadAd + v-if + :ad-data 传参，不要在文档流程中使用 ref 灌数据。

🔧 其他功能

设置用户 ID

import { getGlobalAdSDK } from '@/uni_modules/wl-track/utils/ad-sdk'

const sdk = getGlobalAdSDK()
if (sdk?.global) {
  sdk.global.setGlobalProperty({
    user: {
      userId: 'user_123',
    },
  })
}

错误码