请输入
菜单

SDK初始化及API说明

SDK 初始化及 API 说明

1. 初始化 SDK

1.1 初始化方法使用

初始化 SDK,一般推荐在 Index.ets 或者EntryAbility 中进行,提前做好 SDK 相关的准备。也方便开屏广告的加载展示。

TypeScript 复制代码
export default class EntryAbility extends UIAbility {

    initAMPSSDK(){
      //1、获取跨应用关联权限
      requestOAIDTrackingPermissions()
      //2、初始化配置
      let config: AMPSInitConfig = new AMPSInitConfig.Builder(appId,this.context)
        //.setApiKey(apiKey)//可选
        //.setDebugSetting(true)//可选
        //.setIsTestAd(false)//可选
        //.set...
        .build()
      let callback: AMPSIInitCallback = {
        initSuccess: (): void => {
          this.startSplashAD()
        },
        initializing: (): void => {
          console.log("--------asnp-initializing-----")
        },
        alreadyInit: (): void => {
          console.log("--------asnp-alreadyInit-----")
        },
        initFailed: (code: number, msg: string): void => {
          console.log("--------asnp-initFailed-----")
        }
      }
      //3、初始化SDK
      AMPSAdSdk.init(config,callback)
    }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    let windowClass: window.Window = windowStage.getMainWindowSync()
    windowClass.setWindowLayoutFullScreen(true)
    this.requestPermission(this.context)
    windowStage.loadContent('pages/Index', (err) => {
      this.initAMPSSDK()//必须放在windowStage.loadContent之后【大多数媒体选择放在Index等启动页面内,推荐使用】
      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.');
    });
  }

}

2. API 说明

2.1 AMPSAdSdk 方法说明

方法 说明
init(config: AMPSInitConfig, callback: AMPSIInitCallback,context: common.Context=getContext()) 初始化 SDK 入口

2.2 AMPSAdSdk 初始化参数说明

属性 说明
AMPSInitConfig 初始化配置类
AMPSIInitCallback SDK 初始化回调接口
common.Context 上下文

2.2.1 AMPSInitConfig 方法说明

SDK 初始化配置类

属性 说明
setUiModel 设置深浅模式
setAdCustomController 设置自定义内容
setDebugSetting 开启测试
setUseHttps 是否使用https协议
set... 具体看下面介绍

2.2.2 AMPSInitConfig 参数说明

TypeScript 复制代码
let config: AMPSInitConfig = new AMPSInitConfig.Builder(appId,this.context)
  //.setApiKey(apiKey)
  .setUiModel(ASNPConstants.UiModel.UI_MODEL_AUTO)//这个可以不写默认就是UI_MODEL_AUTO自动。可以设置【UI_MODEL_DARK、UI_MODEL_LIGHT】
  .setAdCustomController(new AMPSCustomController({isCanUseSensor:true,isSupportPersonalized:true}))//个性化,和传感器等的设置
  //.set...
  .setLandStatusBarHeight(true)//设置落地页是否适配状态栏。
  .setDebugSetting(true)//是否开启debug
  .setUseHttps(false)//是否使用https
  .setIsTestAd(false).build()
属性 所指 设置 必传
appId 媒体的账户 ID new AMPSInitConfig.Builder(appId,this.context)
apiKey 媒体的商户 ID .setApiKey(apiKey)
_isDebugSetting 日志模式 :默认:falseDebug:打印 SDK 日志 release:不打印 SDK 日志 .setDebugSetting(true)
_isUseHttps 是否开启 HTTPS 请求:默认 false 根据 HTTPS 和 HTTP 模式获取对应请求接口获取对应数据模板 .setUseHttps(isUseHttps:boolean)
isTestAd 是否测试广告位默认:false 测试时:设置 true .setIsTestAd(isTestAd: boolean)
countryCN 国家默认:CountryType.COUNTRY_TYPE_CHINA_MAINLANDCountryType.COUNTRY_TYPE_OTHER .setCountryCN(ASNPConstants.CountryType.COUNTRY_TYPE_CHINA_MAINLAND)
currency 支持的现金类型
.setCurrency(ASNPConstants.CurrencyType.CURRENCY_TYPE_CNY)
userId 用户 ID .setUserId(userId: string)
optionFields 自定义字段 optionFields: HashMap<string, string> .setOptionFields(optionFields: HashMap<string, string>)
setUiModel 设置 SDK 内部 UI 对手机系统深浅色的适配。 .setUiModel(uiModel: ASNPConstants.UiModel)
AMPSCustomController 用户自定义内容:new AMPSCustomController
1、isCanUsePhoneState :是否可以使用 PhoneState 权限
2、OAID:当开发者传入之后,默认就会使用传入的 OAID
3、isSupportPersonalized:是否支持个性化
4、getUnderageTag:适龄标记 【 UNKNOWN=-1,MATURITY=0,UNDERAGE=1】
5、userAgent:开发者可获取传入
6、isCanUseSensor:是否可以使用传感器【默认可以】设置为 false 传感器会失效
7、isLocationEnabled:是否允许 SDK 获取位置。【默认可以】开发者可以在注册 ohos.permission.APPROXIMATELY_LOCATION 权限,方便 SDK 内部获取位置;当设置为 false 之后将不会主动获取位置,当然用户可以通过 location 上传位置相关信息。
8、location:类型 AMPSLocation
     longitude?:经度
     latitude?:纬度
     coordinate?AMPSConstants.CoordinateType:经度[WGS84;GCJ02;BAIDU]
     timeStamp?:位置时间戳
