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