华为HarmonyOS打造开放、合规的广告生态 - 插屏广告

场景介绍

插屏广告是一种在应用开启、暂停或退出时以全屏或半屏的形式弹出的广告形式，展示时机巧妙避开用户对应用的正常体验，尺寸大，曝光效果好。

接口说明

接口名	描述
loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void	请求单广告位广告，通过AdRequestParams、AdOptions进行广告请求参数设置，通过AdLoadListener监听广告请求回调。
showAd(ad: Advertisement, options: AdDisplayOptions, context?: common.UIAbilityContext): void	展示广告，通过AdDisplayOptions进行广告展示参数设置。

开发步骤

1. 获取OAID。

   如果想要为用户更精准的推送广告，可以在请求参数AdRequestParams中添加oaid属性。

   如何获取OAID参见获取OAID信息。

   说明

   使用以下示例中提供的测试广告位必须先获取OAID信息。

2. 请求单广告位广告。

   需要先创建一个AdLoader对象，通过AdLoader的loadAd方法请求广告，最后通过AdLoadListener来监听广告的加载状态。

   请求广告关键参数如下所示：

   请求广告参数名	类型	必填	说明
   adType	number	是	请求广告类型，插屏广告类型为12。
   adId	string	是	广告位ID。 * 如果仅调测广告，可使用测试广告位ID：testb4znbuh3n2。 * 如果要接入正式广告，则需要申请正式的广告位ID。可在应用发布前进入流量变现官网，点击"开始变现"，登录鲸鸿动能媒体服务平台进行申请，具体操作详情请参见展示位创建。
   oaid	string	否	开放匿名设备标识符，用于精准推送广告。不填无法获取到个性化广告。

   示例代码如下所示：

   1. import { advertising, identifier } from '@kit.AdsKit';
   2. import { common } from '@kit.AbilityKit';
   3. import { hilog } from '@kit.PerformanceAnalysisKit';
   4. import { BusinessError } from '@kit.BasicServicesKit';
   6. @Entry
   7. @Component
   8. struct Index {
   9. private ads: Array<advertising.Advertisement> = [];
   10. private context = getContext(this) as common.UIAbilityContext;
   11. private oaid: string = '';
   13. aboutToAppear() {
   14. try {
   15. // 使用Promise回调方式获取OAID
   16. identifier.getOAID().then((data) => {
   17. this.oaid = data;
   18. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in getting adsIdentifierInfo by promise');
   19. }).catch((error: BusinessError) => {
   20. hilog.error(0x0000, 'testTag', '%{public}s', `Failed to get adsIdentifierInfo, message: ${error.message}`);
   21. })
   22. } catch (error) {
   23. hilog.error(0x0000, 'testTag', '%{public}s', `Catch err, code: {error.code}, message: {error.message}`);
   24. }
   25. }
   27. build() {
   28. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
   29. Row() {
   30. Button('requestAd').onClick(() => {
   31. let load: advertising.AdLoader = new advertising.AdLoader(this.context);
   32. this.requestAd(load);
   33. }).width('45%')
   34. }
   35. }
   36. }
   38. private requestAd(adLoader: advertising.AdLoader): void {
   39. const adRequestParam: advertising.AdRequestParams = {
   40. // 广告类型：插屏广告
   41. adType: 12,
   42. // 'testb4znbuh3n2'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
   43. adId: 'testb4znbuh3n2',
   44. // 开放匿名设备标识符
   45. oaid: this.oaid
   46. };
   47. const adOption: advertising.AdOptions = {
   48. // 设置是否请求非个性化广告
   49. nonPersonalizedAd: 0,
   50. // 是否允许流量下载0：不允许，1：允许，不设置以广告主设置为准
   51. allowMobileTraffic: 0,
   52. // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望
   53. tagForChildProtection: -1,
   54. // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望
   55. tagForUnderAgeOfPromise: -1,
   56. // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众
   57. adContentClassification: 'A'
   58. };
   59. const adLoaderListener: advertising.AdLoadListener = {
   60. onAdLoadFailure: (errorCode: number, errorMsg: string) => {
   61. hilog.error(0x0000, 'testTag', '%{public}s',
   62. `Failed to request ad, message: {errorMsg}, error code: {errorCode}`);
   63. },
   64. onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
   65. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in requesting ad!');
   66. this.ads = [];
   67. this.ads.push(...ads);
   68. },
   69. };
   70. adLoader.loadAd(adRequestParam, adOption, adLoaderListener);
   71. }
   72. }

