菜单

开屏广告接入及API说明

开屏广告接入

1. 开屏广告介绍

开屏广告是 app 启动时，显示的一种广告形式.提供两种方式显示广告：

1.通过 router 跳转到广告页来显示广告，一键调用 splashAd?.showAd()

将 AMPSBuildSplashView 添加到 build 方法中，在自主页面或者启动页中显示

2. 开屏广告集成说明

开屏对象可以重复请求，广告请求成功后，未调用显示前不要重复拉取；
广告关闭后可再次调用 loadAd 后会重新拉取广告。

3. 开屏广告 API 说明

3.1 AMPSSplashAd 创建参数说明

3.1.1 ampsAd.AdOptions 属性说明

属性	说明	必传
spaceId	广告位 ID	是
apiKey	商户 ID	否
timeoutInterval	拉取广告超时时间	否
splashAdBottomBuilderHeight	开屏底部自定义高度	否
expressSize	原生广告的宽高	否

3.1.2 AMPSSplashAd 方法说明

方法	说明
constructor(option: ampsAd.AdOptions, callBack: ampsAd.CallBack)	构造方法创建广告对象，option 参数配置，callBack：回调方法集
load	广告请求
showAd	显示广告
isReadyAd	是否有可使用的广告
getECPM	获取竞价
notifyRTBWin	竞价成功上报
notifyRTBLoss	竞价失败上报

showSlash:

调用 SDK 内部的开屏显示方法 showAd(splashConfig?: AMPSSplashConfig)，有相关参数 AMPSSplashConfig 需要注意。

typeScript 复制代码

export interface  AMPSSplashConfig {
  bottomWrappedBuilder?: WrappedBuilder<[]>//底部自定义内容
  routerAnimal?: boolean | undefined | null //是否支持路由动画
}

3.1.2.1、bottomWrappedBuilder

是开发者可以根据自己的需求自定义开屏页底部显示自定义内容。但需要注意 ampsAd.AdOptions 的 splashAdBottomBuilderHeight 是需要和自定义底部内容高度一致的。

3.1.2.2、routerAnimal

调用 SDK 开屏显示，默认有路由动画会有推进来的交互。如果开发者不想要此动画需要设置 routerAnimal 为 boolean，其他情况都是默认路由动画。当然开屏广告页面退出时候，底部页面也需要开发者去除进入动画。

3.1.3 ampsAd.CallBack 回调方法说明

方法	说明
onLoadSuccess?: () => void	开屏广告加载成功
onLoadFailure?: (code: number, message: string) => void	开屏广告加载失败
onRenderOk?: () => void	开屏广告渲染数据准备成功
onRenderFailure?: () => void	开屏广告渲染数据准备失败
onAdShow?: () => void	开屏广告显示
onAdExposure?: () => void	开屏广告曝光
onAdClicked?: () => void	开屏广告点击
onAdClosed?: () => void	开屏广告关闭

4. 开屏广告代码示例

开屏示例根据公司需求具体有四种设置类型：每种设置都有其对应的案例，开发者可以查看 AMPSAdDemo 中相关的页面。

1、调用 SDK 内部的开屏页、无底部自定义内容 =》无需给 SDK 设置自定义视图。【SplashAdBySDKShowTestPage.ets】

javascript 复制代码

//TODO 只需要在回调中调用showSlash
onRenderOk: () => {
//TODO 调用SDK即可
this.splashAd?.showAd()
}

2、调用 SDK 内部的开屏页、需要底部自定义内容 =》需要给 SDK 设置自定义试图。【SplashAdBySDKShowCmBottomTestPage.ets】

typescript 复制代码

onRenderOk: () => {
//TODO 调用SDK即可,需要注意自定义底部内容：需要底部容器Builder的高度需要和option.splashAdBottomBuilderHeight一致
this.splashAd?.showAd(wrapBuilder(SplashBottomVIew))
},
//这里的splashBottomHeightVP需要和SplashBottomVIew的高度一致。
this.option.splashAdBottomBuilderHeight = splashBottomHeightVP
this.splashAd = new AMPSSplashAd(this.option, this.callback)

