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

场景介绍

贴片广告是一种在视频播放前、视频播放中或视频播放结束后插入的视频或图片广告。

接口说明

接口名	描述
loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void	请求单广告位广告，通过AdRequestParams、AdOptions进行广告请求参数设置，通过AdLoadListener监听广告请求回调。
AdComponent(ads: advertising.Advertisement[], displayOptions: advertising.AdDisplayOptions, interactionListener: advertising.AdInteractionListener, @BuilderParam adRenderer?: () => void): void	展示广告，通过AdDisplayOptions进行广告展示参数设置，通过AdInteractionListener监听广告状态回调。

开发步骤

1. 获取OAID。

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

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

   说明

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

2. 请求单广告位广告。

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

   在请求贴片广告时，需要在AdOptions中设置两个参数：totalDuration和placementAdCountDownDesc。
   请求广告关键参数如下所示：

   请求广告参数名	类型	必填	说明
   adType	number	是	请求广告类型，贴片广告类型为60。
   adId	string	是	广告位ID。 * 如果仅调测广告，可使用测试广告位ID：testy3cglm3pj0。 * 如果要接入正式广告，则需要申请正式的广告位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';
   5. import { router } from '@kit.ArkUI';
   7. @Entry
   8. @Component
   9. struct Index {
   10. private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
   11. // 获取到的OAID
   12. private oaid: string = '';
   14. aboutToAppear() {
   15. try {
   16. // 使用Promise回调方式获取OAID
   17. identifier.getOAID().then((data: string) => {
   18. this.oaid = data;
   19. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in getting adsIdentifierInfo by promise');
   20. }).catch((error: BusinessError) => {
   21. hilog.error(0x0000, 'testTag', '%{public}s',
   22. `Failed to get adsIdentifierInfo, code: {error.code}, message: {error.message}`);
   23. })
   24. } catch (error) {
   25. hilog.error(0x0000, 'testTag', '%{public}s', `Catch err, code: {error.code}, message: {error.message}`);
   26. }
   27. }
   29. build() {
   30. Row() {
   31. Button('加载广告', { type: ButtonType.Normal, stateEffect: true })
   32. .onClick(() => {
   33. // 调用加载广告方法
   34. requestAd(this.context, this.oaid);
   35. })
   36. .borderRadius(8)
   37. .backgroundColor(0x317aff)
   38. .width(90)
   39. .height(40)
   40. }
   41. .height('100%')
   42. }
   43. }
   45. /**
   46. * 加载广告
   47. *
   48. * @param context 上下文环境
   49. * @param oaid OAID信息
   50. */
   51. function requestAd(context: common.Context, oaid: string): void {
   52. const adRequestParam: advertising.AdRequestParams = {
   53. // 广告类型
   54. adType: 60,
   55. // 'testy3cglm3pj0'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
   56. adId: 'testy3cglm3pj0',
   57. // 在AdRequestParams中添加oaid参数
   58. oaid: oaid,
   59. // 用于区分普通请求和预加载请求，默认值false代表普通请求，true代表预加载请求
   60. isPreload: false
   61. };
   62. const adOptions: advertising.AdOptions = {
   63. // 在AdOptions中添加totalDuration参数，用于设置贴片广告展示时长（贴片广告必填）
   64. totalDuration: 30,
   65. // 在AdOptions中添加placementAdCountDownDesc参数，设置贴片广告倒计时文案（可选，填写了则展示文案，不填写则只展示倒计时）
   66. placementAdCountDownDesc: encodeURI('VIP免广告'),
   67. // 是否允许流量下载 0不允许 1允许，不设置以广告主设置为准
   68. allowMobileTraffic: 0,
   69. // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望
   70. tagForChildProtection: -1,
   71. // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望
   72. tagForUnderAgeOfPromise: -1,
   73. // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众
   74. adContentClassification: 'A'
   75. };
   76. // 广告请求回调监听
   77. const adLoaderListener: advertising.AdLoadListener = {
   78. // 广告请求失败回调
   79. onAdLoadFailure: (errorCode: number, errorMsg: string) => {
   80. hilog.error(0x0000, 'testTag', '%{public}s',
   81. `Failed to request single ad, errorCode is: {errorCode}, errorMsg is: {errorMsg}`);
   82. },
   83. // 广告请求成功回调
   84. onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
   85. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in requesting single ad!');
   86. // 保存请求到的广告内容用于展示
   87. const returnAds = ads;
   88. // 路由到广告展示页面
   89. routePage('pages/PlacementAdPage', returnAds);
   91. }
   92. };
   93. // 创建AdLoader广告对象
   94. const load: advertising.AdLoader = new advertising.AdLoader(context);
   95. // 调用广告请求接口
   96. hilog.info(0x0000, 'testTag', '%{public}s', 'Request single ad!');
   97. load.loadAd(adRequestParam, adOptions, adLoaderListener);
   98. }
   100. /**
   101. * 路由跳转
   102. *
   103. * @param pageUri 要路由到的页面
   104. */
   105. async function routePage(pageUri: string, ads: Array<advertising.Advertisement | null>) {
   106. let options: router.RouterOptions = {
   107. url: pageUri,
   108. params: {
   109. ads: ads
   110. }
   111. }
   112. try {
   113. hilog.info(0x0000, 'testTag', '%{public}s', `RoutePage: ${pageUri}`);
   114. router.pushUrl(options);
   115. } catch (error) {
   116. hilog.error(0x0000, 'testTag', '%{public}s',
   117. `Failed to routePage callback, code: {error.code}, msg: {error.message}`);
   118. }
   119. }

