uni-app 接入指引
插件介绍
此插件是 openinstall 为了方便 uni-app 集成使用 openinstall 功能而开发的,实现了App传参安装,渠道统计(H5渠道、广告平台渠道、ASA渠道等),一键拉起全部功能。
openinstall
可帮助 Android/iOS 开发者精确的获取 App 每一次安装来源;在 App 安装或拉起后,直达指定场景,大大提高用户转化率和留存率。同时,openinstall 在精准的 app 安装来源跟踪的技术上,开发了免打包,跨平台的渠道统计功能,轻松创建与管理成千上万的渠道,实现线上线下全渠道覆盖。openinstall 统计数据完全独立于第三方平台,提供多维度的统计报表,实时客观地反映渠道效果。
使用前准备及说明
前往openinstall 官网,注册账户,登录管理控制台,创建应用后,跳过 "集成指引",在 "应用集成" 的对应平台的 "应用配置" 中获取appkey
和scheme
以及 iOS 的关联域名。
针对使用了 渠道统计 功能中的 广告渠道 效果监测功能的集成,需要参考补充文档
注意:为了适配苹果最新的ASA渠道统计API,插件版本1.5.4及以上版本中,iOS插件编译环境为Xcode 12.3,本地打包的用户需要注意。
1. 配置appkey
在 mainfest.json 的App原生插件配置的 openinstall 插件配置框内配置 openinstall 分配给应用的AppKey
2. 配置scheme
在 mainfest.json 的App常用其它配置中配置 openinstall 分配给应用的scheme
(获取scheme:openinstall应用控制台 -> Android集成 -> Android应用配置 -> scheme,iOS同理)
3. 配置Universal Links(iOS平台)
1)、开启Associated Domains服务
到苹果开发者网站,为当前的 AppID 开启关联域名(Associated Domains)服务:
2)、在新版HBuilderX里面配置关联域(Associated Domains)
示例如图:
以下是旧版本HBuilderX的关联域配置:
HBuilderX2.3.0开始云端打包支持配置Xcode中的Capabilities,包括关联域名(Associated Domains)配置参考文档
在HBuilderX中的manifest.json中配置关联域名:
在"plus" -> "distribute" -> "apple" -> "capabilities" -> "entitlements"节点(uni-app项目在"app-plus" -> "distribute" -> "ios" -> "capabilities" -> "entitlements")下添加"com.apple.developer.associated-domains"字段,字段值为字符串数组,每个字符串为要关联的域名
"capabilities": {
"entitlements": {
"com.apple.developer.associated-domains": [
"openinstall分配给应用的关联域名"
]
}
}
HBuilderX2.3.0之前,需将插件下载到本地修改package.json
中内容
"entitlements": {
"com.apple.developer.associated-domains": [
"openinstall为应用生成的关联域名"
]
}
然后再提交云端打包
参考本地uni-app原生插件提交云端打包
二、使用教程
1. 引用并初始化
const openinstall = uni.requireNativePlugin('openinstall-plugin');
必须先进行初始化,才能调用其他api
openinstall.init();
2. 快速安装
如果只需要快速安装功能,无需其它功能(App传参安装、渠道统计、一键拉起),完成初始化即可
3. 一键拉起
获取拉起数据
registerWakeUp(callback)
callback
: 数据回调函数
示例:
在App.vue
的onLaunch
方法中注册拉起回调
openinstall.registerWakeUp(function(result){
console.log('getWakeup : channel=' + result.channelCode + ', data=' + result.bindData);
});
4. App传参安装高级版功能
获取安装数据getInstall(seconds, callback)
seconds
: 回调超时时间callback
: 数据回调函数
示例:
openinstall.getInstall(
8,
function(result) {
console.log('getInstall : channel=' + result.channelCode + ', data=' + result.bindData
+ ', shouldRetry=' + result.shouldRetry);
}
);
5. 渠道统计高级版功能
SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。其它业务相关统计由开发人员使用 api 上报
5.1 注册统计
示例:
openinstall.reportRegister();
5.2 效果点统计reportEffectPoint(effectPointId, effectPointValue)
effectPointId
: 效果点IDeffectPointValue
: 效果点值,数值类型
示例:
openinstall.reportEffectPoint("effect_test", 1);
5.3 效果点明细统计reportEffectPoint(pointId, pointValue, extras)
pointId
: 效果点IDpointValue
: 效果点值,数值类型extras
: 效果点自定义参数和值,key和value都必须是string类型
示例:
var extras = {
"key1": "value1",
"key2": "value2",
}
openinstall.reportEffectPoint("effect_detail", 1, extras);
6. 裂变分享上报高级版功能
reportShare(shareCode, sharePlatform, callback)
shareCode
: 分享标识码(用户标识)platform
: 分享平台,参考官网定义的平台字符串callback
: 上报回调函数 示例:
备注:openinstall.reportShare("10001", "QQ", function(ret) { console.log('shouldRetry = ' + ret.shouldRetry + ', message = ' + ret.message); if(ret.shouldRetry){ console.log('上报失败,请重试'); } });
platform
分享平台,具体传入字段,参考文档裂变分享平台列表
三、导出apk/ipa包并上传
- 代码集成完毕后,需要导出安装包上传openinstall后台,openinstall会自动完成所有的应用配置工作。
- 上传完成后即可开始在线模拟测试,体验完整的App安装/拉起流程;待测试无误后,再完善下载配置信息。
下面是apk包的上传界面(后台截图):
广告接入补充文档
Android平台
(1)针对广告平台接入,新增配置接口,在调用 init 之前调用。参考广告平台对接Android集成指引
var options = {
adEnabled: true,
oaid: "通过移动安全联盟获取到的 oaid",
gaid: "通过 google api 获取到的 advertisingId",
}
openinstall.configAndroid(options);
例如: 开发者自己获取到了 oaid,但是需要 openinstall 获取 gaid,则配置参数为
var options = {
adEnabled: true,
oaid: "通过移动安全联盟获取到的 oaid",
gaid: null,
}
(2) 为了精准地匹配到渠道,需要获取设备唯一标识码,因此需要在manifest.json
中声明权限,在 “App模块权限配置” 的 “Android打包权限配置” 勾选上<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
(3)在manifest.json
中设置,关闭uni-app
自动获取android.permission.READ_PHONE_STATE
权限
{
"app-plus" : {
"distribute" : {
"android" : {
"permissionPhoneState" : {
"request" : "none",
"prompt" : ""
},
}
}
}
}
(4)在App.vue
的onLaunch
方法中进行初始化,先申请权限,之后进行配置和初始化
if (plus.os.name == "Android") {
plus.android.requestPermissions(["android.permission.READ_PHONE_STATE"], function(event) {
if(event.granted){
console.log(event.granted);
}
if(event.deniedPresent){
console.log(event.deniedPresent);
}
if(event.deniedAlways){
console.log(event.deniedAlways);
}
// 配置初始化,设置 OAID 和 GAID
var options = {
adEnabled: true,
oaid: null,
gaid: null,
}
openinstall.configAndroid(options);
// 权限申请成功,不管用户是否同意,都需要做初始化
openinstall.init();
// 初始化完成后,才能做其他api调用
openinstall.registerWakeUp(function(result) {
console.log('wakeup : channel=' + result.channelCode + ', data=' + result.bindData);
});
}, function(event) {
// 权限申请错误
})
}
iOS平台
包括广告平台渠道统计和ASA渠道:
广告平台渠道:
openinstall后台配置及上架指引可参考文档广告平台对接iOS集成指引
(1)需在manifest.json的 “App常用其它设置” 中配置勾选 “使用广告标识(IDFA)”
(2)下载官方插件iOS平台获取idfa,并保存到目录下,如js_sdk/dc-idfa/idfa.js
(3)在App.vue
中引用此模块,如下:
import idfa from "@/js_sdk/dc-idfa/idfa.js"
(4)在App.vue
的onLaunch
方法中进行初始化,如下:
if('iOS' == plus.os.name){
var fid = "";
fid = idfa.value();//如果需要idfa则开启
openinstall.init(fid);
console.log(fid);
};
ASA渠道:
插件1.5.4及以上版本增加了ASA渠道统计功能,已经集成在SDK内部,只需配置增加少量代码。开发者可以通过getInstall
方法获取channelCode
对应的值,即为ASA渠道编号。
区分ASA渠道和H5渠道及其它渠道,可在openinstall开发者平台创建渠道时,创建不同的渠道编号来做区分,如asa+广告系列ID
,例子:asa_1234567890
。
//配置asa,也可同时配置idfa
//isDev:"1"是测试模式,可以测试1234567890渠道下的统计数据,正式环境下请去掉该设置
var options = {
asa: "1",
isDev: "1",//正式上线前务必注释或删除该设置,否则会影响安装参数还原
//idfa: null,
}
openinstall.initAdsAttribution(options);
注意:初始化方法只能调用其中一个,即如果使用了openinstall.initAdsAttribution(options);方法,则不需要使用openinstall.init(fid);方法
注意:广告平台统计里面,获取idfa申请权限的方法,需要在app becomes active的时候调用,避免弹窗无法正常弹出的情况出现。
如何在openinstall开发者平台创建ASA渠道,并实现统计功能和上架前测试,请看图文文档ASA渠道使用指南