3、自定义开屏页在自己页面、不需要自定义内容 =》无需自己定义容器。【SplashAdCustomBuildTestPage.ets】

typescript 复制代码

import { promptAction, router } from '@kit.ArkUI';
import { ampsAd, AMPSSplashAd, AMPSBuildSplashView } from 'biz.beizi.adn';
import { splashBottomHeightVP, SplashBottomVIew, WarmTopView } from '../../components/SplashBottomView';
import { SplashTopBarView } from '../../components/SplashTopBarView';
import { SplashWarnType } from '../../data/ItemModel';
/**
 * 注意：
 * 自己页面通过SplashTopBarView来调用开屏广告页面
 * 1、需要自己结合开屏页面状态处理onBackPress
 * 2、通过状态显示页面内容：例如：this.hasSplash = true
 */
@Entry
@Component
struct SplashAdCustomBuildTestPage {
  @State hasSplash: boolean = false
  splashAd?: AMPSSplashAd
  option: ampsAd.AdOptions = {
    spaceId: '15288',
    adCount: 1,
    timeoutInterval: 12000
  }
  callback: ampsAd.CallBack = {
    onLoadSuccess: (): void => {
    },
    onLoadFailure: (code: number, message: string): void => {
      promptAction.showToast({ message: `${message}:code=${code}` })
    },
    onRenderOk: () => {
      //TODO 测量摆放约束计算成功，可去显示了
      this.hasSplash = true
    },
    onAdShown: (): void => {
      console.log('onAdShown')
    },
    onAdExposure: (): void => {
      console.log('onAdExposure')
    },
    onAdClicked: (): void => {
      console.log('onAdClicked')
    },
    onAdClosed: (): void => {
      console.log('onAdClosed')
      this.hasSplash = false
    },
    onOpenLandingPage: () => {
      this.hasSplash = false
    }
  }

  aboutToAppear(): void {
    let routerOption = router.getParams() as Record<string, string>
    if (routerOption) {
      this.option.spaceId = routerOption['spaceId']
    }
    this.splashAd = new AMPSSplashAd(this.option, this.callback)
    //TODO 一般会在aboutToAppear()中自动加载广告。当然建议开屏页面在EntryAbility内部初始化。可参照EntryAbility进行配置。
    this.splashAd?.load()
  }

  build() {
    Column() {
      Stack() {
        Column(){
          SplashTopBarView($r('app.string.splash_ad'))
          WarmTopView(SplashWarnType.CUSTOM)

          Column({ space: 10 }) {
            Text("自己页面内容")
              .fontSize(18)
              .fontColor(Color.Red)
              .fontWeight(FontWeight.Normal)
              .textShadow({
                color: Color.Black,
                radius: 2,
                offsetY: 2,
                offsetX: 2
              })
              .margin({ top: 50, bottom: 20 })
            Button('加载开屏广告')
              .onClick(() => {
                this.splashAd?.load()
              })
          }
          .justifyContent(FlexAlign.Center)
          .layoutWeight(1)
          .width('100%')
        }

        //TODO 通过状态控制开屏控件页面内容的显示与否
        if (this.hasSplash) {
          AMPSBuildSplashView(this.splashAd)
        }
      }


    }
  }
  //TODO 开发者需要屏蔽开屏页面显示时不可被【侧滑、底部导航栏返回键】等影响，从而导致广告曝光所受影响。
  /**
   *
   * @returns
   */
  onBackPress(): boolean | void {
    //显示开屏广告是拦截返回
    if (this.hasSplash) {
      return true
    }
    return false
  }
}

4、自定义开屏页在自己页面、需要添加底部内容 =》需自己在自身布局内部定义容器。【SplashAdCustomBuildBottomTestPage.ets】

typeScript 复制代码

import { promptAction, router } from '@kit.ArkUI';
import { ampsAd, AMPSSplashAd, AMPSBuildSplashView } from 'biz.beizi.adn';
import { splashBottomHeightVP, SplashBottomVIew, WarmTopView } from '../../components/SplashBottomView';
import { SplashTopBarView } from '../../components/SplashTopBarView';
import { SplashWarnType } from '../../data/ItemModel';
/**
 * ⭐⭐⭐⭐注意：SplashBottomView高度需要和option.splashAdBottomBuilderHeight一致
 * 1、自己定义底部内容以及底部高度
 * 2、option.splashAdBottomBuilderHeight = splashBottomHeightVP【需要和底部高度一致】
 * 3、需要自己结合开屏页面状态处理onBackPress
 */
