|
@@ -0,0 +1,367 @@
|
|
|
|
|
+# 快应用广告接入指南
|
|
|
|
|
+
|
|
|
|
|
+## 概述
|
|
|
|
|
+
|
|
|
|
|
+快应用支持多种类型的广告,包括 Banner广告、插屏广告、原生广告和激励视频广告。本文档将详细介绍如何在快应用中接入这些广告。
|
|
|
|
|
+
|
|
|
|
|
+## 前置条件
|
|
|
|
|
+
|
|
|
|
|
+### 1. 配置权限
|
|
|
|
|
+
|
|
|
|
|
+在 `manifest.json` 中添加广告服务权限:
|
|
|
|
|
+
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "features": [
|
|
|
|
|
+ {
|
|
|
|
|
+ "name": "service.ad"
|
|
|
|
|
+ }
|
|
|
|
|
+ ]
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 2. 获取广告位ID
|
|
|
|
|
+
|
|
|
|
|
+在广告平台(如华为、小米、OPPO等)申请广告位ID,包括:
|
|
|
|
|
+- Banner广告位ID
|
|
|
|
|
+- 插屏广告位ID
|
|
|
|
|
+- 原生广告位ID
|
|
|
|
|
+- 激励视频广告位ID
|
|
|
|
|
+
|
|
|
|
|
+## 广告类型详解
|
|
|
|
|
+
|
|
|
|
|
+### 1. Banner广告
|
|
|
|
|
+
|
|
|
|
|
+Banner广告是固定在页面底部的横幅广告。
|
|
|
|
|
+
|
|
|
|
|
+#### 基本用法
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+import ad from '@service.ad'
|
|
|
|
|
+
|
|
|
|
|
+// 创建Banner广告
|
|
|
|
|
+const bannerAd = ad.createBannerAd({
|
|
|
|
|
+ posId: 'your_banner_pos_id',
|
|
|
|
|
+ style: {
|
|
|
|
|
+ width: 750,
|
|
|
|
|
+ height: 100
|
|
|
|
|
+ }
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 监听事件
|
|
|
|
|
+bannerAd.onLoad(() => {
|
|
|
|
|
+ console.log('Banner广告加载完成')
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+bannerAd.onError((err) => {
|
|
|
|
|
+ console.error('Banner广告加载失败:', err)
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+bannerAd.onClose(() => {
|
|
|
|
|
+ console.log('Banner广告被关闭')
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 显示广告
|
|
|
|
|
+bannerAd.show()
|
|
|
|
|
+
|
|
|
|
|
+// 隐藏广告
|
|
|
|
|
+bannerAd.hide()
|
|
|
|
|
+
|
|
|
|
|
+// 销毁广告
|
|
|
|
|
+bannerAd.destroy()
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 在模板中使用
|
|
|
|
|
+
|
|
|
|
|
+```html
|
|
|
|
|
+<template>
|
|
|
|
|
+ <div class="banner-container">
|
|
|
|
|
+ <ad-banner
|
|
|
|
|
+ pos-id="your_banner_pos_id"
|
|
|
|
|
+ style="width: 750px; height: 100px;"
|
|
|
|
|
+ onload="onBannerLoad"
|
|
|
|
|
+ onerror="onBannerError"
|
|
|
|
|
+ onclose="onBannerClose">
|
|
|
|
|
+ </ad-banner>
|
|
|
|
|
+ </div>
|
|
|
|
|
+</template>
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 2. 插屏广告
|
|
|
|
|
+
|
|
|
|
|
+插屏广告是覆盖整个屏幕的广告,通常在页面切换时显示。
|
|
|
|
|
+
|
|
|
|
|
+#### 基本用法
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+import ad from '@service.ad'
|
|
|
|
|
+
|
|
|
|
|
+// 创建插屏广告
|
|
|
|
|
+const interstitialAd = ad.createInterstitialAd({
|
|
|
|
|
+ posId: 'your_interstitial_pos_id'
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 监听事件
|
|
|
|
|
+interstitialAd.onLoad(() => {
|
|
|
|
|
+ console.log('插屏广告加载完成')
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+interstitialAd.onError((err) => {
|
|
|
|
|
+ console.error('插屏广告加载失败:', err)
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+interstitialAd.onClose(() => {
|
|
|
|
|
+ console.log('插屏广告被关闭')
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 显示广告
|
|
|
|
|
+interstitialAd.show()
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 3. 原生广告
|
|
|
|
|
+
|
|
|
|
|
+原生广告可以自定义样式,更好地融入应用界面。
|
|
|
|
|
+
|
|
|
|
|
+#### 基本用法
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+import ad from '@service.ad'
|
|
|
|
|
+
|
|
|
|
|
+// 创建原生广告
|
|
|
|
|
+const nativeAd = ad.createNativeAd({
|
|
|
|
|
+ posId: 'your_native_pos_id'
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 监听事件
|
|
|
|
|
+nativeAd.onLoad((res) => {
|
|
|
|
|
+ console.log('原生广告加载完成:', res)
|
|
|
|
|
+ // res 包含广告数据,如标题、描述、图片等
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+nativeAd.onError((err) => {
|
|
|
|
|
+ console.error('原生广告加载失败:', err)
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+nativeAd.onClick(() => {
|
|
|
|
|
+ console.log('原生广告被点击')
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 显示广告
|
|
|
|
|
+nativeAd.show()
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 在模板中使用
|
|
|
|
|
+
|
|
|
|
|
+```html
|
|
|
|
|
+<template>
|
|
|
|
|
+ <div class="native-container">
|
|
|
|
|
+ <ad-native
|
|
|
|
|
+ pos-id="your_native_pos_id"
|
|
|
|
|
+ onload="onNativeLoad"
|
|
|
|
|
+ onerror="onNativeError"
|
|
|
|
|
+ onclick="onNativeClick">
|
|
|
|
|
+ </ad-native>
|
|
|
|
|
+ </div>
|
|
|
|
|
+</template>
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 4. 激励视频广告
|
|
|
|
|
+
|
|
|
|
|
+激励视频广告要求用户观看完整视频来获得奖励。
|
|
|
|
|
+
|
|
|
|
|
+#### 基本用法
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+import ad from '@service.ad'
|
|
|
|
|
+
|
|
|
|
|
+// 创建激励视频广告
|
|
|
|
|
+const rewardedVideoAd = ad.createRewardedVideoAd({
|
|
|
|
|
+ posId: 'your_rewarded_pos_id'
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 监听事件
|
|
|
|
|
+rewardedVideoAd.onLoad(() => {
|
|
|
|
|
+ console.log('激励视频广告加载完成')
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+rewardedVideoAd.onError((err) => {
|
|
|
|
|
+ console.error('激励视频广告加载失败:', err)
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+rewardedVideoAd.onClose((res) => {
|
|
|
|
|
+ if (res && res.isEnded) {
|
|
|
|
|
+ // 正常播放结束,可以下发游戏奖励
|
|
|
|
|
+ console.log('激励视频播放完成,可以发放奖励')
|
|
|
|
|
+ this.giveReward()
|
|
|
|
|
+ } else {
|
|
|
|
|
+ // 播放中途退出,不下发游戏奖励
|
|
|
|
|
+ console.log('激励视频播放中途退出')
|
|
|
|
|
+ }
|
|
|
|
|
+})
|
|
|
|
|
+
|
|
|
|
|
+// 显示广告
|
|
|
|
|
+rewardedVideoAd.show()
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## 最佳实践
|
|
|
|
|
+
|
|
|
|
|
+### 1. 广告管理器
|
|
|
|
|
+
|
|
|
|
|
+使用统一的广告管理器来管理所有广告:
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+// src/helper/ad-manager.js
|
|
|
|
|
+import ad from '@service.ad'
|
|
|
|
|
+
|
|
|
|
|
+class AdManager {
|
|
|
|
|
+ constructor() {
|
|
|
|
|
+ this.bannerAd = null
|
|
|
|
|
+ this.interstitialAd = null
|
|
|
|
|
+ this.nativeAd = null
|
|
|
|
|
+ this.rewardedVideoAd = null
|
|
|
|
|
+ }
|
|
|
|
|
+
|
|
|
|
|
+ // 初始化各种广告
|
|
|
|
|
+ initBannerAd() { /* ... */ }
|
|
|
|
|
+ initInterstitialAd() { /* ... */ }
|
|
|
|
|
+ initNativeAd() { /* ... */ }
|
|
|
|
|
+ initRewardedVideoAd() { /* ... */ }
|
|
|
|
|
+
|
|
|
|
|
+ // 显示各种广告
|
|
|
|
|
+ showBannerAd() { /* ... */ }
|
|
|
|
|
+ showInterstitialAd() { /* ... */ }
|
|
|
|
|
+ showNativeAd() { /* ... */ }
|
|
|
|
|
+ showRewardedVideoAd() { /* ... */ }
|
|
|
|
|
+
|
|
|
|
|
+ // 清理资源
|
|
|
|
|
+ destroyAllAds() { /* ... */ }
|
|
|
|
|
+}
|
|
|
|
|
+
|
|
|
|
|
+export default new AdManager()
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 2. 错误处理
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+// 统一的错误处理
|
|
|
|
|
+function handleAdError(error, adType) {
|
|
|
|
|
+ console.error(`${adType}广告错误:`, error)
|
|
|
|
|
+
|
|
|
|
|
+ // 根据错误类型进行不同处理
|
|
|
|
|
+ switch (error.code) {
|
|
|
|
|
+ case 'NO_AD':
|
|
|
|
|
+ console.log('暂无广告可展示')
|
|
|
|
|
+ break
|
|
|
|
|
+ case 'NETWORK_ERROR':
|
|
|
|
|
+ console.log('网络错误,稍后重试')
|
|
|
|
|
+ break
|
|
|
|
|
+ default:
|
|
|
|
|
+ console.log('未知错误')
|
|
|
|
|
+ }
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 3. 广告展示策略
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+// 智能广告展示策略
|
|
|
|
|
+class AdStrategy {
|
|
|
|
|
+ // 控制广告展示频率
|
|
|
|
|
+ static canShowAd(adType) {
|
|
|
|
|
+ const lastShowTime = this.getLastShowTime(adType)
|
|
|
|
|
+ const minInterval = this.getMinInterval(adType)
|
|
|
|
|
+
|
|
|
|
|
+ return Date.now() - lastShowTime > minInterval
|
|
|
|
|
+ }
|
|
|
|
|
+
|
|
|
|
|
+ // 根据用户行为决定是否展示广告
|
|
|
|
|
+ static shouldShowAd(userBehavior) {
|
|
|
|
|
+ // 根据用户停留时间、操作频率等决定
|
|
|
|
|
+ return userBehavior.stayTime > 30000 // 停留超过30秒
|
|
|
|
|
+ }
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 4. 性能优化
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+// 预加载广告
|
|
|
|
|
+function preloadAds() {
|
|
|
|
|
+ // 在应用启动时预加载广告
|
|
|
|
|
+ adManager.initBannerAd()
|
|
|
|
|
+ adManager.initInterstitialAd()
|
|
|
|
|
+ adManager.initNativeAd()
|
|
|
|
|
+ adManager.initRewardedVideoAd()
|
|
|
|
|
+}
|
|
|
|
|
+
|
|
|
|
|
+// 延迟加载
|
|
|
|
|
+function lazyLoadAds() {
|
|
|
|
|
+ // 在用户进入页面后再加载广告
|
|
|
|
|
+ setTimeout(() => {
|
|
|
|
|
+ adManager.initInterstitialAd()
|
|
|
|
|
+ }, 2000)
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## 常见问题
|
|
|
|
|
+
|
|
|
|
|
+### 1. 广告不显示
|
|
|
|
|
+
|
|
|
|
|
+- 检查广告位ID是否正确
|
|
|
|
|
+- 确认网络连接正常
|
|
|
|
|
+- 查看控制台错误信息
|
|
|
|
|
+- 确认广告平台配置正确
|
|
|
|
|
+
|
|
|
|
|
+### 2. 广告加载失败
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+// 重试机制
|
|
|
|
|
+function retryLoadAd(adInstance, maxRetries = 3) {
|
|
|
|
|
+ let retryCount = 0
|
|
|
|
|
+
|
|
|
|
|
+ function loadAd() {
|
|
|
|
|
+ adInstance.load().catch(err => {
|
|
|
|
|
+ if (retryCount < maxRetries) {
|
|
|
|
|
+ retryCount++
|
|
|
|
|
+ setTimeout(loadAd, 1000 * retryCount) // 递增延迟
|
|
|
|
|
+ }
|
|
|
|
|
+ })
|
|
|
|
|
+ }
|
|
|
|
|
+
|
|
|
|
|
+ loadAd()
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### 3. 激励视频奖励发放
|
|
|
|
|
+
|
|
|
|
|
+```javascript
|
|
|
|
|
+// 确保奖励只发放一次
|
|
|
|
|
+let rewardGiven = false
|
|
|
|
|
+
|
|
|
|
|
+rewardedVideoAd.onClose((res) => {
|
|
|
|
|
+ if (res && res.isEnded && !rewardGiven) {
|
|
|
|
|
+ rewardGiven = true
|
|
|
|
|
+ this.giveReward()
|
|
|
|
|
+ }
|
|
|
|
|
+})
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## 测试建议
|
|
|
|
|
+
|
|
|
|
|
+1. **真机测试**:广告功能需要在真机上测试,模拟器可能无法正常显示
|
|
|
|
|
+2. **网络测试**:测试不同网络环境下的广告加载情况
|
|
|
|
|
+3. **用户场景测试**:模拟真实用户使用场景,测试广告展示时机
|
|
|
|
|
+4. **性能测试**:监控广告对应用性能的影响
|
|
|
|
|
+
|
|
|
|
|
+## 注意事项
|
|
|
|
|
+
|
|
|
|
|
+1. **用户体验**:合理控制广告展示频率,避免影响用户体验
|
|
|
|
|
+2. **合规性**:遵守各平台的广告政策和使用规范
|
|
|
|
|
+3. **隐私保护**:注意用户隐私保护,合理使用用户数据
|
|
|
|
|
+4. **资源管理**:及时销毁广告实例,避免内存泄漏
|
|
|
|
|
+
|
|
|
|
|
+## 相关资源
|
|
|
|
|
+
|
|
|
|
|
+- [快应用官方文档](https://doc.quickapp.cn/)
|
|
|
|
|
+- [华为快应用广告文档](https://developer.huawei.com/consumer/cn/doc/development/quickApp-References/ad-service)
|
|
|
|
|
+- [小米快应用广告文档](https://doc.quickapp.cn/features/service/ad.html)
|