1# @ohos.advertising (Ads Service Framework) 2 3The advertising module provides APIs for requesting and displaying ads. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import { advertising } from '@kit.AdsKit'; 13``` 14 15## advertising.showAd 16 17showAd(ad: Advertisement, options: AdDisplayOptions, context?: common.UIAbilityContext): void 18 19Shows a full-screen ad. 20 21**Atomic service API**: This API can be used in atomic services since API version 12. 22 23**System capability**: SystemCapability.Advertising.Ads 24 25**Parameters** 26 27| Name | Type | Mandatory| Description | 28|---------|----------------------------------------------------------------------------------------------|-----|------------------------------------------------------------------| 29| ad | [Advertisement](#advertisement) | Yes | Ad object. | 30| options | [AdDisplayOptions](#addisplayoptions) | Yes | Ad display parameters. | 31| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | No | Context of the UIAbility. If this parameter is not set, the value is obtained from @ohos.app.ability.common.| 32 33**Error codes** 34 35For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 36 37| ID| Error Message | 38|----------|-----------------------------------------------------------------------------------------| 39| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. | 40| 21800001 | System internal error. | 41| 21800004 | Failed to display the ad. | 42 43**Example** 44 45```ts 46import { common } from '@kit.AbilityKit'; 47import { advertising } from '@kit.AdsKit'; 48import { hilog } from '@kit.PerformanceAnalysisKit'; 49 50@Entry 51@Component 52struct Index { 53 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 54 // Requested ad content. 55 private ad?: advertising.Advertisement; 56 // Ad display parameters. 57 private adDisplayOptions: advertising.AdDisplayOptions = { 58 // Whether to mute the ad. By default, the ad is not muted. 59 mute: false 60 } 61 62 build() { 63 Column() { 64 Button('showAd') 65 .onClick(() => { 66 try { 67 // Show the ad. 68 advertising.showAd(this.ad, this.adDisplayOptions, this.context); 69 } catch (err) { 70 hilog.error(0x0000, 'testTag', `Fail to show ad. Code is ${err.code}, message is ${err.message}`); 71 } 72 }); 73 } 74 .width('100%') 75 .height('100%') 76 } 77} 78``` 79 80## advertising.getAdRequestBody<sup>12+</sup> 81 82getAdRequestBody(adParams: AdRequestParams[], adOptions: AdOptions): Promise<string> 83 84Obtains the body of an ad request. This API uses a promise to return the result. (This API is available only for some preset applications.) 85 86**System capability**: SystemCapability.Advertising.Ads 87 88**Parameters** 89 90| Name | Type | Mandatory| Description | 91|-----------|---------------------------------------|-----|------------------------------------------------| 92| adParams | [AdRequestParams[]](#adrequestparams) | Yes | Ad request parameters.<br> - The **adid** parameter is optional.| 93| adOptions | [AdOptions](#adoptions) | Yes | Ad configuration. | 94 95**Return value** 96 97| Type | Description | 98|-----------------------|-----------------------------------| 99| Promise<string> | Promise used to return the ad data of the string type.| 100 101**Error codes** 102 103For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 104 105| ID| Error Message | 106|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| 107| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 108| 801 | Device not supported. | 109| 21800001 | System internal error. | 110 111**Example** 112 113```ts 114import { advertising } from '@kit.AdsKit'; 115import { Prompt } from '@kit.ArkUI'; 116import { BusinessError } from '@kit.BasicServicesKit'; 117import { hilog } from '@kit.PerformanceAnalysisKit'; 118 119function getAdRequestBody(): void { 120 const adRequestParamsArray: advertising.AdRequestParams[] = []; 121 const adRequestParams: advertising.AdRequestParams = { 122 adId: 'testu7m3hc4gvm', 123 adType: 3, 124 adCount: 2, 125 adWidth: 100, 126 adHeight: 100 127 }; 128 adRequestParamsArray.push(adRequestParams); 129 const adOptions: advertising.AdOptions = { 130 // Set whether to request only non-personalized ads. 0: to request personalized ads and non-personalized ads; 1: to request only non-personalized ads. If this parameter is left blank, the service logic prevails. 131 nonPersonalizedAd: 0, 132 // Specify whether you want your ad content to be treated as COPPA-compliant. The following values are available: -1 (default value): uncertain; 0: no; 1: yes. 133 tagForChildProtection: -1, 134 // Specify whether you want the ad request to be processed in a way that meets the GDPR for users in the EEA under the age of consent. The following values are available: -1 (default value): uncertain; 0: no; 1: yes. 135 tagForUnderAgeOfPromise: -1, 136 // Maximum ad content rating. W: aged 3 and up; PI: aged 7 and up, under parental guidance; J: teenagers aged 12 and up; A: adults aged 16 or 18 and up. 137 adContentClassification: 'A' 138 }; 139 advertising.getAdRequestBody(adRequestParamsArray, adOptions).then((data) => { 140 hilog.info(0x0000, 'testTag', `Succeeded in getting ad request body. Data is ${JSON.stringify(data)}`); 141 Prompt.showToast({ 142 message: data, 143 duration: 1000 144 }); 145 }).catch((error: BusinessError) => { 146 hilog.error(0x0000, 'testTag', `Fail to get ad request body. Code is ${error.code}, message is ${error.message}`); 147 Prompt.showToast({ 148 message: error.code.toString() + ',' + error.message, 149 duration: 1000 150 }); 151 }) 152} 153``` 154 155## advertising.parseAdResponse<sup>12+</sup> 156 157parseAdResponse(adResponse: string, listener: MultiSlotsAdLoadListener, context: common.UIAbilityContext): void 158 159Parses and processes the ad response body. (This API is available only for some preset applications.) 160 161**System capability**: SystemCapability.Advertising.Ads 162 163**Parameters** 164 165| Name | Type | Mandatory| Description | 166|------------|----------------------------------------------------------------------------------------------|-----|----------------------| 167| adResponse | string | Yes | Ad response body. | 168| listener | [MultiSlotsAdLoadListener](#multislotsadloadlistener) | Yes | Ad request callback. | 169| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | Yes | UIAbility context.| 170 171**Error codes** 172 173For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 174 175| ID| Error Message | 176|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| 177| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 178| 801 | Device not supported. | 179| 21800001 | System internal error. | 180| 21800005 | Failed to parse the ad response. | 181 182**Example** 183 184For details about how to obtain the context, see [Obtaining the Context of UIAbility](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). 185 186```ts 187import { common } from '@kit.AbilityKit'; 188import { advertising } from '@kit.AdsKit'; 189import { hilog } from '@kit.PerformanceAnalysisKit'; 190 191function parseAdResponse(adResponse: string, context: common.UIAbilityContext): void { 192 // Listen for the ad parsing callback. 193 const multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = { 194 // Called when ad parsing fails. 195 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 196 hilog.error(0x0000, 'testTag', `Fail to load multiSlots ad. Code is ${errorCode}, message is ${errorMsg}`); 197 }, 198 // Called when ad parsing is successful. 199 onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => { 200 hilog.info(0x0000, 'testTag', 'Succeed in loading multiSlots ad'); 201 // Save the parsed ad content as an array for display. 202 const returnAds: Array<advertising.Advertisement> = []; 203 ads.forEach((adsArray) => returnAds.push(...adsArray)); 204 } 205 }; 206 // Call the API to parse the response body. 207 hilog.info(0x0000, 'testTag', 'Start to parse ad response'); 208 advertising.parseAdResponse(adResponse, multiSlotsAdLoaderListener, context); 209} 210``` 211 212## advertising.registerWebAdInterface<sup>12+</sup> 213 214registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext): void 215 216Injects an ad JavaScript object to the **Web** component. (This API is available only for some preset applications.) 217 218**Atomic service API**: This API can be used in atomic services since API version 12. 219 220**System capability**: SystemCapability.Advertising.Ads 221 222**Parameters** 223 224| Name | Type | Mandatory| Description | 225|------------|----------------------------------------------------------------------------------------------|-----|----------------------| 226| controller | web_webview.[WebviewController](../apis-arkweb/arkts-apis-webview-WebviewController.md) | Yes | Controller of the **Web** component. | 227| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | Yes | UIAbility context.| 228 229**Error codes** 230 231For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 232 233| ID| Error Message | 234|----------|-----------------------------------------------------------------------------------------| 235| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. | 236| 21800001 | System internal error. | 237 238**Example** 239 240```ts 241import { common } from '@kit.AbilityKit'; 242import { advertising } from '@kit.AdsKit'; 243import { webview } from '@kit.ArkWeb'; 244import { hilog } from '@kit.PerformanceAnalysisKit'; 245 246@Entry 247@Component 248struct Index { 249 private webController: webview.WebviewController = new webview.WebviewController(); 250 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 251 252 build() { 253 Column() { 254 Button('registerWebAdInterface') 255 .onClick(() => { 256 try { 257 advertising.registerWebAdInterface(this.webController, this.context); 258 } catch (err) { 259 hilog.error(0x0000, 'testTag', `Fail to register web ad interface. Code is ${err.code}, message is ${err.message}`); 260 } 261 }) 262 263 Web({ 264 src: 'www.example.com', 265 controller: this.webController 266 }) 267 .width("100%") 268 .height("100%") 269 } 270 } 271} 272``` 273 274## advertising.registerWebAdInterface<sup>16+</sup> 275 276registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext, needRefresh: boolean): void 277 278Injects an ad JavaScript object to the **Web** component. (This API is available only for some preset applications.) 279 280**Atomic service API**: This API can be used in atomic services since API version 16. 281 282**System capability**: SystemCapability.Advertising.Ads 283 284**Parameters** 285 286| Name | Type | Mandatory| Description | 287|-------------|----------------------------------------------------------------------------------------------|-----|-------------------------------------------| 288| controller | web_webview.[WebviewController](../apis-arkweb/arkts-apis-webview-WebviewController.md) | Yes | Controller of the **Web** component. | 289| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | Yes | UIAbility context. | 290| needRefresh | boolean | Yes | Whether a page needs to be refreshed. (The value **true** means that a page needs to be refreshed; the value **false** means the opposite.)| 291 292**Error codes** 293 294For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 295 296| ID| Error Message | 297|----------|--------------------------------------------------------------------------------------| 298| 401 | Invalid input parameter. Possible causes: Mandatory parameters are left unspecified. | 299| 21800001 | operation javascriptRegister error. | 300 301**Example** 302 303```ts 304import { common } from '@kit.AbilityKit'; 305import { advertising } from '@kit.AdsKit'; 306import { webview } from '@kit.ArkWeb'; 307import { hilog } from '@kit.PerformanceAnalysisKit'; 308 309@Entry 310@Component 311struct Index { 312 private webController: webview.WebviewController = new webview.WebviewController(); 313 private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 314 315 build() { 316 Column() { 317 Button('registerWebAdInterface') 318 .onClick(() => { 319 try { 320 advertising.registerWebAdInterface(this.webController, this.context, true); 321 } catch (err) { 322 hilog.error(0x0000, 'testTag', `Fail to register web ad interface. Code is ${err.code}, message is ${err.message}`); 323 } 324 }) 325 326 Web({ 327 src: 'www.example.com', 328 controller: this.webController 329 }) 330 .width("100%") 331 .height("100%") 332 } 333 } 334} 335``` 336 337## advertising.deleteWebAdInterface<sup>16+</sup> 338 339deleteWebAdInterface(controller: web_webview.WebviewController, needRefresh: boolean): void 340 341Deletes the ad JavaScript object injected through **registerWebAdInterface**. (This API is available only to some preset applications.) 342 343**Atomic service API**: This API can be used in atomic services since API version 16. 344 345**System capability**: SystemCapability.Advertising.Ads 346 347**Parameters** 348 349| Name | Type | Mandatory| Description | 350|-------------|--------------------------------------------------------------------------------------|-----|-------------------------------------------| 351| controller | web_webview.[WebviewController](../apis-arkweb/arkts-apis-webview-WebviewController.md) | Yes | Controller of the **Web** component. | 352| needRefresh | boolean | Yes | Whether a page needs to be refreshed. (The value **true** means that a page needs to be refreshed; the value **false** means the opposite.)| 353 354**Error codes** 355 356For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 357 358| ID| Error Message | 359|----------|--------------------------------------------------------------------------------------| 360| 401 | Invalid input parameter. Possible causes: Mandatory parameters are left unspecified. | 361| 21800001 | operation javascriptRegister error. | 362 363**Example** 364 365```ts 366import { advertising } from '@kit.AdsKit'; 367import { webview } from '@kit.ArkWeb'; 368import { hilog } from '@kit.PerformanceAnalysisKit'; 369 370@Entry 371@Component 372struct Index { 373 private webController: webview.WebviewController = new webview.WebviewController(); 374 375 build() { 376 Column() { 377 Button('deleteWebAdInterface') 378 .onClick(() => { 379 try { 380 advertising.deleteWebAdInterface(this.webController, true); 381 } catch (err) { 382 hilog.error(0x0000, 'testTag', `Fail to delete web ad interface. Code is ${err.code}, message is ${err.message}`); 383 } 384 }) 385 386 Web({ 387 src: 'www.example.com', 388 controller: this.webController, 389 }) 390 .width('100%') 391 .height('100%') 392 } 393 } 394} 395``` 396 397## AdLoader 398 399Provides the APIs for loading ads. 400 401**Atomic service API**: This API can be used in atomic services since API version 12. 402 403**System capability**: SystemCapability.Advertising.Ads 404 405### constructor 406 407constructor(context: common.Context) 408 409Constructor. 410 411**Atomic service API**: This API can be used in atomic services since API version 12. 412 413**System capability**: SystemCapability.Advertising.Ads 414 415**Parameters** 416 417| Name | Type | Mandatory| Description | 418|---------|----------------------------------------------------------------------------|-----|---------------------------------| 419| context | common.[Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Context of the ability or application.| 420 421**Example** 422 423For details about how to obtain the context, see [Context](../../application-models/application-context-stage.md#overview). 424 425```ts 426import { advertising } from '@kit.AdsKit'; 427import { common } from '@kit.AbilityKit'; 428 429function createConstructor(context: common.Context): void { 430 const adLoader: advertising.AdLoader = new advertising.AdLoader(context); 431} 432``` 433 434### loadAd 435 436loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void 437 438Loads an ad. 439 440**Atomic service API**: This API can be used in atomic services since API version 12. 441 442**System capability**: SystemCapability.Advertising.Ads 443 444**Parameters** 445 446| Name | Type | Mandatory| Description | 447|-----------|-------------------------------------|-----|-----------------| 448| adParam | [AdRequestParams](#adrequestparams) | Yes | Ad request parameters. | 449| adOptions | [AdOptions](#adoptions) | Yes | Ad configuration. | 450| listener | [AdLoadListener](#adloadlistener) | Yes | Ad request callback.| 451 452**Error codes** 453 454For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 455 456| ID| Error Message | 457|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| 458| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 459| 801 | Device not supported. | 460| 21800001 | System internal error. | 461| 21800003 | Failed to load the ad request. | 462 463**Example** 464 465For details about how to obtain the context, see [Context](../../application-models/application-context-stage.md#overview). 466 467```ts 468import { common } from '@kit.AbilityKit'; 469import { advertising } from '@kit.AdsKit'; 470import { hilog } from '@kit.PerformanceAnalysisKit'; 471 472function loadAd(context: common.Context): void { 473 const adRequestParams: advertising.AdRequestParams = { 474 // Ad type. 475 adType: 3, 476 // Ad ID. 477 adId: 'testy63txaom86' 478 }; 479 const adOptions: advertising.AdOptions = { 480 // Optional custom parameter, which specifies whether to allow ad asset download using mobile data. The options are 0 (no) and 1 (yes). If this parameter is not set, the advertiser's setting will be used. 481 allowMobileTraffic: 0, 482 // Specify whether you want your ad content to be treated as COPPA-compliant. The following values are available: -1 (default value): uncertain; 0: no; 1: yes. 483 tagForChildProtection: -1, 484 // Specify whether you want the ad request to be processed in a way that meets the GDPR for users in the EEA under the age of consent. The following values are available: -1 (default value): uncertain; 0: no; 1: yes. 485 tagForUnderAgeOfPromise: -1, 486 // Maximum ad content rating. W: aged 3 and up; PI: aged 7 and up, under parental guidance; J: teenagers aged 12 and up; A: adults aged 16 or 18 and up. 487 adContentClassification: 'A' 488 }; 489 // Listener for the ad loading status. 490 const adLoaderListener: advertising.AdLoadListener = { 491 // Called when the ad request fails. 492 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 493 hilog.error(0x0000, 'testTag', `Fail to load ad. Code is ${errorCode}, message is ${errorMsg}`); 494 }, 495 // Called when the ad request is successful. 496 onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => { 497 hilog.info(0x0000, 'testTag', 'Succeed in loading ad'); 498 // Save the requested ad content for display. 499 const returnAds = ads; 500 } 501 }; 502 // Create an AdLoader object. 503 const adLoader: advertising.AdLoader = new advertising.AdLoader(context); 504 // Load the ad. 505 hilog.info(0x0000, 'testTag', 'Start to load ad'); 506 adLoader.loadAd(adRequestParams, adOptions, adLoaderListener); 507} 508``` 509 510### loadAdWithMultiSlots 511 512loadAdWithMultiSlots(adParams: AdRequestParams[], adOptions: AdOptions, listener: MultiSlotsAdLoadListener): void 513 514Loads multiple ads. 515 516**Atomic service API**: This API can be used in atomic services since API version 12. 517 518**System capability**: SystemCapability.Advertising.Ads 519 520**Parameters** 521 522| Name | Type | Mandatory| Description | 523|-----------|-------------------------------------------------------|-----|-----------------| 524| adParams | [AdRequestParams](#adrequestparams)[] | Yes | Ad request parameters. | 525| adOptions | [AdOptions](#adoptions) | Yes | Ad configuration. | 526| listener | [MultiSlotsAdLoadListener](#multislotsadloadlistener) | Yes | Ad request callback.| 527 528**Error codes** 529 530For details about the following error codes, see [Ads Service Framework Error Codes](errorcode-ads.md). 531 532| ID| Error Message | 533|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| 534| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 535| 801 | Device not supported. | 536| 21800001 | System internal error. | 537| 21800003 | Failed to load the ad request. | 538 539**Example** 540 541For details about how to obtain the context, see [Context](../../application-models/application-context-stage.md#overview). 542 543```ts 544import { common } from '@kit.AbilityKit'; 545import { advertising } from '@kit.AdsKit'; 546import { hilog } from '@kit.PerformanceAnalysisKit'; 547 548function loadAdWithMultiSlots(context: common.Context): void { 549 const adRequestParamsArray: advertising.AdRequestParams[] = [ 550 { 551 // Ad type. 552 adType: 3, 553 // Ad ID. 554 adId: 'testy63txaom86' 555 }, 556 { 557 // Ad type. 558 adType: 3, 559 // Ad ID. 560 adId: 'testy63txaom86' 561 } 562 ]; 563 const adOptions: advertising.AdOptions = { 564 // Optional custom parameter, which specifies whether to allow ad asset download using mobile data. The options are 0 (no) and 1 (yes). If this parameter is not set, the advertiser's setting will be used. 565 allowMobileTraffic: 0, 566 // Specify whether you want your ad content to be treated as COPPA-compliant. The following values are available: -1 (default value): uncertain; 0: no; 1: yes. 567 tagForChildProtection: -1, 568 // Specify whether you want the ad request to be processed in a way that meets the GDPR for users in the EEA under the age of consent. The following values are available: -1 (default value): uncertain; 0: no; 1: yes. 569 tagForUnderAgeOfPromise: -1, 570 // Maximum ad content rating. W: aged 3 and up; PI: aged 7 and up, under parental guidance; J: teenagers aged 12 and up; A: adults aged 16 or 18 and up. 571 adContentClassification: 'A' 572 }; 573 // Listener for the ad loading status. 574 const multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = { 575 // Called when the ad request fails. 576 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 577 hilog.error(0x0000, 'testTag', `Fail to load multiSlots ad. Code is ${errorCode}, message is ${errorMsg}`); 578 }, 579 // Called when the ad request is successful. 580 onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => { 581 hilog.info(0x0000, 'testTag', 'Succeed in loading multiSlots ad'); 582 // Save the requested ad content for display. 583 const returnAds: Array<advertising.Advertisement> = []; 584 ads.forEach((adsArray) => returnAds.push(...adsArray)); 585 } 586 }; 587 // Create an AdLoader object. 588 const adLoader: advertising.AdLoader = new advertising.AdLoader(context); 589 // Load the ad. 590 hilog.info(0x0000, 'testTag', 'Start to load multiSlots ad'); 591 adLoader.loadAdWithMultiSlots(adRequestParamsArray, adOptions, multiSlotsAdLoaderListener); 592} 593``` 594 595## AdLoadListener 596 597Enumerates the callbacks used for the request for loading an ad. 598 599**Atomic service API**: This API can be used in atomic services since API version 12. 600 601**System capability**: SystemCapability.Advertising.Ads 602 603### onAdLoadFailure 604 605onAdLoadFailure(errorCode: number, errorMsg: string): void 606 607Called when an ad request fails. 608 609**Atomic service API**: This API can be used in atomic services since API version 12. 610 611**System capability**: SystemCapability.Advertising.Ads 612 613**Parameters** 614 615| Name | Type | Mandatory| Description | 616|-----------|--------|-----|-----------------------| 617| errorCode | number | Yes | Result code indicating the ad request failure. | 618| errorMsg | string | Yes | Error message about the ad request failure.| 619 620### onAdLoadSuccess 621 622onAdLoadSuccess(ads: Array<Advertisement>): void 623 624Called when an ad request is successful. 625 626**Atomic service API**: This API can be used in atomic services since API version 12. 627 628**System capability**: SystemCapability.Advertising.Ads 629 630**Parameters** 631 632| Name| Type | Mandatory| Description | 633|--------|----------------------------------------------|-----|---------| 634| ads | Array<[Advertisement](#advertisement)> | Yes | Ad data.| 635 636**Example** 637 638```ts 639import { advertising } from '@kit.AdsKit'; 640 641const adLoaderListener: advertising.AdLoadListener = { 642 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 643 }, 644 onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => { 645 } 646} 647``` 648 649## MultiSlotsAdLoadListener 650 651Enumerates the callbacks used for the request for loading multiple ads. 652 653**Atomic service API**: This API can be used in atomic services since API version 12. 654 655**System capability**: SystemCapability.Advertising.Ads 656 657### onAdLoadFailure 658 659onAdLoadFailure(errorCode: number, errorMsg: string): void 660 661Called when a request for loading multiple ads fails. 662 663**Atomic service API**: This API can be used in atomic services since API version 12. 664 665**System capability**: SystemCapability.Advertising.Ads 666 667**Parameters** 668 669| Name | Type | Mandatory| Description | 670|-----------|--------|-----|-----------------------| 671| errorCode | number | Yes | Result code indicating the ad request failure. | 672| errorMsg | string | Yes | Error message about the ad request failure.| 673 674### onAdLoadSuccess 675 676onAdLoadSuccess(adsMap: Map<string, Array<Advertisement>>): void 677 678Called when a request for loading multiple ads is successful. 679 680**Atomic service API**: This API can be used in atomic services since API version 12. 681 682**System capability**: SystemCapability.Advertising.Ads 683 684**Parameters** 685 686| Name| Type | Mandatory| Description | 687|--------|-----------------------------------------------------------------|-----|---------| 688| adsMap | Map<string, Array<[Advertisement](#advertisement)>> | Yes | Ad data.| 689 690**Example** 691 692```ts 693import { advertising } from '@kit.AdsKit'; 694 695const multiSlotsAdLoadListener: advertising.MultiSlotsAdLoadListener = { 696 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 697 }, 698 onAdLoadSuccess: (adsMap: Map<string, Array<advertising.Advertisement>>) => { 699 } 700} 701``` 702 703## AdInteractionListener 704 705Defines the ad status change callback. 706 707**Atomic service API**: This API can be used in atomic services since API version 12. 708 709**System capability**: SystemCapability.Advertising.Ads 710 711### onStatusChanged 712 713onStatusChanged(status: string, ad: Advertisement, data: string) 714 715Called when the ad display status changes. 716 717**Atomic service API**: This API can be used in atomic services since API version 12. 718 719**System capability**: SystemCapability.Advertising.Ads 720 721**Parameters** 722 723| Name| Type | Mandatory| Description | 724|--------|---------------------------------|-----|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 725| status | string | Yes | **status**: ad display status, which can be<br>**onAdOpen**, **onAdClose**, **onAdClick**, **onVideoPlayBegin**, **onVideoPlayEnd**, **onAdLoad**, **onAdFail**, **onMediaProgress**, **onMediaStart**, **onMediaPause**, **onMediaStop**, **onMediaComplete**, **onMediaError**, **onLandscape**, **onPortrait**, **onAdReward**, **onMediaCountDown**, or **onBackClicked**.| 726| ad | [Advertisement](#advertisement) | Yes | Content of the ad. | 727| data | string | Yes | Extended information. | 728 729**Example** 730 731```ts 732import { advertising } from '@kit.AdsKit'; 733 734const adInteractionListener: advertising.AdInteractionListener = { 735 onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => { 736 737 } 738} 739``` 740 741## AdOptions 742 743Defines the ad configuration. 744 745**Atomic service API**: This API can be used in atomic services since API version 12. 746 747**System capability**: SystemCapability.Advertising.Ads 748 749| Name | Type | Read-Only| Optional| Description | 750|-------------------------|------------------------------------------|-----|-----|--------------------------------------------------------------------------------------------------------------------| 751| tagForChildProtection | number | No | Yes | Tag for child protection, which specifies whether you want the ad content to be treated as COPPA-compliant.<br>- **-1**: Uncertain.<br>- **0**: No. You do not want the ad content to be treated as COPPA-compliant.<br>- **1**: Yes. You want the ad content to be treated as COPPA-compliant.| 752| adContentClassification | string | No | Yes | Maximum ad content rating.<br>- **W**: ages 3+, all audiences.<br>- **PI**: ages 7+, audiences under parental instruction.<br>- **J**: ages 12+, teenagers.<br>- **A**: ages 16+/18+, adults. | 753| nonPersonalizedAd | number | No | Yes | Whether to request only non-personalized ads.<br>- **0**: request for personalized and non-personalized ads.<br>- **1**: request for only non-personalized ads. | 754| [key: string] | number \| boolean \| string \| undefined | No | Yes | Custom parameters. | 755 756## AdRequestParams 757 758Defines the ad request parameters. 759 760**Atomic service API**: This API can be used in atomic services since API version 12. 761 762**System capability**: SystemCapability.Advertising.Ads 763 764| Name | Type | Read-Only| Optional| Description | 765|-----------------|------------------------------------------|-----|-----|-----------------------------------------------------------------------------------------------------------------------------| 766| adId | string | No | No | Ad ID.<br>- This parameter is optional for **getAdRequestBody**. | 767| adType | number | No | Yes | Type of the requested ad.<br>- **1**: splash ad.<br>- **3**: native ad.<br>- **7**: rewarded ad.<br>- **8**: banner ad.<br>- **12**: interstitial ad.<br>- **60**: roll ad.| 768| adCount | number | No | Yes | Number of ads requested. | 769| adWidth | number | No | Yes | Expected creative width of ads requested, in vp. | 770| adHeight | number | No | Yes | Expected creative height of ads requested, in vp. | 771| adSearchKeyword | string | No | Yes | Ad keyword. | 772| [key: string] | number \| boolean \| string \| undefined | No | Yes | Custom parameters.<br>- **oaid**: A string indicates the Open Anonymous Device Identifier (OAID), which is used to precisely push ads. | 773 774## AdDisplayOptions 775 776Defines the ad display parameters. 777 778**Atomic service API**: This API can be used in atomic services since API version 12. 779 780**System capability**: SystemCapability.Advertising.Ads 781 782| Name | Type | Read-Only| Optional| Description | 783|-----------------------|------------------------------------------|-----|-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 784| customData | string | No | Yes | Custom media data. | 785| userId | string | No | Yes | User ID. | 786| useMobileDataReminder | boolean | No | Yes | Whether to display a dialog box to notify users when they use mobile data to play videos or download applications.<br>- **true**: A dialog box is displayed.<br>- **false**: No dialog box is displayed. | 787| mute | boolean | No | Yes | Whether to mute the ad video.<br>- **true**: The ad video is muted.<br>- **false**: The ad video is not muted. | 788| audioFocusType | number | No | Yes | Type of the scenario where the audio focus is obtained during video playback.<br>- **0**: The focus is obtained when the video is played in mute or non-mute mode.<br>- **1**: The focus is not obtained when the video is played in mute mode.<br>- **2**: The focus is not obtained when the video is played in mute or non-mute mode. | 789| [key: string] | number \| boolean \| string \| undefined | No | Yes | Custom parameters.<br>- **refreshTime**: The value is of the number type, in ms. The value is in the range [30000, 120000]. This parameter is optional for the AutoAdComponent module and specifies the interval at which the ads rotate. If this parameter is set, ads are rotated at the interval specified by this parameter. Otherwise, ads are not rotated and only the first ad in the ad response is displayed.| 790 791## Advertisement 792 793type Advertisement = _Advertisement 794 795Defines the requested ad content. 796 797**Atomic service API**: This API can be used in atomic services since API version 12. 798 799**System capability**: SystemCapability.Advertising.Ads 800 801| Type | Description | 802|--------------------------------------------------------------|----------------------| 803| [_Advertisement](js-apis-inner-advertising-advertisement.md) | Advertisement object.| 804 805 <!--no_check-->