@ohos.advertising (广告服务框架)

本模块提供广告操作能力，包括请求广告、展示广告。

说明：
本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { advertising } from '@kit.AdsKit';

advertising.showAd

showAd(ad: Advertisement, options: AdDisplayOptions, context?: common.UIAbilityContext): void

展示全屏广告。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

import { common } from '@kit.AbilityKit';
import { advertising } from '@kit.AdsKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
  // 请求到的广告内容
  private ad?: advertising.Advertisement;
  // 广告展示参数
  private adDisplayOptions: advertising.AdDisplayOptions = {
    // 是否静音，默认不静音
    mute: false
  }

  build() {
    Column() {
      Button('showAd')
        .onClick(() => {
          try {
            // 调用全屏广告展示接口
            advertising.showAd(this.ad, this.adDisplayOptions, this.context);
          } catch (err) {
            hilog.error(0x0000, 'testTag', `Fail to show ad. Code is ${err.code}, message is ${err.message}`);
          }
        });
    }
    .width('100%')
    .height('100%')
  }
}

advertising.getAdRequestBody¹²⁺

getAdRequestBody(adParams: AdRequestParams[], adOptions: AdOptions): Promise<string>

获取广告请求响应体，使用Promise异步回调（该接口仅对部分系统预置应用开放）。

系统能力： SystemCapability.Advertising.Ads

参数：

返回值：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

import { advertising } from '@kit.AdsKit';
import { Prompt } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

function getAdRequestBody(): void {
  const adRequestParamsArray: advertising.AdRequestParams[] = [];
  const adRequestParams: advertising.AdRequestParams = {
    adId: 'testu7m3hc4gvm',
    adType: 3,
    adCount: 2,
    adWidth: 100,
    adHeight: 100
  };
  adRequestParamsArray.push(adRequestParams);
  const adOptions: advertising.AdOptions = {
    // 设置是否只请求非个性化广告 0：请求个性化广告与非个性化广告 1：只请求非个性化广告。不填以业务逻辑为准
    nonPersonalizedAd: 0,
    // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望
    tagForChildProtection: -1,
    // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望
    tagForUnderAgeOfPromise: -1,
    // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众
    adContentClassification: 'A'
  };
  advertising.getAdRequestBody(adRequestParamsArray, adOptions).then((data) => {
    hilog.info(0x0000, 'testTag', `Succeeded in getting ad request body. Data is ${JSON.stringify(data)}`);
    Prompt.showToast({
      message: data,
      duration: 1000
    });
  }).catch((error: BusinessError) => {
    hilog.error(0x0000, 'testTag', `Fail to get ad request body. Code is ${error.code}, message is ${error.message}`);
    Prompt.showToast({
      message: error.code.toString() + ',' + error.message,
      duration: 1000
    });
  })
}

advertising.parseAdResponse¹²⁺

parseAdResponse(adResponse: string, listener: MultiSlotsAdLoadListener, context: common.UIAbilityContext): void

解析并处理广告响应体（该接口仅对部分系统预置应用开放）。

系统能力： SystemCapability.Advertising.Ads

参数：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

其中context的获取方式参见UIAbilityContext的获取方式。

import { common } from '@kit.AbilityKit';
import { advertising } from '@kit.AdsKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

function parseAdResponse(adResponse: string, context: common.UIAbilityContext): void {
  // 广告解析处理回调监听
  const multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = {
    // 广告解析处理失败回调
    onAdLoadFailure: (errorCode: number, errorMsg: string) => {
      hilog.error(0x0000, 'testTag', `Fail to load multiSlots ad. Code is ${errorCode}, message is ${errorMsg}`);
    },
    // 广告解析处理成功回调
    onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => {
      hilog.info(0x0000, 'testTag', 'Succeed in loading multiSlots ad');
      // 保存解析处理完成的广告内容为数组用于展示
      const returnAds: Array<advertising.Advertisement> = [];
      ads.forEach((adsArray) => returnAds.push(...adsArray));
    }
  };
  // 调用响应体解析接口
  hilog.info(0x0000, 'testTag', 'Start to parse ad response');
  advertising.parseAdResponse(adResponse, multiSlotsAdLoaderListener, context);
}

advertising.registerWebAdInterface¹²⁺

registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext): void

注入广告JavaScript对象到Web组件中（该接口仅对部分系统预置应用开放）。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

import { common } from '@kit.AbilityKit';
import { advertising } from '@kit.AdsKit';
import { webview } from '@kit.ArkWeb';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  private webController: webview.WebviewController = new webview.WebviewController();
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Column() {
      Button('registerWebAdInterface')
        .onClick(() => {
          try {
            advertising.registerWebAdInterface(this.webController, this.context);
          } catch (err) {
            hilog.error(0x0000, 'testTag', `Fail to register web ad interface. Code is ${err.code}, message is ${err.message}`);
          }
        })

      Web({
        src: 'www.example.com',
        controller: this.webController
      })
        .width("100%")
        .height("100%")
    }
  }
}

advertising.registerWebAdInterface¹⁶⁺

registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext, needRefresh: boolean): void

注入广告JavaScript对象到Web组件中（该接口仅对部分系统预置应用开放）。

原子化服务API： 从API version 16开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

import { common } from '@kit.AbilityKit';
import { advertising } from '@kit.AdsKit';
import { webview } from '@kit.ArkWeb';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  private webController: webview.WebviewController = new webview.WebviewController();
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Column() {
      Button('registerWebAdInterface')
        .onClick(() => {
          try {
            advertising.registerWebAdInterface(this.webController, this.context, true);
          } catch (err) {
            hilog.error(0x0000, 'testTag', `Fail to register web ad interface. Code is ${err.code}, message is ${err.message}`);
          }
        })

      Web({
        src: 'www.example.com',
        controller: this.webController
      })
        .width("100%")
        .height("100%")
    }
  }
}

advertising.deleteWebAdInterface¹⁶⁺

deleteWebAdInterface(controller: web_webview.WebviewController, needRefresh: boolean): void

删除通过registerWebAdInterface注入的广告JavaScript对象（该接口仅对部分系统预置应用开放）。

原子化服务API： 从API version 16开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

import { advertising } from '@kit.AdsKit';
import { webview } from '@kit.ArkWeb';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  private webController: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Button('deleteWebAdInterface')
        .onClick(() => {
          try {
            advertising.deleteWebAdInterface(this.webController, true);
          } catch (err) {
            hilog.error(0x0000, 'testTag', `Fail to delete web ad interface. Code is ${err.code}, message is ${err.message}`);
          }
        })

      Web({
        src: 'www.example.com',
        controller: this.webController,
      })
        .width('100%')
        .height('100%')
    }
  }
}

AdLoader

提供加载广告的功能。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

constructor

constructor(context: common.Context)

构造函数。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

示例：

其中context的获取方式参见各类Context的获取方式。

import { advertising } from '@kit.AdsKit';
import { common } from '@kit.AbilityKit';

function createConstructor(context: common.Context): void {
  const adLoader: advertising.AdLoader = new advertising.AdLoader(context);
}

loadAd

loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void

请求单广告位广告。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

其中context的获取方式参见各类Context的获取方式。

import { common } from '@kit.AbilityKit';
import { advertising } from '@kit.AdsKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

function loadAd(context: common.Context): void {
  const adRequestParams: advertising.AdRequestParams = {
    // 广告类型
    adType: 3,
    // 测试广告位ID
    adId: 'testy63txaom86'
  };
  const adOptions: advertising.AdOptions = {
    // 可选自定义参数，设置是否允许使用流量下载广告素材 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', `Fail to load ad. Code is ${errorCode}, message is ${errorMsg}`);
    },
    // 广告请求成功回调
    onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
      hilog.info(0x0000, 'testTag', 'Succeed in loading ad');
      // 保存请求到的广告内容用于展示
      const returnAds = ads;
    }
  };
  // 创建AdLoader广告对象
  const adLoader: advertising.AdLoader = new advertising.AdLoader(context);
  // 调用广告请求接口
  hilog.info(0x0000, 'testTag', 'Start to load ad');
  adLoader.loadAd(adRequestParams, adOptions, adLoaderListener);
}

loadAdWithMultiSlots

loadAdWithMultiSlots(adParams: AdRequestParams[], adOptions: AdOptions, listener: MultiSlotsAdLoadListener): void