3. 展示广告。

   在您的页面中使用AdComponent组件展示贴片广告，由媒体判断流量场景下，可以自动播放则展示广告，反之则不展示。以前贴广告为例，前贴广告播放完成后进入正片播放。您需要在entry/src/main/resources/base/profile/main_pages.json文件中添加页面，如下图所示。

   

   您需要在media和rawfile目录下分别指定正片未播放时的预览图video_preview.PNG和对应的正片文件videoTest.mp4，如下图所示。

   
   示例代码如下所示：

   1. import { router, window } from '@kit.ArkUI';
   2. import { BusinessError } from '@kit.BasicServicesKit';
   3. import { advertising, AdComponent } from '@kit.AdsKit';
   4. import { hilog } from '@kit.PerformanceAnalysisKit';
   6. @Entry
   7. @Component
   8. export struct PlacementAdPage {
   9. // 是否竖屏
   10. private portrait: boolean = true;
   11. // 请求到的广告内容
   12. private ads: Array<advertising.Advertisement> = [];
   13. // 广告展示参数
   14. private adDisplayOptions: advertising.AdDisplayOptions = {
   15. // 是否静音，默认不静音
   16. mute: false
   17. }
   18. // 广告参数
   19. private adOptions: advertising.AdOptions = {
   20. // 设置贴片广告展示时长（贴片广告必填）
   21. totalDuration: 30,
   22. // 设置贴片广告倒计时文案，文案需要使用encodeURI编码（可选，填写了则展示文案，不填写则只展示倒计时）
   23. placementAdCountDownDesc: encodeURI('VIP免广告'),
   24. // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望
   25. tagForChildProtection: -1,
   26. // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望
   27. tagForUnderAgeOfPromise: -1,
   28. // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众
   29. adContentClassification: 'A'
   30. }
   31. // 已经播放的贴片广告数量
   32. private playedAdSize: number = 0;
   33. // 是否播放正片
   34. @State isPlayVideo: boolean = false;
   35. // 视频播放控制器
   36. private controller: VideoController = new VideoController();
   37. // 指定视频未播放时的预览图片路径
   38. private previewUris: Resource = $r('app.media.video_preview');
   39. // 指定视频播放源的路径，这里取本地视频资源
   40. private innerResource: Resource = $rawfile('videoTest.mp4');
   41. // 用于渲染右上角倒计时
   42. private countDownTxtPlaceholder: string = '%d | %s';
   43. @State countDownTxt: string = '';
   45. aboutToAppear() {
   46. const params: Record<string, Object> = router.getParams() as Record<string, Object>;
   47. if (params && params.ads as Array<advertising.Advertisement>) {
   48. this.ads = params.ads as Array<advertising.Advertisement>;
   49. this.adOptions = params.adOptions as advertising.AdOptions;
   50. this.initData();
   51. }
   52. }
   54. build() {
   55. Stack({ alignContent: Alignment.TopEnd }) {
   56. // AdComponent组件用于展示非全屏广告
   57. AdComponent({
   58. ads: this.ads, displayOptions: this.adDisplayOptions,
   59. interactionListener: {
   60. // 广告状态变化回调
   61. onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => {
   62. switch (status) {
   63. case 'onPortrait':
   64. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onPortrait');
   65. // 设置屏幕方向为竖屏或返回上一页
   66. this.setWindowPortrait();
   67. break;
   68. case 'onLandscape':
   69. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onLandscape');
   70. // 设置屏幕方向为横屏
   71. this.setWindowLandscape();
   72. break;
   73. case 'onMediaProgress':
   74. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onMediaProgress');
   75. break;
   76. case 'onMediaStart':
   77. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onMediaStart');
   78. break;
   79. case 'onMediaPause':
   80. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onMediaPause');
   81. break;
   82. case 'onMediaStop':
   83. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onMediaStop');
   84. break;
   85. case 'onMediaComplete':
   86. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onMediaComplete');
   87. // 所有广告都播放完毕后，开始播放正片
   88. this.playedAdSize++;
   89. if (this.playedAdSize === this.ads.length) {
   90. this.isPlayVideo = true;
   91. }
   92. break;
   93. case 'onMediaError':
   94. hilog.error(0x0000, 'testTag', '%{public}s', 'Status is onMediaError');
   95. break;
   96. case 'onMediaCountdown':
   97. try {
   98. hilog.info(0x0000, 'testTag', '%{public}s', 'Status is onMediaCountdown');
   99. const parseData: Record<string, number> = JSON.parse(JSON.stringify(data));
   100. this.updateCountDownTxt(parseData.countdownTime);
   101. } catch (e) {
   102. hilog.error(0x0000, 'testTag', '%{public}s',
   103. `Failed to parse data, code: {e.code}, msg: {e.message}`);
   104. }
   105. break;
   106. }
   107. }
   108. }
   109. })
   110. .visibility(!this.isPlayVideo ? Visibility.Visible : Visibility.None)
   111. .width('100%')
   112. .height('100%')
   114. Row() {
   115. if (this.countDownTxt) {
   116. Text(this.countDownTxt.split('').join('\u200B'))
   117. .fontSize(12)
   118. .textAlign(TextAlign.Center)
   119. .maxLines(1)
   120. .fontColor(Color.White)
   121. .lineHeight(12)
   122. .textOverflow({ overflow: TextOverflow.Ellipsis })
   123. .maxLines(1)
   124. .backgroundColor('#66000000')
   125. .border({ radius: 25 })
   126. .padding({
   127. left: 8,
   128. right: 8,
   129. top: 6,
   130. bottom: 6
   131. })
   132. .margin({ right: 16, top: 16 })
   133. .height(24)
   134. .constraintSize({ minWidth: 60, maxWidth: 100 })
   135. .onClick((event: ClickEvent) => {
   136. hilog.info(0x0000, 'testTag', '%{public}s', 'OnVipClicked, do something...');
   137. })
   138. }
   139. }
   140. .alignItems(VerticalAlign.Top)
   141. .justifyContent(FlexAlign.End)
   143. Video({
   144. src: this.innerResource,
   145. previewUri: this.previewUris,
   146. controller: this.controller
   147. })
   148. .visibility(this.isPlayVideo ? Visibility.Visible : Visibility.None)
   149. .autoPlay(this.isPlayVideo ? true : false)
   150. .controls(false)
   151. .width('100%')
   152. .height('100%')
   153. }.width('100%').height('100%')
   154. }
   156. /**
   157. * 设置竖屏或返回上一页
   158. */
   159. private setWindowPortrait() {
   160. hilog.info(0x0000, 'testTag', '%{public}s', `Set WindowPortrait, portrait: ${this.portrait}`);
   161. if (!this.portrait) {
   162. window.getLastWindow(getContext(this), (err: BusinessError, win) => {
   163. win.setPreferredOrientation(window.Orientation.PORTRAIT)
   164. });
   165. this.portrait = true;
   166. } else {
   167. router.back();
   168. }
   169. }
   171. /**
   172. * 设置横屏（正向）
   173. */
   174. private setWindowLandscape() {
   175. hilog.info(0x0000, 'testTag', '%{public}s', `Set WindowLandscape, portrait: ${this.portrait}`);
   176. if (this.portrait) {
   177. window.getLastWindow(getContext(this), (err: BusinessError, win) => {
   178. win.setPreferredOrientation(window.Orientation.LANDSCAPE)
   179. });
   180. this.portrait = false;
   181. }
   182. }
   184. private initData() {
   185. this.initCountDownText();
   186. }
   188. private initCountDownText() {
   189. const decodeText = this.decodeString(this.adOptions?.placementAdCountDownDesc as string);
   190. if (!this.isBlank(decodeText)) {
   191. this.countDownTxtPlaceholder = this.countDownTxtPlaceholder.replace('%s', decodeText);
   192. } else {
   193. this.countDownTxtPlaceholder = '%d';
   194. }
   195. }
   197. private updateCountDownTxt(leftTime: number) {
   198. hilog.info(0x0000, 'testTag', '%{public}s', `Show LeftTime: ${leftTime}`);
   199. this.countDownTxt = this.countDownTxtPlaceholder.replace('%d', leftTime + '');
   200. }
   202. private decodeString(str: string): string {
   203. if (!str) {
   204. return str;
   205. }
   206. let decodeUrl = str;
   207. try {
   208. decodeUrl = decodeURIComponent(str.replace(/\+/g, '%20'));
   209. } catch (e) {
   210. hilog.error(0x0000, 'testTag', '%{public}s', `Failed to decodeURIComponent, code:{e.code}, msg: {e.message}`);
   211. }
   212. return decodeUrl;
   213. }
   215. private isBlank(str: string): boolean {
   216. if (str === null || str === undefined) {
   217. return true;
   218. }
   219. if (typeof str === 'string') {
   220. return str.trim().length === 0;
   221. }
   222. return false;
   223. }
   224. }