harmony 鸿蒙@ohos.advertising.AdsServiceExtensionAbility (ExtensionAbility for Ads) (System API)

2025-06-12
浏览 (4)

@ohos.advertising.AdsServiceExtensionAbility (ExtensionAbility for Ads) (System API)

The AdsServiceExtensionAbility module provides ExtensionAbilities for the ads service. Device vendors can implement the service logic of requesting one or multiple ads.

NOTE - The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. - The APIs provided by this module are system APIs.

Modules to Import

import { AdsServiceExtensionAbility } from '@kit.AdsKit';

AdsServiceExtensionAbility.onLoadAd

onLoadAd(adParam: advertising.AdRequestParams, adOptions: advertising.AdOptions, respCallback: RespCallback)

Called when the media application starts to load an ad. The device vendor needs to implement the ad request service logic in this API and send the result to the media application through a call back.

System API: This is a system API.

System capability: SystemCapability.Advertising.Ads

Parameters

Name	Type	Mandatory	Description
adParam	advertising.AdRequestParams	Yes	Ad request parameters.
adOptions	advertising.AdOptions	Yes	Ad configuration.
respCallback	RespCallback	Yes	Ad request callback.

Example

import { AdsServiceExtensionAbility, advertising, RespCallback } from '@kit.AdsKit';

export default class AdsExtensionAbility extends AdsServiceExtensionAbility {
  onLoadAd(adRequestParams: advertising.AdRequestParams, adOptions: advertising.AdOptions, respCallback: RespCallback) {
    const adType: number|undefined = adRequestParams.adType;
    const ads: Array<advertising.Advertisement> = [];
    const rewardVerifyConfig: Map<string, string> = new Map();
    ads.push({
      adType: adType as number,
      uniqueId: '111111',
      rewardVerifyConfig: rewardVerifyConfig,
      rewarded: false,
      shown: false,
      clicked: false
    });
    ads.push({
      adType: adType as number,
      uniqueId: '222222',
      rewardVerifyConfig: rewardVerifyConfig,
      rewarded: false,
      shown: false,
      clicked: false
    });
    const slot: string = 'test';
    const respData: Map<string, Array<advertising.Advertisement>> = new Map();
    respData.set(slot, ads);
    respCallback(respData);
  }
}

AdsServiceExtensionAbility.onLoadAdWithMultiSlots

onLoadAdWithMultiSlots(adParams: advertising.AdRequestParams[], adOptions: advertising.AdOptions, respCallback: RespCallback)

Called when the media application starts to load multiple ads. The device vendor needs to implement the ad request service logic in this API and send the result to the media application through a call back.

System API: This is a system API.

System capability: SystemCapability.Advertising.Ads

Parameters

Name	Type	Mandatory	Description
adParams	advertising.AdRequestParams[]	Yes	Ad request parameters.
adOptions	advertising.AdOptions	Yes	Ad configuration.
respCallback	RespCallback	Yes	Ad request callback.

Example

import { AdsServiceExtensionAbility, advertising, RespCallback } from '@kit.AdsKit';

export default class AdsExtensionAbility extends AdsServiceExtensionAbility {
  onLoadAdWithMultiSlots(adRequestParams: advertising.AdRequestParams[], adOptions: advertising.AdOptions,
    respCallback: RespCallback) {
    const adType1: number = adRequestParams[0].adType as number;
    const ads1: Array<advertising.Advertisement> = [];
    const rewardVerifyConfig: Map<string, string> = new Map();
    ads1.push({
      adType: adType1,
      uniqueId: '111111',
      rewardVerifyConfig: rewardVerifyConfig,
      rewarded: false,
      shown: false,
      clicked: false
    });
    ads1.push({
      adType: adType1,
      uniqueId: '222222',
      rewardVerifyConfig: rewardVerifyConfig,
      rewarded: false,
      shown: false,
      clicked: false
    });
    const slot1: string = 'test1';
    const adType2: number = adRequestParams[1].adType as number;
    const ads2: Array<advertising.Advertisement> = [];
    ads2.push({
      adType: adType2,
      uniqueId: '333333',
      rewardVerifyConfig: rewardVerifyConfig,
      rewarded: false,
      shown: false,
      clicked: false
    });
    ads2.push({
      adType: adType2,
      uniqueId: '444444',
      rewardVerifyConfig: rewardVerifyConfig,
      rewarded: false,
      shown: false,
      clicked: false
    });
    const slot2: string = 'test2';
    const respData: Map<string, Array<advertising.Advertisement>> = new Map();
    respData.set(slot1, ads1);
    respData.set(slot2, ads2);
    respCallback(respData);
  }
}