APICloud 接入指引
一、概述
为方便用户集成, openinstall 已在 APICloud 的模块Store
中上架了官方模块。此模块封装了openinstall平台的SDK,集成了携参安装,渠道统计,快速安装和一键拉起功能;可用于实现移动广告效果统计,免填邀请码,安装后自动加好友,一键加入游戏房间,用户分享统计,微信中快速安装/一键拉起等功能,根据需求可实现更多场景。
二、初始化配置
1. 使用之前须从openinstall平台申请开发者账号并创建应用,获取AppKey,使用此模块之前建议先配置config.xml 文件,配置完毕,需通过云端编译生效,配置方法如下:
<permission name="internet" />
<preference name="urlScheme" value="openinstall官方自动分配的scheme" />
//android下
<meta-data name="com.openinstall.APP_KEY" value="openinstall官方自动分配的appKey" />
//iOS下
<feature name="openinstall">
<param name="com.openinstall.APP_KEY" value="openinstall官方自动分配的appKey" />
</feature>
- 字段描述:
internet:添加网络权限;
urlScheme:使用一键拉起功能必须配置
com.openinstall.APP_KEY:从openinstall平台获取的 AppKey。
注:使用openinstall第三方插件文档集成时,如何快速获取AppKey、Associated Domains和scheme,下图为iOS相关配置信息(Android同理):
2. Universal Links相关配置(iOS9.0以上)
1)到苹果开发者网站,为当前的 AppID 开启关联域名(Associated Domains)服务:
注意:当AppID重新编辑过之后,需要更新相应的mobileprovision证书。更新mobileprovision证书步骤请查看云编译mobileprovision证书制作中的 “云编译mobileprovision发布证书制作”或“云编译mobileprovision测试证书制作”。
2)创建新的(或更新现有的)描述文件,下载并导入到APICloud开发控制台 -> iOS证书;
3)配置关联域名(Associated Domains),方法如下:
在widget\res下创建文件名为UZApp.entitlements的文件,UZApp.entitlements内容如下:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.developer.associated-domains</key><!--固定key值-->
<array>
<!--这里换成你在openinstall后台的关联域名(Associated Domains)-->
<string>applinks:xxxxxx.openinstall.io</string>
</array>
</dict>
</plist>
提示:openinstall完全兼容微信和QQ新版本的通用链接拉起功能,在使用微信模块wxPlus或wxpayPlus 时,对于微信要求配置的config.xml,需要传入openinstall相关的universal link链接。链接格式请到openinstall后台的【iOS集成】-【iOS应用配置】获取,参考univerallinks使用指南
三、调用API
1. 安卓广告参数配置(可选)
config
Android 配置接口,设置广告平台相关参数
config(options)
options
adEnabled:
- 类型:布尔类型;
- 描述:表示 openinstall SDK 是否需要获取广告追踪相关参数,默认为 false
oaid:
- 类型:字符串;
- 描述:通过移动安全联盟获取到的 oaid,默认为 null
gaid:
- 类型:字符串;
- 描述:通过 google api 获取到的 advertisingId,默认为 null
示例代码
var openinstall = api.require('openinstall');
openinstall.config({
adEnabled: true,
oaid: null,
gaid: null,
});
补充说明
此接口是 Android 平台针对广告平台接入而新增的配置接口,需要在调用 init 之前调用。参考广告平台对接Android集成指引
2. 初始化
init
示例代码
var openinstall = api.require('openinstall');
openinstall.init();
补充说明
如启用了广告平台对接,请按以下操作初始化
对于Android平台,需要在config.xml
添加权限申明<permission name="readPhoneState"/>
对于iOS平台,获取idfa使用的是apicloud官方模块iAd,需要用户主动添加,iAd模块
openinstall模块初始化示例代码如下:
apiready = function() {
var openinstall = api.require('openinstall');
if (api.systemType == "ios") {
//需要用到idfa时,先获取idfa,再初始化
var iAd = api.require('iAd');//引入iAd模块
var iAd = iAd.getIDFA({
lowerCase: false
}, function(ret) {
openinstall.init({
deviceId:ret.IDFA,
ASA:true
});
});
//不用idfa时
//openinstall.init({ASA: true});
} else if (api.systemType == "android") {
//申请权限并初始化
var permissions = [];
permissions.push('phone-r');
var result = api.hasPermission({
list: permissions
});
if(result && result[0] && !result[0].granted){
//没有权限,去申请
api.requestPermission({
list: permissions,
code: 100
}, function(ret, err){
//不管是否申请到权限都要调用初始化
openinstall.init();
});
}else{
openinstall.init();
}
}
};
3. 快速安装
如果只需要快速安装功能,无需其它功能(App传参安装、渠道统计、一键拉起),完成初始化即可。
4. 一键拉起
获取拉起参数
getWakeup
getWakeup({uri:ret},callback(ret, err))
callback(ret, err)
ret:
- 类型:JSON对象
- 内部字段:
{
channelCode: '渠道编号',//渠道编号
data: '唤醒携带的参数' //有携带参数,则返回数据,没有则为空
}
示例代码
var openinstall = api.require('openinstall');
api.addEventListener({
name: 'appintent'
}, function(ret, err) {
openinstall.getWakeup({
"uri": ret
}, function(ret, err) {
alert(JSON.stringify(ret));
});
});
补充说明
此接口用于获取动态唤醒参数,通过动态参数,在拉起App时,获取由web网页中传递过来的,如邀请码、游戏房间号等自定义参数,拉起指定页面
监听appintent事件,调用以上代码,获取web端传过来的自定义参数,并回调给getWakeup方法调用;
可用性
Android系统,iOS系统
可提供的1.0.0及更高版本
5. App传参安装高级版功能
getInstall
getInstall({params},callback(ret, err))
params
timeout:
类型:数字类型
描述:超时时长,单位秒(s),默认为10秒
callback(ret, err)
ret:
- 类型:JSON对象
- 内部字段:
{
channelCode: '渠道编号',//渠道编号
data: '个性化安装携带的参数'
}
示例代码
var openinstall = api.require('openinstall');
openinstall.getInstall({
timeout:10
},function(ret, err){
alert(JSON.stringify(ret));
});
补充说明
此接口用于获取动态安装参数(可重复获取),测试时候建议卸载再安装正确获取参数,在App需要个性化安装参数时(由web网页中传递过来的,如邀请码、游戏房间号等自定义参数),在回调中获取参数,可实现拉起指定页面、统计渠道数据等
可用性
Android系统,iOS系统
可提供的1.0.0及更高版本
6. 渠道统计高级版功能
SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。
6.1 reportRegister
上报注册量
reportRegister()
示例代码
var openinstall = api.require('openinstall');
openinstall.reportRegister();
补充说明
openinstall 会自动完成安装量、留存率、活跃量、在线时长等渠道统计数据的上报工作,如需统计每个渠道的注册量(对评估渠道质量很重要),可根据自身的业务规则,在确保用户完成app注册的情况下,调用reportRegister()上报注册量。
在openinstall平台即可看到注册量。
可用性
Android系统,iOS系统
可提供的1.0.0及更高版本
6.2reportEffectPoint**
效果点统计
reportEffectPoint({params})
params
effectId:
类型:字符串
描述:效果点ID
effectValue:
类型:数字类型
描述:效果点值,货币以分为单位
示例代码
var openinstall = api.require('openinstall');
openinstall.reportEffectPoint({
effectId:'effect_test',
effectValue:1
});
补充说明
openinstall 调用reportEffectPoint({params})统计自定义效果点。
effectID与effectValue对应的值与openinstall平台的效果点管理的效果点名称与效果点ID必须一一对应。在openinstall平台即可看到渠道管理的渠道效果点。
四、导出apk/ipa包并上传
- 代码集成完毕后,需要导出安装包上传openinstall后台,openinstall会自动完成所有的应用配置工作。
- 上传完成后即可开始在线模拟测试,体验完整的App安装/拉起流程;待测试无误后,再完善下载配置信息。
下面是apk包的上传界面(后台截图):