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

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

场景介绍

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

接口说明

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

开发步骤

获取OAID。

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

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

说明

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

请求单广告位广告。

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

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

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

请求广告参数名

类型

必填

说明

adType

number

是

请求广告类型，插屏广告类型为12。

adId

string

是

广告位ID。

如果仅调测广告，可使用测试广告位ID：testb4znbuh3n2。
如果要接入正式广告，则需要申请正式的广告位ID。可在应用发布前进入流量变现官网，点击“开始变现”，登录鲸鸿动能媒体服务平台进行申请，具体操作详情请参见展示位创建。

oaid

string

否

开放匿名设备标识符，用于精准推送广告。不填无法获取到个性化广告。

示例代码如下所示：

import { advertising, identifier } from '@kit.AdsKit';
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
private ads: Array<advertising.Advertisement> = [];
private context = getContext(this) as common.UIAbilityContext;
private oaid: string = '';
aboutToAppear() {
try {
// 使用Promise回调方式获取OAID
identifier.getOAID().then((data) => {
this.oaid = data;
hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in getting adsIdentifierInfo by promise');
}).catch((error: BusinessError) => {
hilog.error(0x0000, 'testTag', '%{public}s', `Failed to get adsIdentifierInfo, message: ${error.message}`);
})
} catch (error) {
hilog.error(0x0000, 'testTag', '%{public}s', `Catch err, code: ${error.code}, message: ${error.message}`);
}
}
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Row() {
Button('requestAd').onClick(() => {
let load: advertising.AdLoader = new advertising.AdLoader(this.context);
this.requestAd(load);
}).width('45%')
}
}
}
private requestAd(adLoader: advertising.AdLoader): void {
const adRequestParam: advertising.AdRequestParams = {
// 广告类型：插屏广告
adType: 12,
// 'testb4znbuh3n2'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
adId: 'testb4znbuh3n2',
// 开放匿名设备标识符
oaid: this.oaid
};
const adOption: advertising.AdOptions = {
// 设置是否请求非个性化广告
nonPersonalizedAd: 0,
// 是否允许流量下载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'
};
const adLoaderListener: advertising.AdLoadListener = {
onAdLoadFailure: (errorCode: number, errorMsg: string) => {
hilog.error(0x0000, 'testTag', '%{public}s',
`Failed to request ad, message: ${errorMsg}, error code: ${errorCode}`);
},
onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in requesting ad!');
this.ads = [];
this.ads.push(...ads);
},
};
adLoader.loadAd(adRequestParam, adOption, adLoaderListener);
}
}

事件订阅。

开发者需要在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. }
展示广告。

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. }