更新记录

1.2.8（2026-07-15） 下载此版本

新增 sdk.loadAd 统一加载 API，非开屏广告推荐 loadAd + :ad-data 传参

1.2.6（2026-07-07） 下载此版本

开屏广告新增 adLayerClose 事件，支持在广告层真正关闭前处理业务逻辑

1.2.5（2026-07-03） 下载此版本

优化开屏

平台兼容性

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>

🔧 组件参数

开屏广告（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 联动或自定义逻辑，无需重复上报。

支持哪些广告类型？

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

• 开屏广告 → 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
}

开屏：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',
    },
  })
}

错误码