1# @ohos.advertising (广告服务框架) 2 3本模块提供广告操作能力，包括请求广告、展示广告。 4 5> **说明：**<br/> 6> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8## 导入模块 9 10```ts 11import { advertising } from '@kit.AdsKit'; 12``` 13 14## advertising.showAd 15 16showAd(ad: Advertisement, options: AdDisplayOptions, context?: common.UIAbilityContext): void 17 18展示全屏广告。 19 20**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 21 22**系统能力：** SystemCapability.Advertising.Ads 23 24**参数：** 25 26| 参数名 | 类型 | 必填 | 说明 | 27|---------|----------------------------------------------------------------------------------------------|-----|------------------------------------------------------------------| 28| ad | [Advertisement](#advertisement) | 是 | 广告对象。 | 29| options | [AdDisplayOptions](#addisplayoptions) | 是 | 广告展示参数。 | 30| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | 否 | UIAbility的上下文环境，不设置从api: @ohos.app.ability.common中获取。 | 31 32**错误码：** 33 34以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 35 36| 错误码ID | 错误信息 | 37|----------|-----------------------------------------------------------------------------------------| 38| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. | 39| 21800001 | System internal error. | 40| 21800004 | Failed to display the ad. | 41 42**示例：** 43 44```ts 45import { common } from '@kit.AbilityKit'; 46import { advertising } from '@kit.AdsKit'; 47import { hilog } from '@kit.PerformanceAnalysisKit'; 48 49@Entry 50@Component 51struct Index { 52 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 53 // 请求到的广告内容 54 private ad?: advertising.Advertisement; 55 // 广告展示参数 56 private adDisplayOptions: advertising.AdDisplayOptions = { 57 // 是否静音，默认不静音 58 mute: false 59 } 60 61 build() { 62 Column() { 63 Button('showAd') 64 .onClick(() => { 65 try { 66 // 调用全屏广告展示接口 67 advertising.showAd(this.ad, this.adDisplayOptions, this.context); 68 } catch (err) { 69 hilog.error(0x0000, 'testTag', `Fail to show ad. Code is ${err.code}, message is ${err.message}`); 70 } 71 }); 72 } 73 .width('100%') 74 .height('100%') 75 } 76} 77``` 78 79## advertising.getAdRequestBody<sup>12+</sup> 80 81getAdRequestBody(adParams: AdRequestParams[], adOptions: AdOptions): Promise<string> 82 83获取广告请求响应体，使用Promise异步回调（该接口仅对部分系统预置应用开放）。 84 85**系统能力：** SystemCapability.Advertising.Ads 86 87**参数：** 88 89| 参数名 | 类型 | 必填 | 说明 | 90|-----------|---------------------------------------|-----|------------------------------------------------| 91| adParams | [AdRequestParams[]](#adrequestparams) | 是 | 广告请求参数。<br/> - 该接口体的adid参数可以不传。 | 92| adOptions | [AdOptions](#adoptions) | 是 | 广告配置。 | 93 94**返回值：** 95 96| 类型 | 说明 | 97|-----------------------|-----------------------------------| 98| Promise<string> | Promise对象，返回字符类型的广告数据。 | 99 100**错误码：** 101 102以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 103 104| 错误码ID | 错误信息 | 105|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| 106| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 107| 801 | Device not supported. | 108| 21800001 | System internal error. | 109 110**示例：** 111 112```ts 113import { advertising } from '@kit.AdsKit'; 114import { Prompt } from '@kit.ArkUI'; 115import { BusinessError } from '@kit.BasicServicesKit'; 116import { hilog } from '@kit.PerformanceAnalysisKit'; 117 118function getAdRequestBody(): void { 119 const adRequestParamsArray: advertising.AdRequestParams[] = []; 120 const adRequestParams: advertising.AdRequestParams = { 121 adId: 'testu7m3hc4gvm', 122 adType: 3, 123 adCount: 2, 124 adWidth: 100, 125 adHeight: 100 126 }; 127 adRequestParamsArray.push(adRequestParams); 128 const adOptions: advertising.AdOptions = { 129 // 设置是否只请求非个性化广告 0：请求个性化广告与非个性化广告 1：只请求非个性化广告。不填以业务逻辑为准 130 nonPersonalizedAd: 0, 131 // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望 132 tagForChildProtection: -1, 133 // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望 134 tagForUnderAgeOfPromise: -1, 135 // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众 136 adContentClassification: 'A' 137 }; 138 advertising.getAdRequestBody(adRequestParamsArray, adOptions).then((data) => { 139 hilog.info(0x0000, 'testTag', `Succeeded in getting ad request body. Data is ${JSON.stringify(data)}`); 140 Prompt.showToast({ 141 message: data, 142 duration: 1000 143 }); 144 }).catch((error: BusinessError) => { 145 hilog.error(0x0000, 'testTag', `Fail to get ad request body. Code is ${error.code}, message is ${error.message}`); 146 Prompt.showToast({ 147 message: error.code.toString() + ',' + error.message, 148 duration: 1000 149 }); 150 }) 151} 152``` 153 154## advertising.parseAdResponse<sup>12+</sup> 155 156parseAdResponse(adResponse: string, listener: MultiSlotsAdLoadListener, context: common.UIAbilityContext): void 157 158解析并处理广告响应体（该接口仅对部分系统预置应用开放）。 159 160**系统能力：** SystemCapability.Advertising.Ads 161 162**参数：** 163 164| 参数名 | 类型 | 必填 | 说明 | 165|------------|----------------------------------------------------------------------------------------------|-----|----------------------| 166| adResponse | string | 是 | 广告请求参数。 | 167| listener | [MultiSlotsAdLoadListener](#multislotsadloadlistener) | 是 | 请求广告回调监听。 | 168| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | 是 | UIAbility的上下文环境。 | 169 170**错误码：** 171 172以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 173 174| 错误码ID | 错误信息 | 175|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| 176| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 177| 801 | Device not supported. | 178| 21800001 | System internal error. | 179| 21800005 | Failed to parse the ad response. | 180 181**示例：** 182 183其中context的获取方式参见[UIAbilityContext的获取方式](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 184 185```ts 186import { common } from '@kit.AbilityKit'; 187import { advertising } from '@kit.AdsKit'; 188import { hilog } from '@kit.PerformanceAnalysisKit'; 189 190function parseAdResponse(adResponse: string, context: common.UIAbilityContext): void { 191 // 广告解析处理回调监听 192 const multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = { 193 // 广告解析处理失败回调 194 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 195 hilog.error(0x0000, 'testTag', `Fail to load multiSlots ad. Code is ${errorCode}, message is ${errorMsg}`); 196 }, 197 // 广告解析处理成功回调 198 onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => { 199 hilog.info(0x0000, 'testTag', 'Succeed in loading multiSlots ad'); 200 // 保存解析处理完成的广告内容为数组用于展示 201 const returnAds: Array<advertising.Advertisement> = []; 202 ads.forEach((adsArray) => returnAds.push(...adsArray)); 203 } 204 }; 205 // 调用响应体解析接口 206 hilog.info(0x0000, 'testTag', 'Start to parse ad response'); 207 advertising.parseAdResponse(adResponse, multiSlotsAdLoaderListener, context); 208} 209``` 210 211## advertising.registerWebAdInterface<sup>12+</sup> 212 213registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext): void 214 215注入广告JavaScript对象到Web组件中（该接口仅对部分系统预置应用开放）。 216 217**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 218 219**系统能力：** SystemCapability.Advertising.Ads 220 221**参数：** 222 223| 参数名 | 类型 | 必填 | 说明 | 224|------------|----------------------------------------------------------------------------------------------|-----|----------------------| 225| controller | web_webview.[WebviewController](../apis-arkweb/js-apis-webview.md#webviewcontroller) | 是 | Web组件控制器。 | 226| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | 是 | UIAbility的上下文环境。 | 227 228**错误码：** 229 230以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 231 232| 错误码ID | 错误信息 | 233|----------|-----------------------------------------------------------------------------------------| 234| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. | 235| 21800001 | System internal error. | 236 237**示例：** 238 239```ts 240import { common } from '@kit.AbilityKit'; 241import { advertising } from '@kit.AdsKit'; 242import { webview } from '@kit.ArkWeb'; 243import { hilog } from '@kit.PerformanceAnalysisKit'; 244 245@Entry 246@Component 247struct Index { 248 private webController: webview.WebviewController = new webview.WebviewController(); 249 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 250 251 build() { 252 Column() { 253 Button('registerWebAdInterface') 254 .onClick(() => { 255 try { 256 advertising.registerWebAdInterface(this.webController, this.context); 257 } catch (err) { 258 hilog.error(0x0000, 'testTag', `Fail to register web ad interface. Code is ${err.code}, message is ${err.message}`); 259 } 260 }) 261 262 Web({ 263 src: 'www.example.com', 264 controller: this.webController 265 }) 266 .width("100%") 267 .height("100%") 268 } 269 } 270} 271``` 272 273## advertising.registerWebAdInterface<sup>16+</sup> 274 275registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext, needRefresh: boolean): void 276 277注入广告JavaScript对象到Web组件中（该接口仅对部分系统预置应用开放）。 278 279**原子化服务API：** 从API version 16开始，该接口支持在原子化服务中使用。 280 281**系统能力：** SystemCapability.Advertising.Ads 282 283**参数：** 284 285| 参数名 | 类型 | 必填 | 说明 | 286|-------------|----------------------------------------------------------------------------------------------|-----|-------------------------------------------| 287| controller | web_webview.[WebviewController](../apis-arkweb/js-apis-webview.md#webviewcontroller) | 是 | Web组件控制器。 | 288| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | 是 | UIAbility的上下文环境。 | 289| needRefresh | boolean | 是 | 是否需要刷新页面（true: 需要；false: 不需要）。 | 290 291**错误码：** 292 293以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 294 295| 错误码ID | 错误信息 | 296|----------|--------------------------------------------------------------------------------------| 297| 401 | Invalid input parameter. Possible causes: Mandatory parameters are left unspecified. | 298| 21800001 | operation javascriptRegister error. | 299 300**示例：** 301 302```ts 303import { common } from '@kit.AbilityKit'; 304import { advertising } from '@kit.AdsKit'; 305import { webview } from '@kit.ArkWeb'; 306import { hilog } from '@kit.PerformanceAnalysisKit'; 307 308@Entry 309@Component 310struct Index { 311 private webController: webview.WebviewController = new webview.WebviewController(); 312 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 313 314 build() { 315 Column() { 316 Button('registerWebAdInterface') 317 .onClick(() => { 318 try { 319 advertising.registerWebAdInterface(this.webController, this.context, true); 320 } catch (err) { 321 hilog.error(0x0000, 'testTag', `Fail to register web ad interface. Code is ${err.code}, message is ${err.message}`); 322 } 323 }) 324 325 Web({ 326 src: 'www.example.com', 327 controller: this.webController 328 }) 329 .width("100%") 330 .height("100%") 331 } 332 } 333} 334``` 335 336## advertising.deleteWebAdInterface<sup>16+</sup> 337 338deleteWebAdInterface(controller: web_webview.WebviewController, needRefresh: boolean): void 339 340删除通过registerWebAdInterface注入的广告JavaScript对象（该接口仅对部分系统预置应用开放）。 341 342**原子化服务API：** 从API version 16开始，该接口支持在原子化服务中使用。 343 344**系统能力：** SystemCapability.Advertising.Ads 345 346**参数：** 347 348| 参数名 | 类型 | 必填 | 说明 | 349|-------------|--------------------------------------------------------------------------------------|-----|-------------------------------------------| 350| controller | web_webview.[WebviewController](../apis-arkweb/js-apis-webview.md#webviewcontroller) | 是 | Web组件控制器。 | 351| needRefresh | boolean | 是 | 是否需要刷新页面（true: 需要；false: 不需要）。 | 352 353**错误码：** 354 355以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 356 357| 错误码ID | 错误信息 | 358|----------|--------------------------------------------------------------------------------------| 359| 401 | Invalid input parameter. Possible causes: Mandatory parameters are left unspecified. | 360| 21800001 | operation javascriptRegister error. | 361 362**示例：** 363 364```ts 365import { advertising } from '@kit.AdsKit'; 366import { webview } from '@kit.ArkWeb'; 367import { hilog } from '@kit.PerformanceAnalysisKit'; 368 369@Entry 370@Component 371struct Index { 372 private webController: webview.WebviewController = new webview.WebviewController(); 373 374 build() { 375 Column() { 376 Button('deleteWebAdInterface') 377 .onClick(() => { 378 try { 379 advertising.deleteWebAdInterface(this.webController, true); 380 } catch (err) { 381 hilog.error(0x0000, 'testTag', `Fail to delete web ad interface. Code is ${err.code}, message is ${err.message}`); 382 } 383 }) 384 385 Web({ 386 src: 'www.example.com', 387 controller: this.webController, 388 }) 389 .width('100%') 390 .height('100%') 391 } 392 } 393} 394``` 395 396## AdLoader 397 398提供加载广告的功能。 399 400**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 401 402**系统能力：** SystemCapability.Advertising.Ads 403 404### constructor 405 406constructor(context: common.Context) 407 408构造函数。 409 410**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 411 412**系统能力：** SystemCapability.Advertising.Ads 413 414**参数：** 415 416| 参数名 | 类型 | 必填 | 说明 | 417|---------|----------------------------------------------------------------------------|-----|---------------------------------| 418| context | common.[Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | ability或application的上下文环境。 | 419 420**示例：** 421 422其中context的获取方式参见[各类Context的获取方式](../../application-models/application-context-stage.md#概述)。 423 424```ts 425import { advertising } from '@kit.AdsKit'; 426import { common } from '@kit.AbilityKit'; 427 428function createConstructor(context: common.Context): void { 429 const adLoader: advertising.AdLoader = new advertising.AdLoader(context); 430} 431``` 432 433### loadAd 434 435loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void 436 437请求单广告位广告。 438 439**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 440 441**系统能力：** SystemCapability.Advertising.Ads 442 443**参数：** 444 445| 参数名 | 类型 | 必填 | 说明 | 446|-----------|-------------------------------------|-----|-----------------| 447| adParam | [AdRequestParams](#adrequestparams) | 是 | 广告请求参数。 | 448| adOptions | [AdOptions](#adoptions) | 是 | 广告配置。 | 449| listener | [AdLoadListener](#adloadlistener) | 是 | 请求广告回调监听。 | 450 451**错误码：** 452 453以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 454 455| 错误码ID | 错误信息 | 456|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| 457| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 458| 801 | Device not supported. | 459| 21800001 | System internal error. | 460| 21800003 | Failed to load the ad request. | 461 462**示例：** 463 464其中context的获取方式参见[各类Context的获取方式](../../application-models/application-context-stage.md#概述)。 465 466```ts 467import { common } from '@kit.AbilityKit'; 468import { advertising } from '@kit.AdsKit'; 469import { hilog } from '@kit.PerformanceAnalysisKit'; 470 471function loadAd(context: common.Context): void { 472 const adRequestParams: advertising.AdRequestParams = { 473 // 广告类型 474 adType: 3, 475 // 测试广告位ID 476 adId: 'testy63txaom86' 477 }; 478 const adOptions: advertising.AdOptions = { 479 // 可选自定义参数，设置是否允许使用流量下载广告素材 0：不允许，1：允许，不设置以广告主设置为准。 480 allowMobileTraffic: 0, 481 // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望 482 tagForChildProtection: -1, 483 // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望 484 tagForUnderAgeOfPromise: -1, 485 // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众 486 adContentClassification: 'A' 487 }; 488 // 广告请求回调监听 489 const adLoaderListener: advertising.AdLoadListener = { 490 // 广告请求失败回调 491 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 492 hilog.error(0x0000, 'testTag', `Fail to load ad. Code is ${errorCode}, message is ${errorMsg}`); 493 }, 494 // 广告请求成功回调 495 onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => { 496 hilog.info(0x0000, 'testTag', 'Succeed in loading ad'); 497 // 保存请求到的广告内容用于展示 498 const returnAds = ads; 499 } 500 }; 501 // 创建AdLoader广告对象 502 const adLoader: advertising.AdLoader = new advertising.AdLoader(context); 503 // 调用广告请求接口 504 hilog.info(0x0000, 'testTag', 'Start to load ad'); 505 adLoader.loadAd(adRequestParams, adOptions, adLoaderListener); 506} 507``` 508 509### loadAdWithMultiSlots 510 511loadAdWithMultiSlots(adParams: AdRequestParams[], adOptions: AdOptions, listener: MultiSlotsAdLoadListener): void 512 513请求多广告位广告。 514 515**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 516 517**系统能力：** SystemCapability.Advertising.Ads 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522|-----------|-------------------------------------------------------|-----|-----------------| 523| adParams | [AdRequestParams](#adrequestparams)[] | 是 | 广告请求参数。 | 524| adOptions | [AdOptions](#adoptions) | 是 | 广告配置。 | 525| listener | [MultiSlotsAdLoadListener](#multislotsadloadlistener) | 是 | 请求广告回调监听。 | 526 527**错误码：** 528 529以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 530 531| 错误码ID | 错误信息 | 532|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| 533| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 534| 801 | Device not supported. | 535| 21800001 | System internal error. | 536| 21800003 | Failed to load the ad request. | 537 538**示例：** 539 540其中context的获取方式参见[各类Context的获取方式](../../application-models/application-context-stage.md#概述)。 541 542```ts 543import { common } from '@kit.AbilityKit'; 544import { advertising } from '@kit.AdsKit'; 545import { hilog } from '@kit.PerformanceAnalysisKit'; 546 547function loadAdWithMultiSlots(context: common.Context): void { 548 const adRequestParamsArray: advertising.AdRequestParams[] = [ 549 { 550 // 广告类型 551 adType: 3, 552 // 测试广告位ID 553 adId: 'testy63txaom86' 554 }, 555 { 556 // 广告类型 557 adType: 3, 558 // 测试广告位ID 559 adId: 'testy63txaom86' 560 } 561 ]; 562 const adOptions: advertising.AdOptions = { 563 // 可选自定义参数，设置是否允许使用流量下载广告素材 0：不允许，1：允许，不设置以广告主设置为准。 564 allowMobileTraffic: 0, 565 // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望 566 tagForChildProtection: -1, 567 // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求： -1默认值，不确定 0不希望 1希望 568 tagForUnderAgeOfPromise: -1, 569 // 设置广告内容分级上限: W: 3+,所有受众 PI: 7+,家长指导 J:12+,青少年 A: 16+/18+，成人受众 570 adContentClassification: 'A' 571 }; 572 // 广告请求回调监听 573 const multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = { 574 // 广告请求失败回调 575 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 576 hilog.error(0x0000, 'testTag', `Fail to load multiSlots ad. Code is ${errorCode}, message is ${errorMsg}`); 577 }, 578 // 广告请求成功回调 579 onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => { 580 hilog.info(0x0000, 'testTag', 'Succeed in loading multiSlots ad'); 581 // 保存请求到的广告内容为数组用于展示 582 const returnAds: Array<advertising.Advertisement> = []; 583 ads.forEach((adsArray) => returnAds.push(...adsArray)); 584 } 585 }; 586 // 创建AdLoader广告对象 587 const adLoader: advertising.AdLoader = new advertising.AdLoader(context); 588 // 调用广告请求接口 589 hilog.info(0x0000, 'testTag', 'Start to load multiSlots ad'); 590 adLoader.loadAdWithMultiSlots(adRequestParamsArray, adOptions, multiSlotsAdLoaderListener); 591} 592``` 593 594## AdLoadListener 595 596单广告位广告请求回调。 597 598**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 599 600**系统能力：** SystemCapability.Advertising.Ads 601 602### onAdLoadFailure 603 604onAdLoadFailure(errorCode: number, errorMsg: string): void 605 606广告请求失败回调。 607 608**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 609 610**系统能力：** SystemCapability.Advertising.Ads 611 612**参数：** 613 614| 参数名 | 类型 | 必填 | 说明 | 615|-----------|--------|-----|-----------------------| 616| errorCode | number | 是 | 广告请求失败的错误码。 | 617| errorMsg | string | 是 | 广告请求失败的错误信息。 | 618 619### onAdLoadSuccess 620 621onAdLoadSuccess(ads: Array<Advertisement>): void 622 623广告请求成功后回调。 624 625**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 626 627**系统能力：** SystemCapability.Advertising.Ads 628 629**参数：** 630 631| 参数名 | 类型 | 必填 | 说明 | 632|--------|----------------------------------------------|-----|---------| 633| ads | Array<[Advertisement](#advertisement)> | 是 | 广告数据。 | 634 635**示例：** 636 637```ts 638import { advertising } from '@kit.AdsKit'; 639 640const adLoaderListener: advertising.AdLoadListener = { 641 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 642 }, 643 onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => { 644 } 645} 646``` 647 648## MultiSlotsAdLoadListener 649 650多广告位广告请求回调。 651 652**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 653 654**系统能力：** SystemCapability.Advertising.Ads 655 656### onAdLoadFailure 657 658onAdLoadFailure(errorCode: number, errorMsg: string): void 659 660多广告位广告请求失败回调。 661 662**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 663 664**系统能力：** SystemCapability.Advertising.Ads 665 666**参数：** 667 668| 参数名 | 类型 | 必填 | 说明 | 669|-----------|--------|-----|-----------------------| 670| errorCode | number | 是 | 广告请求失败的错误码。 | 671| errorMsg | string | 是 | 广告请求失败的错误信息。 | 672 673### onAdLoadSuccess 674 675onAdLoadSuccess(adsMap: Map<string, Array<Advertisement>>): void 676 677多广告位广告请求成功后回调。 678 679**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 680 681**系统能力：** SystemCapability.Advertising.Ads 682 683**参数：** 684 685| 参数名 | 类型 | 必填 | 说明 | 686|--------|-----------------------------------------------------------------|-----|---------| 687| adsMap | Map<string, Array<[Advertisement](#advertisement)>> | 是 | 广告数据。 | 688 689**示例：** 690 691```ts 692import { advertising } from '@kit.AdsKit'; 693 694const multiSlotsAdLoadListener: advertising.MultiSlotsAdLoadListener = { 695 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 696 }, 697 onAdLoadSuccess: (adsMap: Map<string, Array<advertising.Advertisement>>) => { 698 } 699} 700``` 701 702## AdInteractionListener 703 704广告状态变化回调。 705 706**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 707 708**系统能力：** SystemCapability.Advertising.Ads 709 710### onStatusChanged 711 712onStatusChanged(status: string, ad: Advertisement, data: string) 713 714广告状态回调。 715 716**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 717 718**系统能力：** SystemCapability.Advertising.Ads 719 720**参数：** 721 722| 参数名 | 类型 | 必填 | 说明 | 723|--------|---------------------------------|-----|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 724| status | string | 是 | status：广告展示状态，取值<br/>onAdOpen（打开广告回调）、onAdClose（关闭广告回调）、onAdClick（点击广告回调）、onVideoPlayBegin（广告视频开始播放回调）、onVideoPlayEnd（广告视频播放结束回调）、onAdLoad（广告加载成功回调）、onAdFail（广告加载失败回调）、onMediaProgress（广告播放进度回调）、onMediaStart（广告开始播放回调）、onMediaPause（广告暂停播放回调）、onMediaStop（广告停止播放回调）、onMediaComplete（广告播放完成回调）、onMediaError（广告播放失败回调）、onLandscape（竖屏状态下点击全屏按钮回调）、onPortrait（全屏状态下点击返回按钮回调）、onAdReward (广告获得奖励回调) 、onMediaCountDown (广告倒计时回调) 、onBackClicked (返回点击广告回调)。 | 725| ad | [Advertisement](#advertisement) | 是 | 发生状态变化的广告内容。 | 726| data | string | 是 | 扩展信息。 | 727 728**示例：** 729 730```ts 731import { advertising } from '@kit.AdsKit'; 732 733const adInteractionListener: advertising.AdInteractionListener = { 734 onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => { 735 736 } 737} 738``` 739 740## AdOptions 741 742广告配置参数。 743 744**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 745 746**系统能力：** SystemCapability.Advertising.Ads 747 748| 名称 | 类型 | 只读 | 可选 | 说明 | 749|-------------------------|------------------------------------------|-----|-----|-----------------------------------------------------------------------------------------------------------------------------------------| 750| tagForChildProtection | number | 否 | 是 | 设置儿童保护标签，否希望根据 COPPA 的规定将您的内容视为面向儿童的内容。<br/>- -1：默认值，不确定。<br/>- 0：不希望。<br/>- 1：希望。<br/>默认为-1。 | 751| adContentClassification | string | 否 | 是 | 设置广告内容分级上限。<br/>- W：3+,所有受众。<br/>- PI：7+，家长指导。<br/>- J：12+，青少年。<br/>- A：16+/18+,成人受众。<br/>不填以业务逻辑为准。 | 752| nonPersonalizedAd | number | 否 | 是 | 设置是否只请求非个性化广告。<br/>- 0：请求个性化广告与非个性化广告。<br/>- 1：只请求非个性化广告。<br/>不填以业务逻辑为准。 | 753| [key: string] | number \| boolean \| string \| undefined | 否 | 是 | 自定义参数。 | 754 755## AdRequestParams 756 757广告请求参数。 758 759**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 760 761**系统能力：** SystemCapability.Advertising.Ads 762 763| 名称 | 类型 | 只读 | 可选 | 说明 | 764|-----------------|------------------------------------------|-----|-----|-----------------------------------------------------------------------------------------------------------------------------------------------------------| 765| adId | string | 否 | 否 | 广告位ID。<br/>- getAdRequestBody接口可以不传该参数。 | 766| adType | number | 否 | 是 | 请求的广告类型。<br/>- 1：开屏广告。<br/>- 3：原生广告。<br/>- 7：激励广告。<br/>- 8：banner广告。<br/>- 12：插屏广告。<br/>- 60：贴片广告。<br/>不填默认为原生广告类型。 | 767| adCount | number | 否 | 是 | 请求的广告数量。不填以业务逻辑为准。 | 768| adWidth | number | 否 | 是 | 请求广告时期望的创意宽度，单位vp（横幅广告必填）。不填以业务逻辑为准。 | 769| adHeight | number | 否 | 是 | 请求广告时期望的创意高度，单位vp（横幅广告必填）。不填以业务逻辑为准。 | 770| adSearchKeyword | string | 否 | 是 | 广告关键字。不填默认""。 | 771| [key: string] | number \| boolean \| string \| undefined | 否 | 是 | 自定义参数。<br/>- oaid: 类型string，开放匿名设备标识符，用于精准推送广告。不填无法获取到个性化广告。默认值为""。 | 772 773## AdDisplayOptions 774 775广告展示参数。 776 777**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 778 779**系统能力：** SystemCapability.Advertising.Ads 780 781| 名称 | 类型 | 只读 | 可选 | 说明 | 782|-----------------------|------------------------------------------|-----|-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 783| customData | string | 否 | 是 | 媒体自定义数据。用于服务端通知媒体服务器某位用户因为与激励视频广告互动而应予以奖励，从而规避欺骗的行为（不填则不会通知）。 | 784| userId | string | 否 | 是 | 媒体自定义用户id。用于服务端通知媒体服务器某位用户因为与激励视频广告互动而应予以奖励，从而规避欺骗的行为（不填则不会通知）。 | 785| useMobileDataReminder | boolean | 否 | 是 | 使用移动数据播放视频或下载应用时是否弹框通知用户。<br/>- true：弹框通知。<br/>- false：不弹框通知。<br/>该参数依赖流量弹窗功能，当前不支持完整功能的使用，暂不确定默认值。 | 786| mute | boolean | 否 | 是 | 广告视频播放是否静音。<br/>- true：静音播放。<br/>- false：非静音播放。<br/>不填以业务逻辑为准。 | 787| audioFocusType | number | 否 | 是 | 视频播放过程中获得音频焦点的场景类型。<br/>- 0：视频播放静音、非静音时都获取焦点。<br/>- 1：视频静音播放时不获取焦点。<br/>- 2：视频播放静音、非静音时都不获取焦点。<br/>该接口依赖的相关功能当前不支持使用，暂不确定默认值。 | 788| [key: string] | number \| boolean \| string \| undefined | 否 | 是 | 自定义参数。<br/>- refreshTime：类型number，单位：ms，取值范围[30000, 120000]。AutoAdComponent组件可选自定义参数，用于控制广告的轮播时间间隔。填写了该参数，则广告按照参数配置的时间间隔轮播，否则广告不会轮播，只会展示广告响应中的第一个广告内容。 | 789 790## Advertisement 791 792type Advertisement = _Advertisement 793 794请求的广告内容。 795 796**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 797 798**系统能力：** SystemCapability.Advertising.Ads 799 800| 类型 | 说明 | 801|--------------------------------------------------------------|----------------------| 802| [_Advertisement](js-apis-inner-advertising-advertisement.md) | 表示Advertisement对象。 |