菜单

原生广告

1. 加载广告

const atNativeAd = new ATNativeAd("your placement id");
atNativeAd.setAdListener({
  onAdLoaded: (): void => { },
  onAdLoadFailed: (adError: ATAdError): void => { }
  onAdOtherStatus: (adInfo?: ATAdInfo | undefined): void => { }
});
atNativeAd.loadAd({
  context: getContext(),
  uiContext: this.getUIContext()
});

2. 展示广告

（1）先通过ATNative#getNativeAd()获取广告对象NativeAd

const nativeAd = atNativeAd.getNativeAd();
if (!nativeAd) {
  this.adMsg = "ad is not ready";
  return;
}
nativeAd?.setNativeAdEventListener({
  onAdShow: (adInfo: ATAdInfo): void => { },
  onAdClose: (adInfo: ATAdInfo): void => { },
  onAdClick: (adInfo: ATAdInfo): void => { },
  onAdDislikeClick: (adInfo: ATAdInfo): void => { },
  onAdVideoResume: (adInfo: ATAdInfo): void => { },
  onAdVideoPause: (adInfo: ATAdInfo): void => { },
  onAdVideoPlayStart: (adInfo: ATAdInfo): void => { },
  onAdVideoPlayEnd: (adInfo: ATAdInfo): void => { },
  onAdVideoPlayFailed: (adError: ATAdError, adInfo?: ATAdInfo | undefined): void => { }
})

（2）再通过NativeAd的isNativeExpress方法判断是自渲染还是模板渲染

if (nativeAd?.isNativeExpress()) {
  // 模板渲染
  ...
} else {
  // 自渲染
  ...
}

● 模板渲染

@Component
struct NativeAdPage {

  build() {
    ... 
    BuildATNativeAdExpressView(nativeAd);
    ...
  }

}

● 自渲染

通过NativeAd的getAdMaterial方法获取素材进行渲染，详情请参考Demo示例：NativeAdItemComponent。

3. API说明

● ATNativeAd

原生广告的操作类，负责广告加载、监听、显示等。

方法	说明
ATNativeAd(placementId: string)	广告的初始化方法 placementID：原生样式的广告位，通过后台创建开屏广告位获取的
setAdListener(listener: ATNativeAdLoadListener)	设置广告位层级的广告监听回调 listener：广告位事件回调的接口类
loadAd(adLoadConfig?: ATNativeAdLoadConfig)	发起广告加载 adLoadConfig：加载广告配置
getNativeAd(showConfig?: ATNativeAdShowConfig)	获取广告对象，用于展示广告
isAdReady()	判断当前广告位是否存在可展示的广告返回值：true=存在可展示的广告，false=不存在可展示的广告
getAdCaches()	查询当前广告位的所有缓存信息的ATAdInfo对象
getTopAdInfo()	获取当前广告位优先级最高的广告缓存信息 ATAdInfo对象

● ATNativeAdLoadListener

广告位层级的广告事件回调

方法	说明
onAdLoaded: ()	广告加载成功回调
onAdLoadFailed: (adError: ATAdError)	广告加载失败回调

● NativeAd

原生广告对象，用于展示广告

方法	说明
setNativeAdEventListener(listener: NativeAdEventListener)	设置广告展示相关的事件监听回调
isNativeExpress()	是否为模板渲染类型的广告返回值：true=模板广告，false=自渲染广告
getAdMaterial()	获取广告素材对象，仅自渲染广告支持返回值：广告素材对象

● ATNativeAdEventListener

广告展示相关的事件监听回调

方法	说明
onAdShow: (adInfo: ATAdInfo)	广告展示回调
onAdClose: (adInfo: ATAdInfo)	广告关闭回调
onAdClick: (adInfo: ATAdInfo)	广告点击回调
onAdDislikeClick: (adInfo: ATAdInfo)	广告点击关闭回调
onAdVideoResume: (adInfo: ATAdInfo)	广告继续播放回调
onAdVideoPause: (adInfo: ATAdInfo)	广告暂停播放回调
onAdVideoPlayStart: (adInfo: ATAdInfo)	广告开始播放回调
onAdVideoPlayEnd: (adInfo: ATAdInfo)	广告播放结束回调
onAdVideoPlayFailed: (adError: ATAdError, adInfo?: ATAdInfo \| undefined)	广告播放失败回调

● ATNativeAdMaterial

自渲染广告返回的广告素材对象

方法	说明
getAdTitle()	获取广告标题
getAdDesc()	获取广告描述
getAdMainImageUrl()	获取广告主图url
getImageUrlList()	获取图片列表-url
getImageList()	获取广告图片列表对象
getAdIconUrl()	获取广告Icon
getAdFrom()	获取广告来源/赞助商
getAdChoiceUrl(choiceType?: ATAdChoiceType)	获取广告角标 NORMAL = 0, GREY = 1
getAdMaterialType()	获取素材类型 UNKNOWN = 0, VIDEO = 1, IMAGE = 2, LIVE = 3
getAdCallToActionText()	获取广告按钮文案
getAdInteractionType()	获取广告的交互类型 UNKNOWN = 0, DOWNLOAD = 1, H5 = 2
getAdAppInfo()	获取广告应用相关的信息,比如隐私数据，应用名
getAdVideoInfo()	获取视频相关信息
getUniqueKey()	获取唯⼀标识，⽤于LazyForEach标识⼴告
getVisibleAreaRatios()	获取可⻅区域监听数组
getVisibleAreaChangeListener()	可⻅区域监听⽅法，⽤于SDK内部判断⻚⾯展示⽐例，处理⼴告曝光&视频播放等
getClickHandler()	控件点击监听

注意事项

● 快手

如果有集成快手平台，需要调用以下广告曝光和广告点击的api。

广告曝光

⼴告曝光逻辑按照⻚⾯展示⽐例来计算，开发者需要在⾃渲染的⼴告组件上监听展示⽐例并且回调给SDK，示例：

// 添加可⻅区域监听，SDK内部处理曝光逻辑
.onVisibleAreaChange(this.itemInfo.nativeAd?.getVisibleAreaRatios(), 
this.itemInfo.nativeAd?.getVisibleAreaChangeListener())

广告点击

⽬前SDK内部⽆法⾃动给开发者的UI组件添加点击事件，对于点击后需要触发转化的控件，需要⼿动添加点击事件

并且回调给SDK，示例：

.onClick((e: ClickEvent) => {
// 点击转化
this.itemInfo?.nativeAd?.getClickHandler()(getContext(this) as common.UIAbilityContext, 
e)
})

最近修改: 2025-05-30Powered by

大纲