.setAdCustomController(controller: AMPSCustomController)
setLandStatusBarHeight 设置落地页是否适配状态栏高度:默认适配了
.setLandStatusBarHeight(true)
setUseHttps 设置使用网络请求协议:默认http请求
.setUseHttps(true)

2.2.3 AMPSIInitCallback 参数说明

作为 SDK 初始化状态、成功与否,可以通过 AMPSIInitCallback 回调进行接收是否成功、失败、正在初始化、已经初始化等状态。

TypeScript 复制代码
export interface AMPSIInitCallback {
  // 定义 initSuccess 方法,无参数
  initSuccess(): void;

  // 定义 initializing 方法,无参数
  initializing(): void;

  // 定义 alreadyInit 方法,无参数
  alreadyInit(): void;

  // 定义 initFailed 方法,接收两个参数:code(数字类型)和 msg(字符串类型)
  initFailed(code: number, msg: string): void;
}

回调方法说明

回调方法 回调说明
initSuccess 初始化成功
initializing 正在初始化
alreadyInit 已经初始化
initFailed 初始化失败

3. 位置信息收集

  • SDK在获取广告时,会判断用户是否同意允许位置信息收集。如果用户配置了位置信息收集权限,SDK将会默认获取设备位置信息。所以开发者可以选择声明位置信息权限,方便SDK收集信息,当然也可以通过AMPSCustomControllerlocation的AMPSLocation参数主动上传位置信息。开发者可以选择在module.json5文件中声明ohos.permission.APPROXIMATELY_LOCATION权限,方便SDK收集信息,确保在配置中声明了下面权限。当然开发者也可以设置是否允许SDK收集位置信息,初始化配置参数设置代码如下:
javaScript 复制代码
  let config: AMPSInitConfig = new AMPSInitConfig.Builder(appId, this.context)
       //...
      .setAdCustomController(new AMPSCustomController({
        isLocationEnabled:false //fale表示不允许SDK内部收集,默认是true
      }))
      .build()

注意:配置文件中需要声明模糊位置信息收集权限

json 复制代码
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:location_reason",
        "usedScene": {"abilities": ["entry"]}
      }

4. 个性化广告开关设置

4.1 功能说明

  • 首先个性化设置会控制是否上传给服务端广告标识符 OAID,如果个性化设置是关闭的,在正式环境下服务端是不会下发广告数据的。所以默认应该开启支持个性化设置。当然个性化开关的开启意味着,可以上报给服务端广告标识符,后台才会下发广告。
  • 广告标识符在 Android 和鸿蒙中都是可以通过系统 API 获取唯一标识符的,也就是每台设备都具有唯一的广告标识符。而在鸿蒙中广告标识符依赖于广告标识符服务,需要向用户动态申请权限。
  • 首先鸿蒙系统中,通过广告标识服务获取 OAID,该服务需要向用户申请授权:ohos.permission.APP_TRACKING_CONSENT。
  • 此权限是需要用户动态申请授权,理应有用户授权弹窗,在最近 2024 年 8 月份 API 变化之后,默认是无授权弹窗的,只要动态申请就给允许权限。当然,如果需要弹窗,需要用户在设置-->隐私和安全->跨应用关联->点击打开【要求应用请求关联】,才会弹窗,有弹窗之后,需要用户点击允许才能决定其是否允许。
  • 只有动态申请之后才,可以通过 identifier.getOAID()获取到 OAID。

根据以上可见,默认个性化只能是开启,避免正式环境无广告下发,如果需要获取用户设备的唯一广告标识符 OAID,最好开发者动态申请权限,否则 SDK 会提供一个零时的未卸载周期内的 OAID。

4.2 实现方式

4.2.1 初始化跨应用关联权限【允许,拒绝】

根据上述说明:在 SDK 默认个性化是开启状态,开发者获取设备唯一的标识符建议动态申请权限:

1、如果动态申请权限,且 【要求应用请求关联】为默认不勾选。无应用授权弹窗,直接默认会允许。