3. 事件订阅。

   开发者需要在App中订阅com.huawei.hms.pps.action.PPS_INTERSTITIAL_STATUS_CHANGED事件来监听插屏广告页面变化并接收插屏信息。示例代码中的订阅方法registerPPSReceiver()需要在每次展示广告前调用 。

   在订阅到公共事件后，可以从CommonEventData的parameters参数中使用"interstitial_ad_status"作为key值获取插屏广告页面变化状态。

   示例代码如下所示：

   1. import { commonEventManager, BusinessError } from '@kit.BasicServicesKit';
   2. import { hilog } from '@kit.PerformanceAnalysisKit';
   4. const KEY_INTERSTITIAL_STATUS = 'interstitial_ad_status';
   6. export class InterstitialAdStatusHandler {
   7. // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
   8. private subscriber: commonEventManager.CommonEventSubscriber | null = null;
   10. // 订阅方法，需要在每次展示广告前调用
   11. public registerPPSReceiver(): void {
   12. if (this.subscriber) {
   13. this.unRegisterPPSReceiver();
   14. }
   15. // 订阅者信息
   16. const subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
   17. events: ['com.huawei.hms.pps.action.PPS_INTERSTITIAL_STATUS_CHANGED'],
   18. publisherBundleName: 'com.huawei.hms.adsservice'
   19. };
   20. // 创建订阅者回调
   21. commonEventManager.createSubscriber(subscribeInfo,
   22. (err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) => {
   23. if (err) {
   24. hilog.error(0x0000, 'testTag', '%{public}s', `CreateSubscriber error, {err.code}, message: {err.message}}`);
   25. return;
   26. }
   27. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in creating subscriber');
   28. this.subscriber = commonEventSubscriber;
   29. // 订阅公共事件回调
   30. if (!this.subscriber) {
   31. hilog.warn(0x0000, 'testTag', '%{public}s', 'Need to create subscriber');
   32. return;
   33. }
   34. commonEventManager.subscribe(this.subscriber,
   35. (err: BusinessError, commonEventData: commonEventManager.CommonEventData) => {
   36. if (err) {
   37. hilog.error(0x0000, 'testTag', '%{public}s', `Subscribe error, {err.code}, message: {err.message}`);
   38. } else {
   39. // 订阅者成功接收到公共事件
   40. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded subscribing data');
   41. // 获取插屏广告页面变化状态
   42. const status: string = commonEventData?.parameters?.[KEY_INTERSTITIAL_STATUS];
   43. switch (status) {
   44. case AdStatus.AD_OPEN:
   45. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdOpen');
   46. break;
   47. case AdStatus.AD_CLICKED:
   48. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdClick');
   49. break;
   50. case AdStatus.AD_CLOSED:
   51. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdClose');
   52. this.unRegisterPPSReceiver();
   53. break;
   54. case AdStatus.AD_VIDEO_START:
   55. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdVideoStart');
   56. break;
   57. case AdStatus.AD_COMPLETED:
   58. hilog.info(0x0000, 'testTag', '%{public}s', 'onAdCompleted');
   59. break;
   60. default:
   61. break;
   62. }
   63. }
   64. });
   65. });
   66. }
   68. // 取消订阅
   69. public unRegisterPPSReceiver(): void {
   70. commonEventManager.unsubscribe(this.subscriber, (err: BusinessError) => {
   71. if (err) {
   72. hilog.error(0x0000, 'testTag', '%{public}s', `Unsubscribe error, {err.code}, message: {err.message}}`);
   73. } else {
   74. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in unsubscribing');
   75. this.subscriber = null;
   76. }
   77. });
   78. }
   79. }
   81. enum AdStatus {
   82. AD_OPEN = 'onAdOpen',
   83. AD_CLICKED = 'onAdClick',
   84. AD_CLOSED = 'onAdClose',
   85. AD_VIDEO_START = 'onVideoPlayBegin',
   86. AD_COMPLETED = 'onVideoPlayEnd'
   87. }

4. 展示广告。

   ads为步骤2请求到的广告信息，调用showAd方法来展示广告。示例代码如下所示：

   1. import { advertising } from '@kit.AdsKit';
   2. import { common } from '@kit.AbilityKit';
   4. @Entry
   5. @Component
   6. struct Index {
   7. private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
   8. // 步骤2中请求到的广告内容
   9. private ads: Array<advertising.Advertisement> = [];
   10. private displayOptions: advertising.AdDisplayOptions = {
   11. // 插屏广告视频播放是否静音
   12. mute: true
   13. };
   15. build() {
   16. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
   17. Row() {
   18. Button('showAd').onClick(() => {
   19. this.showAd();
   20. }).width('45%')
   21. }
   22. }
   23. }
   25. private showAd() {
   26. // 请在此处自行增加步骤3中的，注册插屏广告状态监听器
   27. // ...
   29. // 此处ads[0]表示请求到的第一个广告，用户根据实际情况选择
   30. advertising.showAd(this.ads[0], this.displayOptions, this.context);
   31. }
   32. }