1# @ohos.advertising (广告服务框架) 2 3本模块提供广告操作能力，包括请求广告、展示广告。 4 5> **说明：** 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 { advertising } from '@kit.AdsKit'; 46import { hilog } from '@kit.PerformanceAnalysisKit'; 47import { common } from '@kit.AbilityKit'; 48 49@Entry 50@Component 51export struct ShowAd { 52 private context: common.UIAbilityContext = getContext(this) 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('展示广告') 64 .onClick(() => { 65 try { 66 // 调用全屏广告展示接口 67 advertising.showAd(this.ad, this.adDisplayOptions, this.context); 68 } catch (err) { 69 hilog.error(0x0000, 'testTag', '%{public}s', `show ad catch error: ${err.code} ${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 { hilog } from '@kit.PerformanceAnalysisKit'; 114import { BusinessError } from '@kit.BasicServicesKit'; 115import { advertising } from '@kit.AdsKit'; 116import { Prompt } from '@kit.ArkUI'; 117 118function getAdRequestBody(): void { 119 let adReqParamsListForRequest: Array<advertising.AdRequestParams> = []; 120 const adReqParams: Record<string, Object> = { 121 'adId': 'testu7m3hc4gvm', 122 'adType': 3, 123 'adCount': 2, 124 'adWidth': 100, 125 'adHeight': 100 126 }; 127 128 adReqParamsListForRequest.push(adReqParams as advertising.AdRequestParams); 129 const adOption: Record<string, Object> = { 130 // 设置广告内容分级上限 w:3+,所有受众 PI：7+，家长指导 J：12+，青少年 A：16+/18+,成人受众 131 'adContentClassification': 'A', 132 // 设置是否只请求非个性化广告 0：请求个性化广告与非个性化广告 1：只请求非个性化广告。不填以业务逻辑为准 133 'nonPersonalizedAd': 0, 134 // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容，: -1默认值，不确定 0不希望 1希望 135 'tagForChildProtection': 1, 136 // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求 -1默认值,不确定 0不希望 1希望 137 'tagForUnderAgeOfPromise': -1 138 }; 139 advertising.getAdRequestBody(adReqParamsListForRequest, adOption as advertising.AdOptions).then((data) => { 140 hilog.info(0x0000, 'testTag', '%{public}s', `succeeded in getting AdRequestBody by promise: ${data}`); 141 Prompt.showToast({ 142 message: data, 143 duration: 1000 144 }); 145 }).catch((error: BusinessError) => { 146 hilog.error(0x0000, 'testTag', '%{public}s', 147 `getAdRequestBody failed, code: ${error.code}, message: ${error.message}`); 148 Prompt.showToast({ 149 message: error.code.toString() + ',' + error.message, 150 duration: 1000 151 }); 152 }) 153} 154``` 155 156## advertising.parseAdResponse<sup>12+</sup> 157 158parseAdResponse(adResponse: string, listener: MultiSlotsAdLoadListener, context: common.UIAbilityContext): void 159 160解析并处理广告响应体（该接口仅对部分系统预置应用开放）。 161 162**系统能力：** SystemCapability.Advertising.Ads 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167|------------|----------------------------------------------------------------------------------------------|----|------------------| 168| adResponse | string | 是 | 广告请求参数。 | 169| listener | [MultiSlotsAdLoadListener](#multislotsadloadlistener) | 是 | 请求广告回调监听。 | 170| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | 是 | UIAbility的上下文环境。 | 171 172**错误码：** 173 174以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 175 176| 错误码ID | 错误信息 | 177|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------| 178| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 179| 801 | Device not supported. | 180| 21800001 | System internal error. | 181| 21800005 | Failed to parse the ad response. | 182 183**示例：** 184 185其中context的获取方式参见[UIAbilityContext的获取方式](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 186 187```ts 188import { common } from '@kit.AbilityKit'; 189import { advertising } from '@kit.AdsKit'; 190import { hilog } from '@kit.PerformanceAnalysisKit'; 191 192function parseAdResponse(adResponse: string, context: common.UIAbilityContext): void { 193 // 广告解析处理回调监听 194 const multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = { 195 // 广告解析处理失败回调 196 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 197 hilog.error(0x0000, 'testTag', '%{public}s', 198 `request multi ads errorCode is: ${errorCode}, errorMsg is: ${errorMsg}`); 199 }, 200 // 广告解析处理成功回调 201 onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => { 202 hilog.info(0x0000, 'testTag', '%{public}s', 'succeeded in requesting multi ads!'); 203 // 保存解析处理完成的广告内容为数组用于展示 204 let returnAds: Array<advertising.Advertisement> = []; 205 ads.forEach((adsArray) => returnAds.push(...adsArray)); 206 } 207 }; 208 // 调用响应体解析接口 209 hilog.info(0x0000, 'testTag', '%{public}s', 'parse ad response!'); 210 advertising.parseAdResponse(adResponse, multiSlotsAdLoaderListener, context); 211} 212``` 213 214## advertising.registerWebAdInterface<sup>12+</sup> 215 216registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext): void 217 218注入广告JavaScript对象到Web组件中（该接口仅对部分系统预置应用开放）。 219 220**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 221 222**系统能力：** SystemCapability.Advertising.Ads 223 224**参数：** 225 226| 参数名 | 类型 | 必填 | 说明 | 227|------------|----------------------------------------------------------------------------------------------|----|------------------| 228| controller | web_webview.[WebviewController](../apis-arkweb/js-apis-webview.md#webviewcontroller) | 是 | Web组件控制器。 | 229| context | common.[UIAbilityContext](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) | 是 | UIAbility的上下文环境。 | 230 231**错误码：** 232 233以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 234 235| 错误码ID | 错误信息 | 236|----------|---------------------------------------------------------------------------------------| 237| 401 | Invalid input parameter. Possible causes: 1.Mandatory parameters are left unspecified | 238| 21800001 | System internal error. | 239 240**示例：** 241 242```ts 243import { webview } from '@kit.ArkWeb'; 244import { common } from '@kit.AbilityKit'; 245import { advertising } from '@kit.AdsKit'; 246import { hilog } from '@kit.PerformanceAnalysisKit'; 247 248@Entry 249@Component 250struct Index { 251 private webController: webview.WebviewController = new webview.WebviewController(); 252 private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext; 253 254 build() { 255 Column() { 256 Button('广告对象注入Web') 257 .onClick(() => { 258 try { 259 advertising.registerWebAdInterface(this.webController, this.context); 260 } catch (err) { 261 hilog.error(0x0000, 'testTag', '%{public}s', 262 `register web ad interface error: ${err.code}, ${err.message}`); 263 } 264 }) 265 266 Web({ 267 src: 'www.example.com', 268 controller: this.webController, 269 }) 270 .width("100%") 271 .height("100%") 272 } 273 } 274} 275``` 276 277## AdLoader 278 279提供加载广告的功能。 280 281**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 282 283**系统能力：** SystemCapability.Advertising.Ads 284 285### constructor 286 287constructor(context: common.Context) 288 289构造函数。 290 291**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 292 293**系统能力：** SystemCapability.Advertising.Ads 294 295**参数：** 296 297| 参数名 | 类型 | 必填 | 说明 | 298|---------|----------------------------------------------------------------------------|----|----------------------------| 299| context | common.[Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | ability或application的上下文环境。 | 300 301**示例：** 302 303其中context的获取方式参见[各类Context的获取方式](../../application-models/application-context-stage.md#概述)。 304 305```ts 306import { advertising } from '@kit.AdsKit'; 307import { common } from '@kit.AbilityKit'; 308 309function createConstructor(context: common.Context): void { 310 const load: advertising.AdLoader = new advertising.AdLoader(context); 311} 312``` 313 314### loadAd 315 316loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void 317 318请求单广告位广告。 319 320**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 321 322**系统能力：** SystemCapability.Advertising.Ads 323 324**参数：** 325 326| 参数名 | 类型 | 必填 | 说明 | 327|-----------|-------------------------------------|----|-----------| 328| adParam | [AdRequestParams](#adrequestparams) | 是 | 广告请求参数。 | 329| adOptions | [AdOptions](#adoptions) | 是 | 广告配置。 | 330| listener | [AdLoadListener](#adloadlistener) | 是 | 请求广告回调监听。 | 331 332**错误码：** 333 334以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 335 336| 错误码ID | 错误信息 | 337|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| 338| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 339| 801 | Device not supported. | 340| 21800001 | System internal error. | 341| 21800003 | Failed to load the ad request. | 342 343**示例：** 344 345其中context的获取方式参见[各类Context的获取方式](../../application-models/application-context-stage.md#概述)。 346 347```ts 348import { advertising } from '@kit.AdsKit'; 349import { common } from '@kit.AbilityKit'; 350import { hilog } from '@kit.PerformanceAnalysisKit'; 351 352function requestAd(context: common.Context): void { 353 const adRequestParam: advertising.AdRequestParams = { 354 // 广告类型 355 adType: 3, 356 // 测试广告位ID 357 adId: "testy63txaom86" 358 }; 359 const adOptions: advertising.AdOptions = { 360 // 可选自定义参数，设置是否允许使用流量下载广告素材 0：不允许，1：允许 361 allowMobileTraffic: 0, 362 // 设置广告内容分级上限： w:3+,所有受众 PI：7+，家长指导 J：12+，青少年 A：16+/18+,成人受众 363 adContentClassification: 'A', 364 // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望 365 tagForChildProtection: -1, 366 // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求: -1默认值,不确定 0不希望 1希望 367 tagForUnderAgeOfPromise: -1 368 } 369 // 广告请求回调监听 370 const adLoaderListener: advertising.AdLoadListener = { 371 // 广告请求失败回调 372 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 373 hilog.error(0x0000, 'testTag', '%{public}s', 374 `request single ad errorCode is: ${errorCode}, errorMsg is: ${errorMsg}`); 375 }, 376 // 广告请求成功回调 377 onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => { 378 hilog.info(0x0000, 'testTag', '%{public}s', 'succeed in requesting single ad!'); 379 // 保存请求到的广告内容用于展示 380 const returnAds = ads; 381 } 382 }; 383 // 创建AdLoader广告对象 384 const load: advertising.AdLoader = new advertising.AdLoader(context); 385 // 调用广告请求接口 386 hilog.info(0x0000, 'testTag', '%{public}s', 'request single ad!'); 387 load.loadAd(adRequestParam, adOptions, adLoaderListener); 388} 389``` 390 391### loadAdWithMultiSlots 392 393loadAdWithMultiSlots(adParams: AdRequestParams[], adOptions: AdOptions, listener: MultiSlotsAdLoadListener): void 394 395请求多广告位广告。 396 397**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 398 399**系统能力：** SystemCapability.Advertising.Ads 400 401**参数：** 402 403| 参数名 | 类型 | 必填 | 说明 | 404|-----------|-------------------------------------------------------|----|-----------| 405| adParams | [AdRequestParams](#adrequestparams)[] | 是 | 广告请求参数。 | 406| adOptions | [AdOptions](#adoptions) | 是 | 广告配置。 | 407| listener | [MultiSlotsAdLoadListener](#multislotsadloadlistener) | 是 | 请求广告回调监听。 | 408 409**错误码：** 410 411以下错误码的详细介绍请参见[广告服务框架错误码参考](errorcode-ads.md)。 412 413| 错误码ID | 错误信息 | 414|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| 415| 401 | Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 416| 801 | Device not supported. | 417| 21800001 | System internal error. | 418| 21800003 | Failed to load the ad request. | 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'; 427import { hilog } from '@kit.PerformanceAnalysisKit'; 428 429function requestMultiAd(context: common.Context): void { 430 const adRequestParamArray: advertising.AdRequestParams[] = [{ 431 // 广告类型 432 adType: 3, 433 // 测试广告位ID 434 adId: "testy63txaom86" 435 } as advertising.AdRequestParams, 436 { 437 // 广告类型 438 adType: 3, 439 // 测试广告位ID 440 adId: "testy63txaom86" 441 } as advertising.AdRequestParams 442 ]; 443 const adOptions: advertising.AdOptions = { 444 // 可选自定义参数，设置是否允许使用流量下载广告素材 0：不允许，1：允许 445 allowMobileTraffic: 0, 446 // 设置广告内容分级上限： w:3+,所有受众 PI：7+，家长指导 J：12+，青少年 A：16+/18+,成人受众 447 adContentClassification: 'A', 448 // 是否希望根据 COPPA 的规定将您的内容视为面向儿童的内容: -1默认值，不确定 0不希望 1希望 449 tagForChildProtection: -1, 450 // 是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求 -1默认值,不确定 0不希望 1希望 451 tagForUnderAgeOfPromise: -1 452 }; 453 // 广告请求回调监听 454 const multiSlotsAdLoaderListener: advertising.MultiSlotsAdLoadListener = { 455 // 广告请求失败回调 456 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 457 hilog.error(0x0000, 'testTag', '%{public}s', 458 `request multi ads errorCode is: ${errorCode}, errorMsg is: ${errorMsg}`); 459 }, 460 // 广告请求成功回调 461 onAdLoadSuccess: (ads: Map<string, Array<advertising.Advertisement>>) => { 462 hilog.info(0x0000, 'testTag', '%{public}s', 'succeed in requesting multi ads!'); 463 // 保存请求到的广告内容为数组用于展示 464 let returnAds: Array<advertising.Advertisement> = []; 465 ads.forEach((adsArray) => returnAds.push(...adsArray)); 466 } 467 }; 468 // 创建AdLoader广告对象 469 const load: advertising.AdLoader = new advertising.AdLoader(context); 470 // 调用广告请求接口 471 hilog.info(0x0000, 'testTag', '%{public}s', 'request multi ads!'); 472 load.loadAdWithMultiSlots(adRequestParamArray, adOptions, multiSlotsAdLoaderListener); 473} 474``` 475 476## AdLoadListener 477 478单广告位广告请求回调。 479 480**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 481 482**系统能力：** SystemCapability.Advertising.Ads 483 484### onAdLoadFailure 485 486onAdLoadFailure(errorCode: number, errorMsg: string): void 487 488广告请求失败回调。 489 490**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 491 492**系统能力：** SystemCapability.Advertising.Ads 493 494**参数：** 495 496| 参数名 | 类型 | 必填 | 说明 | 497|-----------|--------|----|--------------| 498| errorCode | number | 是 | 广告请求失败的错误码。 | 499| errorMsg | string | 是 | 广告请求失败的错误信息。 | 500 501### onAdLoadSuccess 502 503onAdLoadSuccess(ads: Array<Advertisement>): void 504 505广告请求成功后回调。 506 507**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 508 509**系统能力：** SystemCapability.Advertising.Ads 510 511**参数：** 512 513| 参数名 | 类型 | 必填 | 说明 | 514|-----|----------------------------------------------|----|-------| 515| ads | Array<[Advertisement](#advertisement)> | 是 | 广告数据。 | 516 517**示例：** 518 519```ts 520import { advertising } from '@kit.AdsKit'; 521 522let adLoaderListener: advertising.AdLoadListener = { 523 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 524 }, 525 onAdLoadSuccess: (ads: Array<advertising.Advertisement>) => { 526 } 527} 528``` 529 530## MultiSlotsAdLoadListener 531 532多广告位广告请求回调。 533 534**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 535 536**系统能力：** SystemCapability.Advertising.Ads 537 538### onAdLoadFailure 539 540onAdLoadFailure(errorCode: number, errorMsg: string): void 541 542多广告位广告请求失败回调。 543 544**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 545 546**系统能力：** SystemCapability.Advertising.Ads 547 548**参数：** 549 550| 参数名 | 类型 | 必填 | 说明 | 551|-----------|--------|----|--------------| 552| errorCode | number | 是 | 广告请求失败的错误码。 | 553| errorMsg | string | 是 | 广告请求失败的错误信息。 | 554 555### onAdLoadSuccess 556 557onAdLoadSuccess(adsMap: Map<string, Array<Advertisement>>): void 558 559多广告位广告请求成功后回调。 560 561**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 562 563**系统能力：** SystemCapability.Advertising.Ads 564 565**参数：** 566 567| 参数名 | 类型 | 必填 | 说明 | 568|--------|-----------------------------------------------------------------|----|-------| 569| adsMap | Map<string, Array<[Advertisement](#advertisement)>> | 是 | 广告数据。 | 570 571**示例：** 572 573```ts 574import { advertising } from '@kit.AdsKit'; 575 576let adLoaderListener: advertising.MultiSlotsAdLoadListener = { 577 onAdLoadFailure: (errorCode: number, errorMsg: string) => { 578 }, 579 onAdLoadSuccess: (adsMap: Map<string, Array<advertising.Advertisement>>) => { 580 } 581} 582``` 583 584## AdInteractionListener 585 586广告状态变化回调。 587 588**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 589 590**系统能力：** SystemCapability.Advertising.Ads 591 592### onStatusChanged 593 594onStatusChanged(status: string, ad: Advertisement, data: string) 595 596广告状态回调。 597 598**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 599 600**系统能力：** SystemCapability.Advertising.Ads 601 602**参数：** 603 604| 参数名 | 类型 | 必填 | 说明 | 605|--------|---------------------------------|----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 606| status | string | 是 | status：广告展示状态，取值<br/>onAdOpen（打开广告回调）、onAdClose（关闭广告回调）、onAdClick（点击广告回调）、onVideoPlayBegin（广告视频开始播放回调）、onVideoPlayEnd（广告视频播放结束回调）、onAdLoad（广告加载成功回调）、onAdFail（广告加载失败回调）、onMediaProgress（广告播放进度回调）、onMediaStart（广告开始播放回调）、onMediaPause（广告暂停播放回调）、onMediaStop（广告停止播放回调）、onMediaComplete（广告播放完成回调）、onMediaError（广告播放失败回调）、onLandscape（竖屏状态下点击全屏按钮回调）、onPortrait（全屏状态下点击返回按钮回调）、onAdReward (广告获得奖励回调) 、onMediaCountDown (广告倒计时回调) 、onBackClicked (返回点击广告回调)。 | 607| ad | [Advertisement](#advertisement) | 是 | 发生状态变化的广告内容。 | 608| data | string | 是 | 扩展信息。 | 609 610**示例：** 611 612```ts 613import { advertising } from '@kit.AdsKit'; 614 615let adInteractionListener: advertising.AdInteractionListener = { 616 onStatusChanged: (status: string, ad: advertising.Advertisement, data: string) => { 617 618 } 619} 620``` 621 622## AdOptions 623 624广告配置参数。 625 626**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 627 628**系统能力：** SystemCapability.Advertising.Ads 629 630| 名称 | 类型 | 只读 | 可选 | 说明 | 631|-------------------------|------------------------------------------|----|----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 632| tagForChildProtection | number | 否 | 是 | 设置儿童保护标签，否希望根据 COPPA 的规定将您的内容视为面向儿童的内容。<br/>- -1：默认值，不确定。<br/>- 0：不希望。<br/>- 1：希望。<br/>默认为-1。 | 633| adContentClassification | string | 否 | 是 | 设置广告内容分级上限。<br/>- W：3+,所有受众。<br/>- PI：7+，家长指导。<br/>- J：12+，青少年。<br/>- A：16+/18+,成人受众。<br/>不填以业务逻辑为准。 | 634| nonPersonalizedAd | number | 否 | 是 | 设置是否只请求非个性化广告。<br/>- 0：请求个性化广告与非个性化广告。<br/>- 1：只请求非个性化广告。<br/>不填以业务逻辑为准。 | 635| [key: string] | number \| boolean \| string \| undefined | 否 | 是 | 自定义参数。<br/> - totalDuration：类型number，单位：s。贴片广告必填自定义参数，用于设置贴片广告展示时长。<br/> - placementAdCountDownDesc：类型string。贴片广告可选自定义参数，用于设置贴片广告倒计时文案，该参数需要使用encodeURI()方法编码。填写了该参数，则展示倒计时文案，否则只展示倒计时。<br/> - allowMobileTraffic：类型number。可选自定义参数，设置是否允许使用流量下载广告素材。0：不允许，1：允许，不设置以广告主设置为准。 <br/> - tagForUnderAgeOfPromise：类型number。非必填参数，用于设置未成年保护标签，表示是否希望按适合未达到法定承诺年龄的欧洲经济区 (EEA) 用户的方式处理该广告请求。-1：默认值，不确定 0：不希望 1：希望 | 636 637## AdRequestParams 638 639广告请求参数。 640 641**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 642 643**系统能力：** SystemCapability.Advertising.Ads 644 645| 名称 | 类型 | 只读 | 可选 | 说明 | 646|-----------------|------------------------------------------|----|----|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 647| adId | string | 否 | 否 | 广告位ID。<br/>- getAdRequestBody接口可以不传该参数。 | 648| adType | number | 否 | 是 | 请求的广告类型。<br/>- 1：开屏广告。<br/>- 3：原生广告。<br/>- 7：激励广告。<br/>- 8：banner广告。<br/>- 12：插屏广告。<br/>- 60：贴片广告。<br/>不填默认为原生广告类型。 | 649| adCount | number | 否 | 是 | 请求的广告数量。不填以业务逻辑为准。 | 650| adWidth | number | 否 | 是 | 请求广告时期望的创意宽度，单位vp（横幅广告必填）。不填以业务逻辑为准。 | 651| adHeight | number | 否 | 是 | 请求广告时期望的创意高度，单位vp（横幅广告必填）。不填以业务逻辑为准。 | 652| adSearchKeyword | string | 否 | 是 | 广告关键字。不填默认""。 | 653| [key: string] | number \| boolean \| string \| undefined | 否 | 是 | 自定义参数。<br/>- isPreload：类型boolean，请求贴片广告时，用于区分普通在线请求和素材预加载请求。true：素材预加载请求，false：普通在线请求。默认值false。仅对贴片广告生效，其他广告请求不解析该参数。<br/>- enableDirectReturnVideoAd：类型boolean，原生广告自定义扩展参数，是否直接返回广告，不用等待所有广告素材下载完成。true：不等待广告素材下载完成，展示广告时在线加载素材；false：等待广告素材下载完成，展示广告时从本地缓存中加载素材。如果不填以云侧配置为准。仅对原生广告生效，其他广告请求不解析该参数。<br/>- oaid: 类型string，开放匿名设备标识符，用于精准推送广告。不填无法获取到个性化广告。默认值为""。<br/>- tmax：类型number，交易的最大超时时间（包含网络延迟）单位毫秒。<br/>- cur：类型string，竞价请求支持的币种，支持传多个，用英文逗号分隔。当前支持五种货币：CNY、USD、EUR、GBP、JPY，不填则默认是CNY。<br/>- bidFloor：类型number，实时竞价广告位的底价。<br/>- bidFloorCur：类型string，广告位底价使用的币种。如果bidFloor非空，则bidFloorCur也非空。当前只支持五种货币中的一种：CNY、USD、EUR、GBP、JPY，不填则默认是CNY。<br/>- bpkgName：类型string，广告位禁投的APP包名，支持传多个，用英文逗号分隔。 | 654 655## AdDisplayOptions 656 657广告展示参数。 658 659**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 660 661**系统能力：** SystemCapability.Advertising.Ads 662 663| 名称 | 类型 | 只读 | 可选 | 说明 | 664|-----------------------|------------------------------------------|----|----|--------------------------------------------------------------------------------------------------------------------------------------------------------| 665| customData | string | 否 | 是 | 媒体自定义数据。用于服务端通知媒体服务器某位用户因为与激励视频广告互动而应予以奖励，从而规避欺骗的行为（不填则不会通知）。 | 666| userId | string | 否 | 是 | 媒体自定义用户id。用于服务端通知媒体服务器某位用户因为与激励视频广告互动而应予以奖励，从而规避欺骗的行为（不填则不会通知）。 | 667| useMobileDataReminder | boolean | 否 | 是 | 使用移动数据播放视频或下载应用时是否弹框通知用户。<br/>- true：弹框通知。<br/>- false：不弹框通知。<br/>该参数依赖流量弹窗功能，当前不支持完整功能的使用，暂不确定默认值。 | 668| mute | boolean | 否 | 是 | 广告视频播放是否静音。<br/>- true：静音播放。<br/>- false：非静音播放。<br/>不填以业务逻辑为准。 | 669| audioFocusType | number | 否 | 是 | 视频播放过程中获得音频焦点的场景类型。<br/>- 0：视频播放静音、非静音时都获取焦点。<br/>- 1：视频静音播放时不获取焦点。<br/>- 2：视频播放静音、非静音时都不获取焦点。<br/>该接口依赖的相关功能当前不支持使用，暂不确定默认值。 | 670| [key: string] | number \| boolean \| string \| undefined | 否 | 是 | 自定义参数。<br/>- refreshTime：类型number，单位：ms，取值范围[30000, 120000]。AutoAdComponent组件可选自定义参数，用于控制广告的轮播时间间隔。填写了该参数，则广告按照参数配置的时间间隔轮播，否则广告不会轮播，只会展示广告响应中的第一个广告内容。 | 671 672## Advertisement 673 674type Advertisement = _Advertisement 675 676请求的广告内容。 677 678**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 679 680**系统能力：** SystemCapability.Advertising.Ads 681 682| 类型 | 说明 | 683|--------------------------------------------------------------|-------------------| 684| [_Advertisement](js-apis-inner-advertising-advertisement.md) | 表示Advertisement对象 |