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

场景介绍

原生广告是与应用内容融于一体的广告，通过"和谐"的内容呈现广告信息，在不破坏用户体验的前提下，为用户提供有价值的信息，展示形式包含图片和视频，支持您自由定制界面。

接口说明

接口名	描述
loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void	请求单广告位广告，通过AdRequestParams、AdOptions进行广告请求参数设置，通过AdLoadListener监听广告请求回调。
loadAdWithMultiSlots(adParams: AdRequestParams[], adOptions: AdOptions, listener: MultiSlotsAdLoadListener): void	请求多广告位广告，通过AdRequestParams[]、AdOptions进行广告请求参数设置，通过MultiSlotsAdLoadListener监听广告请求回调。
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，来监听广告的加载状态。

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

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

   示例代码如下所示：

   1. import { advertising, identifier } from '@kit.AdsKit';
   2. import { router } from '@kit.ArkUI';
   3. import { common } from '@kit.AbilityKit';
   4. import { hilog } from '@kit.PerformanceAnalysisKit';
   5. import { BusinessError } from '@kit.BasicServicesKit';
   7. @Entry
   8. @Component
   9. export struct LoadAd {
   10. private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
   11. private oaid: string = '';
   13. aboutToAppear() {
   14. try {
   15. // 使用Promise回调方式获取OAID
   16. identifier.getOAID().then((data: string) => {
   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',
   21. `Failed to get adsIdentifierInfo, error code: ${error.code}, message: ${error.message}`);
   22. })
   23. } catch (error) {
   24. hilog.error(0x0000, 'testTag', '%{public}s', `Catch err, code: ${error.code}, message: ${error.message}`);
   25. }
   26. }
   28. build() {
   29. Column() {
   30. Column() {
   31. // 跳转到原生广告展示页面
   32. Button("请求原生广告", { type: ButtonType.Normal, stateEffect: true }).onClick(() => {
   33. this.requestAd();
   34. })
   35. }.width('100%').height('80%').justifyContent(FlexAlign.Center)
   36. }
   37. .width('100%')
   38. .height('100%')
   39. }
   41. private requestAd(): void {
   42. // 广告展示参数
   43. const adDisplayOptions: advertising.AdDisplayOptions = {
   44. // 是否静音，默认不静音
   45. mute: false
   46. }
   47. // 原生广告配置
   48. const adOptions: advertising.AdOptions = {
   49. // 设置是否请求非个性化广告
   50. nonPersonalizedAd: 1,
   51. // 是否允许流量下载0：不允许，1：允许，不设置以广告主设置为准
   52. allowMobileTraffic: 0,
   53. // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望
   54. tagForChildProtection: -1,
   55. // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望
   56. tagForUnderAgeOfPromise: -1,
   57. // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众
   58. adContentClassification: 'A'
   59. }
   60. // 原生广告请求参数
   61. const nativeVideoAdReqParams: advertising.AdRequestParams = {
   62. // 'testu7m3hc4gvm'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
   63. adId: 'testu7m3hc4gvm',
   64. adType: 3,
   65. adCount: 1,
   66. // 原生广告自定义扩展参数。等所有广告素材下载完后再回调
   67. enableDirectReturnVideoAd: true,
   68. oaid: this.oaid
   69. }
   70. // 广告请求回调监听
   71. const adLoaderListener: advertising.AdLoadListener = {
   72. // 广告请求失败回调
   73. onAdLoadFailure: (errorCode: number, errorMsg: string) => {
   74. hilog.error(0x0000, 'testTag', '%{public}s',
   75. `Failed to request ad, message: ${errorMsg}, error code: ${errorCode}`);
   76. },
   77. // 广告请求成功回调
   78. onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
   79. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in requesting ad');
   80. // 调用原生广告展示页面
   81. routePage('pages/NativeAdPage', ads, adDisplayOptions);
   82. }
   83. };
   84. // 创建AdLoader广告对象
   85. const load: advertising.AdLoader = new advertising.AdLoader(this.context);
   86. // 调用广告请求接口
   87. load.loadAd(nativeVideoAdReqParams, adOptions, adLoaderListener);
   88. }
   89. }
   91. async function routePage(pageUri: string, ads: Array<advertising.Advertisement | null>,
   92. displayOptions: advertising.AdDisplayOptions) {
   93. let options: router.RouterOptions = {
   94. url: pageUri,
   95. params: {
   96. ads: ads,
   97. displayOptions: displayOptions
   98. }
   99. }
   100. try {
   101. router.pushUrl(options);
   102. } catch (error) {
   103. hilog.error(0x0000, 'testTag', '%{public}s',
   104. `Failed to routePage callback, code: ${error.code}, msg: ${error.message}`);
   105. }
   106. }

   请求多广告与请求单广告类似，需要创建一个AdLoader对象，通过AdLoader的loadAdWithMultiSlots方法请求广告，最后通过MultiSlotsAdLoadListener，来监听广告的加载状态。示例代码如下：

   1. import { advertising, identifier } from '@kit.AdsKit';
   2. import { router } from '@kit.ArkUI';
   3. import { common } from '@kit.AbilityKit';
   4. import { hilog } from '@kit.PerformanceAnalysisKit';
   5. import { BusinessError } from '@kit.BasicServicesKit';
   7. @Entry
   8. @Component
   9. export struct LoadAd {
   10. private ads: Array<advertising.Advertisement> = [];
   11. private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
   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. Column() {
   31. Column() {
   32. // 跳转到原生广告展示页面
   33. Button("请求原生广告", { type: ButtonType.Normal, stateEffect: true }).onClick(() => {
   34. this.requestAd();
   35. })
   36. }.width('100%').height('80%').justifyContent(FlexAlign.Center)
   37. }
   38. .width('100%')
   39. .height('100%')
   40. }
   42. private requestAd(): void {
   43. // 广告展示参数
   44. const adDisplayOptions: advertising.AdDisplayOptions = {
   45. // 是否静音，默认不静音
   46. mute: false
   47. }
   48. // 原生广告配置
   49. const adOptions: advertising.AdOptions = {
   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. };
   60. // 原生广告请求参数
   61. const nativeVideoAdReqParams: advertising.AdRequestParams[] = [{
   62. // 'testy63txaom86'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
   63. adId: 'testy63txaom86',
   64. adType: 3,
   65. adCount: 1,
   66. // 原生广告自定义扩展参数。等所有广告素材下载完后再回调
   67. enableDirectReturnVideoAd: true,
   68. oaid: this.oaid
   69. }, {
   70. // 'testu7m3hc4gvm'为测试专用的广告位ID，App正式发布时需要改为正式的广告位ID
   71. adId: 'testu7m3hc4gvm',
   72. adType: 3,
   73. adCount: 1,
   74. // 原生广告自定义扩展参数。等所有广告素材下载完后再回调
   75. enableDirectReturnVideoAd: true,
   76. oaid: this.oaid
   77. }]
   78. // 广告请求回调监听
   79. const adLoaderListener: advertising.MultiSlotsAdLoadListener = {
   80. // 广告请求失败回调
   81. onAdLoadFailure: (errorCode: number, errorMsg: string) => {
   82. hilog.error(0x0000, 'testTag', '%{public}s',
   83. `Failed to request ad errorCode is: ${errorCode}, errorMsg is: ${errorMsg}`);
   84. },
   85. // 广告请求成功回调
   86. onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => {
   87. hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in requesting ad!');
   88. ads.forEach((adsArray) => this.ads.push(...adsArray));
   89. // 调用原生广告展示页面
   90. routePage('pages/NativeAdPage', this.ads, adDisplayOptions);
   91. }
   92. };
   93. // 创建AdLoader广告对象
   94. const load: advertising.AdLoader = new advertising.AdLoader(this.context);
   95. // 调用广告请求接口
   96. load.loadAdWithMultiSlots(nativeVideoAdReqParams, adOptions, adLoaderListener);
   97. }
   98. }
   100. async function routePage(pageUri: string, ads: Array<advertising.Advertisement | null>,
   101. displayOptions: advertising.AdDisplayOptions) {
   102. let options: router.RouterOptions = {
   103. url: pageUri,
   104. params: {
   105. ads: ads,
   106. displayOptions: displayOptions
   107. }
   108. }
   109. try {
   110. router.pushUrl(options);
   111. } catch (error) {
   112. hilog.error(0x0000, 'testTag', '%{public}s',
   113. `Failed to routePage callback, code: ${error.code}, msg: ${error.message}`);
   114. }
   115. }