请求多广告位广告。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

错误码：

以下错误码的详细介绍请参见广告服务框架错误码参考。

示例：

其中context的获取方式参见各类Context的获取方式。

import { common } from '@kit.AbilityKit';
import { advertising } from '@kit.AdsKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

function loadAdWithMultiSlots(context: common.Context): void {
  const adRequestParamsArray: advertising.AdRequestParams[] = [
    {
      // 广告类型
      adType: 3,
      // 测试广告位ID
      adId: 'testy63txaom86'
    },
    {
      // 广告类型
      adType: 3,
      // 测试广告位ID
      adId: 'testy63txaom86'
    }
  ];
  const adOptions: advertising.AdOptions = {
    // 可选自定义参数，设置是否允许使用流量下载广告素材 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 multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = {
    // 广告请求失败回调
    onAdLoadFailure: (errorCode: number, errorMsg: string) => {
      hilog.error(0x0000, 'testTag', `Fail to load multiSlots ad. Code is ${errorCode}, message is ${errorMsg}`);
    },
    // 广告请求成功回调
    onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => {
      hilog.info(0x0000, 'testTag', 'Succeed in loading multiSlots ad');
      // 保存请求到的广告内容为数组用于展示
      const returnAds: Array<advertising.Advertisement> = [];
      ads.forEach((adsArray) => returnAds.push(...adsArray));
    }
  };
  // 创建AdLoader广告对象
  const adLoader: advertising.AdLoader = new advertising.AdLoader(context);
  // 调用广告请求接口
  hilog.info(0x0000, 'testTag', 'Start to load multiSlots ad');
  adLoader.loadAdWithMultiSlots(adRequestParamsArray, adOptions, multiSlotsAdLoaderListener);
}

AdLoadListener

单广告位广告请求回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

onAdLoadFailure

onAdLoadFailure(errorCode: number, errorMsg: string): void

广告请求失败回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

onAdLoadSuccess

onAdLoadSuccess(ads: Array<Advertisement>): void

广告请求成功后回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

示例：

import { advertising } from '@kit.AdsKit';

const adLoaderListener: advertising.AdLoadListener = {
  onAdLoadFailure: (errorCode: number, errorMsg: string) => {
  },
  onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => {
  }
}

MultiSlotsAdLoadListener

多广告位广告请求回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

onAdLoadFailure

onAdLoadFailure(errorCode: number, errorMsg: string): void

多广告位广告请求失败回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

onAdLoadSuccess

onAdLoadSuccess(adsMap: Map<string, Array<Advertisement>>): void

多广告位广告请求成功后回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

示例：

import { advertising } from '@kit.AdsKit';

const multiSlotsAdLoadListener: advertising.MultiSlotsAdLoadListener = {
  onAdLoadFailure: (errorCode: number, errorMsg: string) => {
  },
  onAdLoadSuccess: (adsMap: Map<string, Array<advertising.Advertisement>>) => {
  }
}

AdInteractionListener

广告状态变化回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

onStatusChanged

onStatusChanged(status: string, ad: Advertisement, data: string)

广告状态回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

参数：

示例：

import { advertising } from '@kit.AdsKit';

const adInteractionListener: advertising.AdInteractionListener = {
  onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => {

  }
}

AdOptions

广告配置参数。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

AdRequestParams

广告请求参数。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

AdDisplayOptions

广告展示参数。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

Advertisement

type Advertisement = _Advertisement

请求的广告内容。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Advertising.Ads

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ads Kit（广告服务）

harmony 鸿蒙广告服务框架错误码

harmony 鸿蒙广告标识服务错误码

harmony 鸿蒙@ohos.advertising.AdComponent (非全屏广告展示组件)

harmony 鸿蒙@ohos.advertising.AdsServiceExtensionAbility (广告扩展服务)(系统接口)

harmony 鸿蒙@ohos.advertising.AdsServiceExtensionAbility (广告扩展服务)

harmony 鸿蒙@ohos.advertising.AutoAdComponent (轮播广告展示组件)

harmony 鸿蒙advertisement (广告内容)

harmony 鸿蒙@ohos.identifier.oaid (广告标识服务)(系统接口)

harmony 鸿蒙@ohos.identifier.oaid (广告标识服务)