鸿蒙Ads Kit（广告服务）：激励广告开发(二)

激励广告是一种全屏幕的视频广告用户可以选择点击观看以换取相应奖励如游戏复活、获取道具、积分等。一、场景介绍激励广告是一种全屏幕的视频广告用户可以选择点击观看以换取相应奖励。场景游戏通关、复活获取道具、积分继续机会人物技能升级二、版本支持设备类型支持情况Phone支持Tablet支持PC/2in1支持需智慧营销服务或广告服务版本≥8.4.80.300PC/2in1设备版本查看路径设置 → 应用和元服务 → 更多应用三、核心接口接口描述loadAd(adParam, adOptions, listener)请求单广告位广告通过AdRequestParams、AdOptions进行广告请求参数设置通过AdLoadListener监听广告请求回调showAd(ad, options, context)展示广告通过AdDisplayOptions进行广告展示参数设置。说明为了保证广告能正确展示该接口必须和请求广告接口配套使用四、开发步骤4.1 导入相关模块import { abilityAccessCtrl, common, PermissionRequestResult } from kit.AbilityKit; import { advertising, identifier } from kit.AdsKit; import { hilog } from kit.PerformanceAnalysisKit; import { BusinessError, commonEventManager } from kit.BasicServicesKit;4.2 获取OAID若需提升广告推送精准度可以在请求参数AdRequestParams中添加oaid属性。注意使用以下示例中提供的测试广告位时必须先获取OAID信息。async function requestOAID(context: Context): Promisestring | undefined { // 向用户请求授权广告跨应用关联访问权限 let isPermissionGranted: boolean false; try { const atManager: abilityAccessCtrl.AtManager abilityAccessCtrl.createAtManager(); const result: PermissionRequestResult await atManager.requestPermissionsFromUser(context, [ohos.permission.APP_TRACKING_CONSENT]); isPermissionGranted result.authResults[0] abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED; } catch (err) { hilog.error(0x0000, testTag, Failed to request permission. Code is ${err.code}, message is ${err.message}); } if (isPermissionGranted) { hilog.info(0x0000, testTag, Succeeded in requesting permission); try { const oaid await identifier.getOAID(); hilog.info(0x0000, testTag, Succeeded in getting OAID); return oaid; } catch (err) { hilog.error(0x0000, testTag, Failed to get OAID. Code is ${err.code}, message is ${err.message}); } } else { hilog.error(0x0000, testTag, Failed to request permission. User rejected); } return undefined; }4.3 请求广告请求广告关键参数参数名类型必填说明adTypenumber是激励广告类型为7adIdstring是广告位ID测试用j14rx3xtac正式需申请oaidstring否开放匿名设备标识符不填无法获取个性化广告private async loadAd(): Promisevoid { // 广告请求回调监听 const adLoadListener: advertising.AdLoadListener { onAdLoadFailure: (errorCode: number, errorMsg: string) { hilog.error(0x0000, testTag, Failed to load ad. Code is ${errorCode}, message is ${errorMsg}); }, onAdLoadSuccess: (ads: Arrayadvertising.Advertisement) { hilog.info(0x0000, testTag, Succeeded in loading ad); // 展示广告 this.showAd(ads); } }; // 广告请求参数 const adRequestParams: advertising.AdRequestParams { adId: j14rx3xtac, // 测试广告位ID adType: 7, // 激励广告类型 oaid: await requestOAID(this.context) }; // 广告配置参数 const adOptions: advertising.AdOptions {}; // 创建AdLoader广告对象 const adLoader: advertising.AdLoader new advertising.AdLoader(this.context); try { adLoader.loadAd(adRequestParams, adOptions, adLoadListener); } catch (e) { hilog.error(0x0000, testTag, Failed to load ad. Code is ${e.code}, message is ${e.message}); } }4.4 事件订阅需要在应用中订阅com.huawei.hms.pps.action.PPS_REWARD_STATUS_CHANGED事件来监听激励广告页面变化并接收奖励信息。页面变化状态状态说明onAdOpen打开广告onAdClick点击广告onAdClose关闭广告onAdReward广告获得奖励onVideoPlayBegin广告视频开始播放onVideoPlayEnd广告视频播放结束奖励信息获取rewardType奖励物品的名称rewardAmount奖励物品的数量const KEY_REWARD_DATA reward_ad_data; const KEY_REWARD_STATUS reward_ad_status; export class RewardAdStatusHandler { private subscriber: commonEventManager.CommonEventSubscriber | null null; public registerPPSReceiver(): void { if (this.subscriber) { this.unRegisterPPSReceiver(); } const subscribeInfo: commonEventManager.CommonEventSubscribeInfo { events: [com.huawei.hms.pps.action.PPS_REWARD_STATUS_CHANGED], publisherBundleName: com.huawei.hms.adsservice // 防止接收伪造事件 }; commonEventManager.createSubscriber(subscribeInfo, (err, commonEventSubscriber) { if (err) { hilog.error(0x0000, testTag, Failed to create subscriber. Code is ${err.code}); return; } this.subscriber commonEventSubscriber; commonEventManager.subscribe(this.subscriber, (err, commonEventSubscriber) { if (err) { hilog.error(0x0000, testTag, Failed to subscribe. Code is ${err.code}); } else { const status commonEventSubscriber?.parameters?.[KEY_REWARD_STATUS]; switch (status) { case onAdOpen: hilog.info(0x0000, testTag, Status is onAdOpen); break; case onAdClick: hilog.info(0x0000, testTag, Status is onAdClick); break; case onAdClose: hilog.info(0x0000, testTag, Status is onAdClose); this.unRegisterPPSReceiver(); break; case onAdReward: const rewardData commonEventSubscriber?.parameters?.[KEY_REWARD_DATA]; const rewardType rewardData?.rewardType; const rewardAmount rewardData?.rewardAmount; hilog.info(0x0000, testTag, Status is onAdReward. Type is ${rewardType}, Amount is ${rewardAmount}); break; case onVideoPlayBegin: hilog.info(0x0000, testTag, Status is onVideoPlayBegin); break; case onVideoPlayEnd: hilog.info(0x0000, testTag, Status is onVideoPlayEnd); break; default: break; } } }); }); } public unRegisterPPSReceiver(): void { commonEventManager.unsubscribe(this.subscriber, (err) { if (!err) { this.subscriber null; } }); } }4.5 展示广告private showAd(ads: Arrayadvertising.Advertisement): void { try { // 注册激励广告状态监听器每次展示广告前注册 new RewardAdStatusHandler().registerPPSReceiver(); const adDisplayOptions: advertising.AdDisplayOptions { mute: true, // 是否静音 customData: CUSTOM_DATA, // 自定义数据可选 userId: 1234567 // 用户ID可选 }; advertising.showAd(ads[0], adDisplayOptions, this.context); } catch (e) { hilog.error(0x0000, testTag, Failed to show ad. Code is ${e.code}, message is ${e.message}); } }五、测试广告位广告位类型测试广告位ID展示形式比例推广类型激励j14rx3xtac图片16:9应用下载激励j2mh81xmqs视频9:16网页推广注意测试广告位仅可用于调测激励广告功能不可用于广告变现。应用正式发布前需替换为正式的激励广告位ID。六、整体流程获取OAID提升广告精准度 ↓ 请求广告loadAd ↓ 广告加载成功 ↓ 注册事件监听registerPPSReceiver ↓ 展示广告showAd ↓ 用户观看广告 ↓ 事件回调onAdReward/onAdClose等 ↓ 发放奖励要点说明广告类型adType 7激励广告测试广告位j14rx3xtac图片、j2mh81xmqs视频权限要求需申请ohos.permission.APP_TRACKING_CONSENT权限获取OAID事件订阅订阅com.huawei.hms.pps.action.PPS_REWARD_STATUS_CHANGED展示前注册每次展示广告前需注册事件监听器