@Entry
@Component
struct SplashAdCustomBuildBottomTestPage {
  @State hasSplash: boolean = false
  splashAd?: AMPSSplashAd
  option: ampsAd.AdOptions = {
    spaceId: '15288',
    adCount: 1,
    timeoutInterval: 12000
  }
  callback: ampsAd.CallBack = {
    onLoadSuccess: (): void => {
    },
    onLoadFailure: (code: number, message: string): void => {
      promptAction.showToast({ message: `${message}:code=${code}` })
    },
    onRenderOk: () => {
      //TODO 测量摆放约束计算成功，可去显示了
      this.hasSplash = true
    },
    onAdShown: (): void => {
      console.log('onAdShown')
    },
    onAdExposure: (): void => {
      console.log('onAdExposure')
    },
    onAdClicked: (): void => {
      console.log('onAdClicked')
    },
    onAdClosed: (): void => {
      console.log('onAdClosed')
      this.hasSplash = false
    },
    onOpenLandingPage: () => {
      this.hasSplash = false
    }
  }

  aboutToAppear(): void {
    let routerOption = router.getParams() as Record<string, string>
    if (routerOption) {
      this.option.spaceId = routerOption['spaceId']
    }
    //TODO 别忘记底部自定义高度需要这里设置，保证测量正确
    this.option.splashAdBottomBuilderHeight = splashBottomHeightVP
    this.splashAd = new AMPSSplashAd(this.option, this.callback)
    //TODO 一般会在aboutToAppear()中自动加载广告。当然建议开屏页面在EntryAbility内部初始化。可参照EntryAbility进行配置。
    this.splashAd?.load()
  }

  build() {
    Column() {
      Stack() {
        //TODO 通过状态控制开屏控件页面内容的显示与否
        if (this.hasSplash) {
          Column() {
            Stack() {
              AMPSBuildSplashView(this.splashAd)
            }
            .flexGrow(1)
            .width('100%')
            .height(100)
            //TODO 自己写相关设计即可
            //wrapBuilder(SplashBottomVIew).builder()
            Row() {
              Image($r("app.media.asnp_ad_logo"))
                .width(50)
                .height(50)
                .margin({ right: 20 })
              Text("倍孜网络")
                .fontSize("20vp")
                .fontColor(Color.Black)
            }
            .alignItems(VerticalAlign.Center)
            .justifyContent(FlexAlign.Start)
            .backgroundColor(Color.White)
            .padding(20)
            .width('100%')
            .height(splashBottomHeightVP)
          }
          .width("100%")
          .height("100%")
        }
      }

      SplashTopBarView($r('app.string.splash_ad'))
      WarmTopView(SplashWarnType.CUSTOM_BOTTOM)


      Column({ space: 10 }) {
        Text("自己页面内容")
          .fontSize(18)
          .fontColor(Color.Red)
          .fontWeight(FontWeight.Normal)
          .textShadow({
            color: Color.Black,
            radius: 2,
            offsetY: 2,
            offsetX: 2
          })
          .margin({ top: 50, bottom: 20 })
        Button('加载开屏广告')
          .onClick(() => {
            this.splashAd?.load()
          })
      }
      .justifyContent(FlexAlign.Center)
      .layoutWeight(1)
      .width('100%')
    }
  }
  //TODO 开发者需要屏蔽开屏页面显示时不可被【侧滑、底部导航栏返回键】等影响，从而导致广告曝光所受影响。
  /**
   *
   * @returns
   */
  onBackPress(): boolean | void {
    //显示开屏广告是拦截返回
    if (this.hasSplash) {
      return true
    }
    return false
  }
}

开屏页广告长见在 EntryAbility 加载与显示：

TypeScript 复制代码

