HarmonyOS Banner广告集成指南

HarmonyOS Banner广告集成指南

1. 概述

Banner广告是一种常见的广告形式，通常显示在应用的顶部或底部，是一种非常有效的广告展示方式。HarmonyOS提供了AutoAdComponent组件来简化Banner广告的集成过程。本教程将指导您如何在HarmonyOS应用中集成和展示Banner广告。

2. 前提条件

• 已安装DevEco Studio
• 已创建HarmonyOS项目
• 已在鲸鸿动能媒体服务平台注册并创建广告位

3. 添加依赖

在项目的oh-package.json5文件中添加AdsKit依赖：

"dependencies": {"@kit.AdsKit": "*"
}

4. 导入必要的模块

import { advertising, AutoAdComponent, identifier } from '@kit.AdsKit';
import { common, abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

5. 定义广告类型和状态常量

// 定义广告类型常量
enum AdType {BANNER_AD = 0,NATIVE_AD = 3,REWARD_AD = 7,INTERSTITIAL_AD = 8,SPLASH_AD = 9,INSTREAM_AD = 10
}// 定义广告状态常量
enum AdStatus {AD_CLICKED = 'adClicked',AD_CLOSED = 'adClosed',AD_FAILED = 'adFailed',AD_LOADED = 'adLoaded',AD_LOADING = 'adLoading',AD_OPENED = 'adOpened',AD_REWARDED = 'adRewarded',AD_COMPLETED = 'adCompleted'
}

6. 配置广告参数

// 广告展示参数
private adDisplayOptions: advertising.AdDisplayOptions = {// 广告轮播的时间间隔，单位ms，取值范围[30000, 120000]refreshTime: 30000
};// 广告配置
private adOptions: advertising.AdOptions = {// 是否允许流量下载  0不允许 1允许，不设置以广告主设置为准allowMobileTraffic: 0,// 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望tagForChildProtection: -1,// 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望tagForUnderAgeOfPromise: -1,// 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众adContentClassification: 'A'
};// Banner广告请求参数
@State bannerAdReqParams: advertising.AdRequestParams = {adId: 'YOUR_AD_ID_HERE', // 替换为您的广告位IDadType: AdType.BANNER_AD,adCount: 1,adWidth: 360,adHeight: 57
};

7. 请求广告跟踪权限

在展示广告前，需要请求用户授权广告跟踪权限：

private requestOAIDTrackingConsentPermissions(context: common.Context): void {const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();try {atManager.requestPermissionsFromUser(context, ['ohos.permission.APP_TRACKING_CONSENT']).then((data) => {if (data.authResults[0] == 0) {hilog.info(0x0000, 'BannerAdDemo', '%{public}s', '成功请求权限');identifier.getOAID().then((data: string) => {this.bannerAdReqParams.oaid = data;hilog.info(0x0000, 'BannerAdDemo', '%{public}s', `成功获取广告标识符信息`);}).catch((error: BusinessError) => {hilog.error(0x0000, 'BannerAdDemo', '%{public}s', `获取广告标识符信息失败, message: ${error.message}`);})} else {hilog.info(0x0000, 'BannerAdDemo', '%{public}s', '用户拒绝授权');}}).catch((err: BusinessError) => {hilog.error(0x0000, 'BannerAdDemo', '%{public}s', `请求权限失败, error: ${err.code} ${err.message}`);})} catch (err) {hilog.error(0x0000, 'BannerAdDemo', '%{public}s', `捕获错误, code:${err.code}, message: ${err.message}`);}
}

8. 使用AutoAdComponent展示Banner广告

@Builder
buildBannerAd() {Row() {AutoAdComponent({adParam: this.bannerAdReqParams,adOptions: this.adOptions,displayOptions: this.adDisplayOptions,interactionListener: {onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => {hilog.info(0x0000, 'BannerAdDemo', '%{public}s', `广告状态变化: ${status}`);switch (status) {case AdStatus.AD_OPENED:hilog.info(0x0000, 'BannerAdDemo', '%{public}s', '广告被打开');break;case AdStatus.AD_CLICKED:hilog.info(0x0000, 'BannerAdDemo', '%{public}s', '广告被点击');break;case AdStatus.AD_CLOSED:hilog.info(0x0000, 'BannerAdDemo', '%{public}s', '广告被关闭');break;case AdStatus.AD_FAILED:hilog.info(0x0000, 'BannerAdDemo', '%{public}s', `广告加载失败: ${data}`);break;case AdStatus.AD_LOADED:hilog.info(0x0000, 'BannerAdDemo', '%{public}s', '广告加载成功');break;}}}}).width('100%').height(this.bannerAdReqParams.adHeight)}.width('100%').backgroundColor('#FFFFFF').borderRadius(8).margin({ top: 16, bottom: 8 })
}

9. 在页面中使用Banner广告

在页面的build方法中添加Banner广告：

build() {Column() {// 其他UI组件// Banner广告区域this.buildBannerAd()// 其他UI组件}.width('100%').height('100%')
}

10. 常见问题

广告显示白屏

可能原因：展示的广告样式与UI展示页面不匹配。Banner广告必须使用AutoAdComponent组件展示。

广告不显示

可能原因：

• 广告位ID错误
• 网络问题
• 未正确请求广告跟踪权限
• 广告请求参数配置错误

广告尺寸不正确

确保设置了正确的adWidth和adHeight参数，并且组件的宽高与这些参数一致。

11. 总结

正确配置和使用AutoAdComponent组件可以帮助您轻松实现Banner广告的集成。