初始化 SDK,一般推荐在 Index.ets 或者EntryAbility 中进行,提前做好 SDK 相关的准备。也方便开屏广告的加载展示。
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.');
});
}
}
方法 | 说明 |
---|---|
init(config: AMPSInitConfig, callback: AMPSIInitCallback,context: common.Context=getContext()) | 初始化 SDK 入口 |
属性 | 说明 |
---|---|
AMPSInitConfig | 初始化配置类 |
AMPSIInitCallback | SDK 初始化回调接口 |
common.Context | 上下文 |
SDK 初始化配置类
属性 | 说明 |
---|---|
setUiModel | 设置深浅模式 |
setAdCustomController | 设置自定义内容 |
setDebugSetting | 开启测试 |
setUseHttps | 是否使用https协议 |
set... | 具体看下面介绍 |
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) | 否 |
作为 SDK 初始化状态、成功与否,可以通过 AMPSIInitCallback 回调进行接收是否成功、失败、正在初始化、已经初始化等状态。
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 | 初始化失败 |
let config: AMPSInitConfig = new AMPSInitConfig.Builder(appId, this.context)
//...
.setAdCustomController(new AMPSCustomController({
isLocationEnabled:false //fale表示不允许SDK内部收集,默认是true
}))
.build()
注意:配置文件中需要声明模糊位置信息收集权限
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:location_reason",
"usedScene": {"abilities": ["entry"]}
}
根据以上可见,默认个性化只能是开启,避免正式环境无广告下发,如果需要获取用户设备的唯一广告标识符 OAID,最好开发者动态申请权限,否则 SDK 会提供一个零时的未卸载周期内的 OAID。
根据上述说明:在 SDK 默认个性化是开启状态,开发者获取设备唯一的标识符建议动态申请权限:
1、如果动态申请权限,且 【要求应用请求关联】为默认不勾选。无应用授权弹窗,直接默认会允许。
2、如果用户手动设置【要求应用请求关联】为打开,需要用户点击【允许】才可以。
注意:配置文件中需要声明跨应用关联权限"ohos.permission.APP_TRACKING_CONSENT"
{
"name": "ohos.permission.APP_TRACKING_CONSENT",
"reason": "$string:app_name",
"usedScene": {
"abilities": [
"entry"
]
}
}
代码检测是否授予权限代码如下:
//获取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】
//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。
如果需要打开个性化设置,请认真阅读此篇文档
由于鸿蒙目前需要动态申请权限,且如果用户点击【要求应用请求关联】,就需要引导用户再次开启权限。
推荐实现方式:
(1)开发者主动在SDK初始化之前动态申请权限
(2)根据代码严格判断是否用户授予了此权限
(3)默认来说首次初始化动态申请,8月份版本之后的默认是true,只要保证在初始化SDK之前动态调用权限申请即可。
(4)用户如果之前在设置的-->隐私和安全->跨应用关联->点击打开了【要求应用请求关联】,启动SDK初始化之后,会出现动态授权弹窗,如果用户点击不同意,需要用户再次去应用关联权限允许权限,下次应用初始化或者轮询配置获取时候,会主动的获取OAID。