3. 展示广告

   在您的页面中使用AdComponent组件展示原生广告。您需要在entry/src/main/resources/base/profile/main_pages.json文件中添加pages/NativeAdPage页面，如下图所示。

   

   
   示例代码如下所示：

   1. import { advertising, AdComponent } from '@kit.AdsKit';
   2. import { Prompt, router } from '@kit.ArkUI';
   4. @Entry
   5. @Component
   6. export struct NativeAdPage {
   7. // 广告内容
   8. private ads: Array<advertising.Advertisement> = [];
   9. private adDisplayOptions: advertising.AdDisplayOptions = {
   10. // 是否静音，默认不静音
   11. mute: false
   12. }
   14. aboutToAppear() {
   15. const params: Record<string, Object> = router.getParams() as Record<string, Object>;
   16. if (params && params.ads as Array<advertising.Advertisement> &&
   17. params.displayOptions as advertising.AdDisplayOptions) {
   18. this.ads = params.ads as Array<advertising.Advertisement>;
   19. this.adDisplayOptions = params.displayOptions as advertising.AdDisplayOptions;
   20. }
   21. }
   23. build() {
   24. Column() {
   25. List({ space: 20, initialIndex: 0 }) {
   26. ForEach(this.ads, (ad: advertising.Advertisement) => {
   27. ListItem() {
   28. AdComponent({
   29. ads: [ad],
   30. displayOptions: this.adDisplayOptions,
   31. interactionListener: {
   32. onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => {
   33. switch (status) {
   34. case 'onAdOpen':
   35. Prompt.showToast({
   36. message: 'native ad open',
   37. duration: 1000
   38. });
   39. break;
   40. case 'onAdClick':
   41. Prompt.showToast({
   42. message: 'native ad click',
   43. duration: 1000
   44. });
   45. break;
   46. case 'onAdClose':
   47. Prompt.showToast({
   48. message: 'native ad close',
   49. duration: 1000
   50. });
   51. break;
   52. default:
   53. }
   54. }
   55. }
   56. })
   57. .width('100%')
   58. }
   59. })
   60. }
   61. .listDirection(Axis.Vertical)
   62. .scrollBar(BarState.Off)
   63. .friction(0.6)
   64. .divider({
   65. strokeWidth: 2,
   66. color: Color.White,
   67. startMargin: 20,
   68. endMargin: 20
   69. })
   70. .edgeEffect(EdgeEffect.Spring)
   71. .width('100%')
   72. .height('100%')
   73. }.width('100%').height('100%')
   74. }
   75. }

   说明

   在原生广告场景中通常不需要显式设置AdComponent组件的高度，AdComponent组件会自动调整高度以适应需要展示的内容