请输入
菜单

2、SDK初始化及API说明

SDK 初始化及 API 说明

1. 初始化 SDK

1.1 初始化方法使用

初始化 SDK,一般推荐在 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(); // 获取应用主窗口
      //页面加载之前就做初始化操作。
      this.initAMPSSDK()
      windowStage.loadContent('pages/HomePage', (err) => {});
    }

}

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 初始化配置类

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

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】
  .setDebugSetting(true)
  .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 支持的现金类型默认:
export class CurrencyType {
static readonly CURRENCY_TYPE_CNY = "CNY"; //人民币
static readonly CURRENCY_TYPE_USD = "USD"; //美元
static readonly CURRENCY_TYPE_JPY = "JPY"; //**日元
static readonly CURRENCY_TYPE_EUR = "EUR"; //**欧元
static readonly CURRENCY_TYPE_GBP = "GBP"; //**英镑
static readonly CURRENCY_TYPE_IDR = "IDR"; //印尼盾
static readonly CURRENCY_TYPE_MYR = "MYR"; //马来西亚**林吉特
static readonly CURRENCY_TYPE_PHP = "PHP"; //菲律宾**比索
static readonly CURRENCY_TYPE_KRW = "THB"; //泰铢 }
.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)

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 初始化失败

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、如果用户手动设置【要求应用请求关联】为打开,需要用户点击【允许】才可以。

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

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
  }
}

如果需要关闭个性化,可以继承 AMPSCustomController,并重写 isSupportPersonalized 方法,返回 false 即可。需要开发者手动继承 AMPSCustomController,并在初始化时候进行设置即可。【需要注意,如果关闭个性化设置,正式环境是不会返回广告的,所以默认是 isSupportPersonalized return true】

TypeScript 复制代码
//1、自定义实现AMPSCustomController,并保证应用是否真正允许了跟踪权限。
class MyCustomController extends AMPSCustomController {

  constructor(support:boolean) {
    super();
  }
  isSupportPersonalized(): boolean {
    //开启和关闭个性化设置
    return 【true/false】//默认不重写AMPSCustomController,默认是true。
  }
}


//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 MyCustomController())//默认不传即可,默认支持个性化
  .build()

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

推荐方式:

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

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

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