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