import { abilityAccessCtrl, AbilityConstant, Permissions, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { ampsAd, AMPSAdSdk, AMPSIInitCallback, AMPSInitConfig, AMPSSplashAd } from 'biz.beizi.adn';

export  const appId = "12379"
export  const apiKey = "10023"
export default class EntryAbility extends UIAbility {

  //动态向用户申请跨应用关联权限，保证SDK能获取到广告标识符OAID
  requestPermission(context: Context) {
    let atManager = abilityAccessCtrl.createAtManager();
    const permissions: Array<Permissions> = ['ohos.permission.APP_TRACKING_CONSENT'];
    //requestPermissionsFromUser会判断权限的授权状态来决定是否唤起弹窗
    atManager.requestPermissionsFromUser(context, permissions).then((data) => {
      let grantStatus: Array<number> = data.authResults;
      let length: number = grantStatus.length;
      for (let i = 0; i < length; i++) {
        if (grantStatus[i] === 0) {
          // 用户授权，可以继续访问目标操作
          console.debug('AmpsSdk', 'user grant:' + permissions[i]);
        } else {
          // 用户拒绝授权，提示用户必须授权才能访问当前页面的功能，并引导用户到系统设置中打开相应的权限
          console.debug('AmpsSdk', 'user reject:' + permissions[i]);
          return;
        }
      }
    }).catch((err: Record<string, object>) => {
      console.error('ksadsdk', `requestPermissionsFromUser failed, code is ${err.code}, message is ${err.message}`);
    });
  }
  //初始化广告SDK
  initAMPSSDK(){
    //===初始化
    let config: AMPSInitConfig = new AMPSInitConfig.Builder(appId,this.context)
      //.setApiKey(apiKey)
      //.setDebugSetting(false)
      //.setIsTestAd(false)
      .build()
    let callback: AMPSIInitCallback = {
      initSuccess: (): void => {
        console.log("--------asnp-initSuccess-----")
        this.startSplashAD()
      },
      initializing: (): void => {
        console.log("--------asnp-initializing-----")
      },
      alreadyInit: (): void => {
        console.log("--------asnp-alreadyInit-----")
      },
      initFailed: (code: number, msg: string): void => {
        console.log("--------asnp-initFailed-----")
      }
    }
    AMPSAdSdk.init(config,callback)
  }
  //开屏广告
  startSplashAD() {

    let adLoadCallback: ampsAd.CallBack = {
      onLoadSuccess: (): void => {

      },
      onLoadFailure: (code:number,message:string)=>{
        console.log('---------------asnp-onLoadFailure----code:' + code.toString() + "----message:" + message);
      },
      onRenderOk: (): void => {
        splashAd.showAd()
      },
      onAdShown: (): void => {
        console.log('-------onAdShown-------')
      },
      onAdExposure: (): void => {
        console.log('-------onAdExposure-------')
      },
      onAdClicked: (): void => {
        console.log('-------onAdClicked-------')
      },
      onAdClosed: (): void => {
        console.log('-------onAdClosed-------')
      },
      onOpenLandingPage: ()=>{
        console.log('-------onOpenLandingPage-------')
      },
      onCloseLandingPage:()=>{
        console.log('-------onCloseLandingPage-------')
      }

    }
    let option: ampsAd.AdOptions = {
      apiKey: apiKey,
      spaceId: '15288',
    }

    let splashAd: AMPSSplashAd = new AMPSSplashAd(option,adLoadCallback)
    splashAd.load()
  }
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    //建议动态申请权限放在初始化之前。
    this.requestPermission(this.context)
    // Main window is created, set main page for this ability
    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
    let windowClass: window.Window = windowStage.getMainWindowSync()
    windowClass.setWindowLayoutFullScreen(true)
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
        return;
      }
    this.initAMPSSDK()
      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.');
    });
  }
}

5. 开屏广告注意事项

开屏广告加载必须在 SDK 初始化完成之后。
广告数据准备成功（onRenderOk）之后，在调用 showSlash 显示广告。
Splash 不支持横屏的应用。

上一个

SDK初始化及API说明

下一个

插屏广告接入及API说明

最近修改: 2025-06-10

大纲