2、如果用户手动设置【要求应用请求关联】为打开,需要用户点击【允许】才可以。

注意:配置文件中需要声明跨应用关联权限"ohos.permission.APP_TRACKING_CONSENT"

json 复制代码
{
  "name": "ohos.permission.APP_TRACKING_CONSENT",
  "reason": "$string:app_name",
  "usedScene": {
    "abilities": [
      "entry"
    ]
  }
}

代码检测是否授予权限代码如下:

TypeScript 复制代码
//获取OAID官方相关案例代码
async function requestOAIDTrackingConsentPermissions(context: common.Context): Promise<void> {
  // 进入页面时,向用户请求授权广告跨应用关联访问权限
  const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
  try {
    //检查用户是否授予了此权限为【允许】,这里需要注意动态申请是不会弹窗的,需要用户到应用跟踪页面去设置
    let data = await atManager.requestPermissionsFromUser(context, ["ohos.permission.APP_TRACKING_CONSENT"])
    if (data.authResults[0] == 0) { //表示打开了权限

      //----------------------------OAID在SDK内部已经获取,下面获取OAID部分可以作为了解-----------------------------------------
      //权限打开并不意味着一定会拿到,此API并不适用所有设备类型,所以需要进行判断
      if (canIUse("SystemCapability.Advertising.OAID")) {
        identifier.getOAID((err: BusinessError, data: string) => {
          if (err.code) {
          } else {
            //获取OAID成功
            const oaid: string = data;
          }
        });
       //----------------------------OAID在SDK内部已经获取,上面获取OAID部分可以作为了解-----------------------------------------
      }
    }else{
        //TODO 可以做引导,让用户授权打开跨应用关联未允许。
    }
  } catch (err) {

  }
}

//检测跨应用关联权限是否授权
async function requestOAIDTrackingConsentPermissions(context: common.Context): Promise<boolean> {
  // 进入页面时,向用户请求授权广告跨应用关联访问权限
  const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
  try {
    let data= await atManager.requestPermissionsFromUser(context, ["ohos.permission.APP_TRACKING_CONSENT"])
    return data.authResults[0] == 0
  } catch (err) {
    return false
  }
}

如果需要关闭个性化,可以通过.setAdCustomController 设置 AMPSCustomController,并设置 isSupportPersonalized = false。【需要注意,如果关闭个性化设置,正式环境是不会返回广告的,所以默认是 isSupportPersonalized return true】

TypeScript 复制代码
//1、创建AMPSCustomController,如果想获取用户设备真实的OAID,需保证应用是否真正允许了跟踪权限。
//2、检测是否开启了了个性化开关
//如果个性化开启需要保证动态申请和用户设置了【允许】
//可以使用一下代码判断并设置个性化开启
async  requestOAIDTrackingConsentPermissions(context: common.Context): Promise<boolean> {
  // 进入页面时,向用户请求授权广告跨应用关联访问权限
  const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
  try {
    let data = await atManager.requestPermissionsFromUser(context, ["ohos.permission.APP_TRACKING_CONSENT"])
    return data.authResults[0] == 0
  } catch (err) {
    return false
  }
}

//动态申请权限,方便SDK内部获取设备唯一广告标识符
await this.requestOAIDTrackingConsentPermissions(this.context)

//===初始化
let config: AMPSInitConfig = new AMPSInitConfig.Builder(appId, this.context)
   //.setApiKey(apiKey)
   //.setDebugSetting(true)
   //.setIsTestAd(false)
   //.setAdCustomController(new AMPSCustomController({isCanUseSensor:true,isSupportPersonalized:true}))//个性化,和传感器等的设置
  .build()

  AMPSAdSdk.init(config, callback, this.context)

推荐方式:用户动态申请跨应用关联权限之后进行初始化SDK。

如果需要打开个性化设置,请认真阅读此篇文档

由于鸿蒙目前需要动态申请权限,且如果用户点击【要求应用请求关联】,就需要引导用户再次开启权限。

Plaintext 复制代码
推荐实现方式:
(1)开发者主动在SDK初始化之前动态申请权限
(2)根据代码严格判断是否用户授予了此权限
(3)默认来说首次初始化动态申请,8月份版本之后的默认是true,只要保证在初始化SDK之前动态调用权限申请即可。
(4)用户如果之前在设置的-->隐私和安全->跨应用关联->点击打开了【要求应用请求关联】,启动SDK初始化之后,会出现动态授权弹窗,如果用户点击不同意,需要用户再次去应用关联权限允许权限,下次应用初始化或者轮询配置获取时候,会主动的获取OAID。
上一个
SDK接入配置
下一个
开屏广告接入及API说明
最近修改: 2025-06-10