1/* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file Provides the capability to load and display advertisements 18 * @kit AdsKit 19 */ 20import type web_webview from './@ohos.web.webview'; 21import type common from './@ohos.app.ability.common'; 22import type { Advertisement as _Advertisement } from './advertising/advertisement'; 23 24/** 25 * Provides the capability to load and display advertisements. 26 * @namespace advertising 27 * @syscap SystemCapability.Advertising.Ads 28 * @since 11 29 */ 30/** 31 * Provides the capability to load and display advertisements. 32 * @namespace advertising 33 * @syscap SystemCapability.Advertising.Ads 34 * @atomicservice 35 * @since 12 36 */ 37declare namespace advertising { 38 /** 39 * Indicates the advertisement data model. 40 * @syscap SystemCapability.Advertising.Ads 41 * @since 11 42 */ 43 /** 44 * Indicates the advertisement data model. 45 * @syscap SystemCapability.Advertising.Ads 46 * @atomicservice 47 * @since 12 48 */ 49 export type Advertisement = _Advertisement; 50 51 /** 52 * The parameters in the request for loading one or more advertisements. 53 * @typedef AdRequestParams 54 * @syscap SystemCapability.Advertising.Ads 55 * @since 11 56 */ 57 /** 58 * The parameters in the request for loading one or more advertisements. 59 * @typedef AdRequestParams 60 * @syscap SystemCapability.Advertising.Ads 61 * @atomicservice 62 * @since 12 63 */ 64 export interface AdRequestParams { 65 /** 66 * The advertisement slot id. 67 * @type { string } 68 * @syscap SystemCapability.Advertising.Ads 69 * @since 11 70 */ 71 /** 72 * The advertisement slot id. 73 * @type { string } 74 * @syscap SystemCapability.Advertising.Ads 75 * @atomicservice 76 * @since 12 77 */ 78 adId: string; 79 80 /** 81 * The advertisement type of request. 82 * @type { ?number } 83 * @syscap SystemCapability.Advertising.Ads 84 * @since 11 85 */ 86 /** 87 * The advertisement type of request. 88 * @type { ?number } 89 * @syscap SystemCapability.Advertising.Ads 90 * @atomicservice 91 * @since 12 92 */ 93 adType?: number; 94 95 /** 96 * The advertisement quantity of request. 97 * @type { ?number } 98 * @syscap SystemCapability.Advertising.Ads 99 * @since 11 100 */ 101 /** 102 * The advertisement quantity of request. 103 * @type { ?number } 104 * @syscap SystemCapability.Advertising.Ads 105 * @atomicservice 106 * @since 12 107 */ 108 adCount?: number; 109 110 /** 111 * The advertisement view size width that expects. 112 * @type { ?number } 113 * @syscap SystemCapability.Advertising.Ads 114 * @since 11 115 */ 116 /** 117 * The advertisement view size width that expects. 118 * @type { ?number } 119 * @syscap SystemCapability.Advertising.Ads 120 * @atomicservice 121 * @since 12 122 */ 123 adWidth?: number; 124 125 /** 126 * The advertisement view size height that expects. 127 * @type { ?number } 128 * @syscap SystemCapability.Advertising.Ads 129 * @since 11 130 */ 131 /** 132 * The advertisement view size height that expects. 133 * @type { ?number } 134 * @syscap SystemCapability.Advertising.Ads 135 * @atomicservice 136 * @since 12 137 */ 138 adHeight?: number; 139 140 /** 141 * The advertisement search keyword. 142 * @type { ?string } 143 * @syscap SystemCapability.Advertising.Ads 144 * @since 11 145 */ 146 /** 147 * The advertisement search keyword. 148 * @type { ?string } 149 * @syscap SystemCapability.Advertising.Ads 150 * @atomicservice 151 * @since 12 152 */ 153 adSearchKeyword?: string; 154 155 /** 156 * The extended attributes for request parameters. 157 * @type { number | boolean | string | undefined } 158 * @syscap SystemCapability.Advertising.Ads 159 * @since 11 160 */ 161 /** 162 * The extended attributes for request parameters. 163 * @type { number | boolean | string | undefined } 164 * @syscap SystemCapability.Advertising.Ads 165 * @atomicservice 166 * @since 12 167 */ 168 [key: string]: number | boolean | string | undefined; 169 } 170 171 /** 172 * The ad options of loading ads. 173 * @typedef AdOptions 174 * @syscap SystemCapability.Advertising.Ads 175 * @since 11 176 */ 177 /** 178 * The ad options of loading ads. 179 * @typedef AdOptions 180 * @syscap SystemCapability.Advertising.Ads 181 * @atomicservice 182 * @since 12 183 */ 184 export interface AdOptions { 185 /** 186 * The tags for children's content. 187 * @type { ?number } 188 * @syscap SystemCapability.Advertising.Ads 189 * @since 11 190 */ 191 /** 192 * The tags for children's content. 193 * @type { ?number } 194 * @syscap SystemCapability.Advertising.Ads 195 * @atomicservice 196 * @since 12 197 */ 198 tagForChildProtection?: number; 199 200 /** 201 * Advertisement content classification setting. 202 * @type { ?string } 203 * @syscap SystemCapability.Advertising.Ads 204 * @since 11 205 */ 206 /** 207 * Advertisement content classification setting. 208 * @type { ?string } 209 * @syscap SystemCapability.Advertising.Ads 210 * @atomicservice 211 * @since 12 212 */ 213 adContentClassification?: string; 214 215 /** 216 * Non-personalized ad settings. 217 * @type { ?number } 218 * @syscap SystemCapability.Advertising.Ads 219 * @since 11 220 */ 221 /** 222 * Non-personalized ad settings. 223 * @type { ?number } 224 * @syscap SystemCapability.Advertising.Ads 225 * @atomicservice 226 * @since 12 227 */ 228 nonPersonalizedAd?: number; 229 230 /** 231 * The extended attributes for ad options. 232 * @type { number | boolean | string | undefined } 233 * @syscap SystemCapability.Advertising.Ads 234 * @since 11 235 */ 236 /** 237 * The extended attributes for ad options. 238 * @type { number | boolean | string | undefined } 239 * @syscap SystemCapability.Advertising.Ads 240 * @atomicservice 241 * @since 12 242 */ 243 [key: string]: number | boolean | string | undefined; 244 } 245 246 /** 247 * The interaction options info for displaying ad. 248 * @typedef AdDisplayOptions 249 * @syscap SystemCapability.Advertising.Ads 250 * @since 11 251 */ 252 /** 253 * The interaction options info for displaying ad. 254 * @typedef AdDisplayOptions 255 * @syscap SystemCapability.Advertising.Ads 256 * @atomicservice 257 * @since 12 258 */ 259 export interface AdDisplayOptions { 260 /** 261 * Ad custom data. 262 * @type { ?string } 263 * @syscap SystemCapability.Advertising.Ads 264 * @since 11 265 */ 266 /** 267 * Ad custom data. 268 * @type { ?string } 269 * @syscap SystemCapability.Advertising.Ads 270 * @atomicservice 271 * @since 12 272 */ 273 customData?: string; 274 275 /** 276 * User id. 277 * @type { ?string } 278 * @syscap SystemCapability.Advertising.Ads 279 * @since 11 280 */ 281 /** 282 * User id. 283 * @type { ?string } 284 * @syscap SystemCapability.Advertising.Ads 285 * @atomicservice 286 * @since 12 287 */ 288 userId?: string; 289 290 /** 291 * Indicates whether a dialog box is displayed to notify users of video playback 292 * and application download in non-Wi-Fi scenarios. 293 * @type { ?boolean } 294 * @syscap SystemCapability.Advertising.Ads 295 * @since 11 296 */ 297 /** 298 * Indicates whether a dialog box is displayed to notify users of video playback 299 * and application download in non-Wi-Fi scenarios. 300 * @type { ?boolean } 301 * @syscap SystemCapability.Advertising.Ads 302 * @atomicservice 303 * @since 12 304 */ 305 useMobileDataReminder?: boolean; 306 307 /** 308 * Indicates whether to mute the playback of the ad video. 309 * @type { ?boolean } 310 * @syscap SystemCapability.Advertising.Ads 311 * @since 11 312 */ 313 /** 314 * Indicates whether to mute the playback of the ad video. 315 * @type { ?boolean } 316 * @syscap SystemCapability.Advertising.Ads 317 * @atomicservice 318 * @since 12 319 */ 320 mute?: boolean; 321 322 /** 323 * The type of the scenario where the audio focus is obtained during video playback. 324 * @type { ?number } 325 * @syscap SystemCapability.Advertising.Ads 326 * @since 11 327 */ 328 /** 329 * The type of the scenario where the audio focus is obtained during video playback. 330 * @type { ?number } 331 * @syscap SystemCapability.Advertising.Ads 332 * @atomicservice 333 * @since 12 334 */ 335 audioFocusType?: number; 336 337 /** 338 * The extended attributes for interaction options. 339 * @type { number | boolean | string | undefined } 340 * @syscap SystemCapability.Advertising.Ads 341 * @since 11 342 */ 343 /** 344 * The extended attributes for interaction options. 345 * @type { number | boolean | string | undefined } 346 * @syscap SystemCapability.Advertising.Ads 347 * @atomicservice 348 * @since 12 349 */ 350 [key: string]: number | boolean | string | undefined; 351 } 352 353 /** 354 * The listener of ad interaction. 355 * @interface AdInteractionListener 356 * @syscap SystemCapability.Advertising.Ads 357 * @since 11 358 */ 359 /** 360 * The listener of ad interaction. 361 * @interface AdInteractionListener 362 * @syscap SystemCapability.Advertising.Ads 363 * @atomicservice 364 * @since 12 365 */ 366 export interface AdInteractionListener { 367 /** 368 * Ads status callback. 369 * @param { string } status - The current ad status. The status contains onAdOpen,onAdClose,onAdReward,onAdClick,onVideoPlayBegin and onVideoPlayEnd. 370 * @param { Advertisement } ad - The ad which status is changed. 371 * @param { string } data - The data of current ad status. 372 * @syscap SystemCapability.Advertising.Ads 373 * @since 11 374 */ 375 /** 376 * Ads status callback. 377 * @param { string } status - The current ad status. The status contains onAdOpen,onAdClose,onAdReward,onAdClick,onVideoPlayBegin and onVideoPlayEnd. 378 * @param { Advertisement } ad - The ad which status is changed. 379 * @param { string } data - The data of current ad status. 380 * @syscap SystemCapability.Advertising.Ads 381 * @atomicservice 382 * @since 12 383 */ 384 onStatusChanged(status: string, ad: Advertisement, data: string); 385 } 386 387 /** 388 * The listener of loading ad. 389 * @interface AdLoadListener 390 * @syscap SystemCapability.Advertising.Ads 391 * @since 11 392 */ 393 /** 394 * The listener of loading ad. 395 * @interface AdLoadListener 396 * @syscap SystemCapability.Advertising.Ads 397 * @atomicservice 398 * @since 12 399 */ 400 export interface AdLoadListener { 401 /** 402 * Called by system when the ad load has been failed. 403 * @param { number } errorCode - code of ad loading failure. 404 * @param { string } errorMsg - error message. 405 * @syscap SystemCapability.Advertising.Ads 406 * @since 11 407 */ 408 /** 409 * Called by system when the ad load has been failed. 410 * @param { number } errorCode - code of ad loading failure. 411 * @param { string } errorMsg - error message. 412 * @syscap SystemCapability.Advertising.Ads 413 * @atomicservice 414 * @since 12 415 */ 416 onAdLoadFailure(errorCode: number, errorMsg: string): void; 417 418 /** 419 * Called by system when the ad load has been succeeded. 420 * @param { Array<Advertisement> } ads - advertisements are loaded successfully. 421 * @syscap SystemCapability.Advertising.Ads 422 * @since 11 423 */ 424 /** 425 * Called by system when the ad load has been succeeded. 426 * @param { Array<Advertisement> } ads - advertisements are loaded successfully. 427 * @syscap SystemCapability.Advertising.Ads 428 * @atomicservice 429 * @since 12 430 */ 431 onAdLoadSuccess(ads: Array<Advertisement>): void; 432 } 433 434 /** 435 * The listener of loading multi-slots ad. 436 * @interface MultiSlotsAdLoadListener 437 * @syscap SystemCapability.Advertising.Ads 438 * @since 11 439 */ 440 /** 441 * The listener of loading multi-slots ad. 442 * @interface MultiSlotsAdLoadListener 443 * @syscap SystemCapability.Advertising.Ads 444 * @atomicservice 445 * @since 12 446 */ 447 export interface MultiSlotsAdLoadListener { 448 /** 449 * Called by system when the ad load has been failed. 450 * @param { number } errorCode - code of ad loading failure. 451 * @param { string } errorMsg - error message. 452 * @syscap SystemCapability.Advertising.Ads 453 * @since 11 454 */ 455 /** 456 * Called by system when the ad load has been failed. 457 * @param { number } errorCode - code of ad loading failure. 458 * @param { string } errorMsg - error message. 459 * @syscap SystemCapability.Advertising.Ads 460 * @atomicservice 461 * @since 12 462 */ 463 onAdLoadFailure(errorCode: number, errorMsg: string): void; 464 465 /** 466 * Called by system when the ad load has been succeeded. 467 * @param { Map<string, Array<Advertisement>> } adsMap - advertisements are loaded successfully. 468 * @syscap SystemCapability.Advertising.Ads 469 * @since 11 470 */ 471 /** 472 * Called by system when the ad load has been succeeded. 473 * @param { Map<string, Array<Advertisement>> } adsMap - advertisements are loaded successfully. 474 * @syscap SystemCapability.Advertising.Ads 475 * @atomicservice 476 * @since 12 477 */ 478 onAdLoadSuccess(adsMap: Map<string, Array<Advertisement>>): void; 479 } 480 481 /** 482 * Show the reward and interstitial ad. 483 * @param { Advertisement } ad - Indicates the advertisement content information. ad is required. 484 * @param { AdDisplayOptions } options - Indicates interaction option object use to show the ad. options is required. 485 * @param { common.UIAbilityContext } context - Indicates the ui ability context of the media application. 486 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 487 * @throws { BusinessError } 21800001 - System internal error. 488 * @throws { BusinessError } 21800004 - Failed to display the ad. 489 * @syscap SystemCapability.Advertising.Ads 490 * @since 11 491 */ 492 /** 493 * Show the reward and interstitial ad. 494 * @param { Advertisement } ad - Indicates the advertisement content information. ad is required. 495 * @param { AdDisplayOptions } options - Indicates interaction option object use to show the ad. options is required. 496 * @param { common.UIAbilityContext } context - Indicates the ui ability context of the media application. 497 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 498 * @throws { BusinessError } 21800001 - System internal error. 499 * @throws { BusinessError } 21800004 - Failed to display the ad. 500 * @syscap SystemCapability.Advertising.Ads 501 * @atomicservice 502 * @since 12 503 */ 504 function showAd(ad: Advertisement, options: AdDisplayOptions, context?: common.UIAbilityContext): void; 505 506 /** 507 * Provides the functions of loading ads. 508 * @syscap SystemCapability.Advertising.Ads 509 * @since 11 510 */ 511 /** 512 * Provides the functions of loading ads. 513 * @syscap SystemCapability.Advertising.Ads 514 * @atomicservice 515 * @since 12 516 */ 517 export class AdLoader { 518 /** 519 * Constructs a adLoader object, context should be transferred. 520 * @param { common.Context } context - Indicates the context of the media application. 521 * @syscap SystemCapability.Advertising.Ads 522 * @since 11 523 */ 524 /** 525 * Constructs a adLoader object, context should be transferred. 526 * @param { common.Context } context - Indicates the context of the media application. 527 * @syscap SystemCapability.Advertising.Ads 528 * @atomicservice 529 * @since 12 530 */ 531 constructor(context: common.Context); 532 533 /** 534 * Load ad. 535 * @param { AdRequestParams } adParam - Indicates the parameters in the request. adParam.adId is required. 536 * <br>adParam.adType must be number and valid. adParam.adWidth and adParam.adHeight must be number and greater than zero 537 * @param { AdOptions } adOptions - Indicates the ad options. 538 * @param { AdLoadListener } listener - Indicates the listener to be registered that use to load ad. 539 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 540 * <br>2. Incorrect parameter types. 3.Parameter verification failed 541 * @throws { BusinessError } 21800001 - System internal error. 542 * @throws { BusinessError } 21800003 - Failed to load the ad request. 543 * @syscap SystemCapability.Advertising.Ads 544 * @since 11 545 */ 546 /** 547 * Load ad. 548 * @param { AdRequestParams } adParam - Indicates the parameters in the request. adParam.adId is required. 549 * <br>adParam.adType must be number and valid. adParam.adWidth and adParam.adHeight must be number and greater than zero 550 * @param { AdOptions } adOptions - Indicates the ad options. 551 * @param { AdLoadListener } listener - Indicates the listener to be registered that use to load ad. 552 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 553 * <br>2. Incorrect parameter types. 3.Parameter verification failed 554 * @throws { BusinessError } 21800001 - System internal error. 555 * @throws { BusinessError } 21800003 - Failed to load the ad request. 556 * @syscap SystemCapability.Advertising.Ads 557 * @atomicservice 558 * @since 12 559 */ 560 loadAd(adParam: AdRequestParams, adOptions: AdOptions, listener: AdLoadListener): void; 561 562 /** 563 * Load ad with multi-slots. 564 * @param { AdRequestParams[] } adParams - Indicates the parameters in the request. adParam.adId is required. 565 * <br>adParam.adType must be number and valid. adParam.adWidth and adParam.adHeight must be number and greater than zero 566 * @param { AdOptions } adOptions - Indicates the ad options. 567 * @param { MultiSlotsAdLoadListener } listener - Indicates the listener to be registered that use to load ad. 568 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 569 * <br>2. Incorrect parameter types. 3.Parameter verification failed 570 * @throws { BusinessError } 21800001 - System internal error. 571 * @throws { BusinessError } 21800003 - Failed to load the ad request. 572 * @syscap SystemCapability.Advertising.Ads 573 * @since 11 574 */ 575 /** 576 * Load ad with multi-slots. 577 * @param { AdRequestParams[] } adParams - Indicates the parameters in the request. adParam.adId is required. 578 * <br>adParam.adType must be number and valid. adParam.adWidth,adParam.adHeight must be number and greater than zero 579 * @param { AdOptions } adOptions - Indicates the ad options. 580 * @param { MultiSlotsAdLoadListener } listener - Indicates the listener to be registered that use to load ad. 581 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 582 * <br>2. Incorrect parameter types. 3.Parameter verification failed 583 * @throws { BusinessError } 21800001 - System internal error. 584 * @throws { BusinessError } 21800003 - Failed to load the ad request. 585 * @syscap SystemCapability.Advertising.Ads 586 * @atomicservice 587 * @since 12 588 */ 589 loadAdWithMultiSlots(adParams: AdRequestParams[], adOptions: AdOptions, listener: MultiSlotsAdLoadListener): void; 590 } 591 592 /** 593 * Get message body for ad requesting. 594 * @param { AdRequestParams[] } adParams - Indicates the parameters in the request. 595 * @param { AdOptions } adOptions - Indicates the ad options. 596 * @returns { Promise<string> } The promise of ad request message body. 597 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 598 * @throws { BusinessError } 21800001 - System internal error. 599 * @syscap SystemCapability.Advertising.Ads 600 * @since 12 601 */ 602 function getAdRequestBody(adParams: AdRequestParams[], adOptions: AdOptions): Promise<string>; 603 604 /** 605 * Pass ad response message and parse into advertisements. 606 * @param { string } adResponse - Indicate the ad response message. 607 * @param { MultiSlotsAdLoadListener } listener - Indicates the listener to be registered that use to load ad. 608 * @param { common.UIAbilityContext } context - Indicates the ui ability context of the media application. 609 * @throws { BusinessError } 401 - Invalid input parameter.Possible causes: 1. Mandatory parameters are left unspecified. 610 * @throws { BusinessError } 21800001 - System internal error. 611 * @throws { BusinessError } 21800005 - Failed to parse the ad response. 612 * @syscap SystemCapability.Advertising.Ads 613 * @since 12 614 */ 615 function parseAdResponse(adResponse: string, listener: MultiSlotsAdLoadListener, context: common.UIAbilityContext): void; 616 617 /** 618 * Register ad javascript proxy interface into webview in order to enable web Ad. 619 * @param { web_webview.WebviewController } controller - Indicates webview controller to register ad javascript proxy interface. 620 * @param { common.UIAbilityContext } context - Indicates the ui ability context of the media application. 621 * @throws { BusinessError } 401 - Invalid input parameter. Possible causes: 1. Mandatory parameters are left unspecified. 622 * @throws { BusinessError } 21800001 - System internal error. 623 * @syscap SystemCapability.Advertising.Ads 624 * @atomicservice 625 * @since 12 626 */ 627 function registerWebAdInterface(controller: web_webview.WebviewController, context: common.UIAbilityContext): void; 628} 629 630export default advertising;