unity3d 接入指引
openinstall 已为开发者打包生成了 unitypackage ,只需将 package 拖拽到工程中并导入所有文件,然后按照文档做少量配置即可使用 openinstall 提供的所有功能
一、导入openinstall.unitypackage
右击Assets
,选择Import Package
中的Custom Package...
在文件选择框中选中openinstall.unitypackage
,导入所有文件
将Assets/Plugins/OpenInstall
下的OpenInstall.prefab
拖入对应的场景中使用 openinstall 实现业务逻辑
二、平台配置
请根据 使用指南 来做对应的配置
使用openinstall第三方插件文档集成时,如何快速获取AppKey、Associated Domains和scheme,下图为iOS相关配置信息(Android同理):
1. iOS平台
无需写一句Object-C代码,只需进行如下配置
备注:
- 如果工程中已使用了
IMPL_APP_CONTROLLER_SUBCLASS
宏生成的customAppController.mm文件(或其它自定义名称),请在该文件中添加一键拉起的回调方法,并删除掉openinstall插件中 Assets/Plugins/iOS/libs 目录下的CustomAppController.mm
文件;
1.1 配置appKey
在 Info.plist 文件中配置 appKey 键值对,如下:
<key>com.openinstall.APP_KEY</key>
<string>从openinstall官网后台获取应用的appkey</string>
以下为iOS一键拉起功能相关配置
1.2 配置universal links(适用于iOS9.0以后)
1)到苹果开发者网站,为当前的 AppID 开启关联域名(Associated Domains)服务:
2)在 Xcode 中配置 openinstall 为当前应用生成的关联域名(Associated Domains)(openinstall应用控制台 -> iOS集成 -> iOS应用配置 -> 关联域名(Associated Domains)):
1.3 配置scheme(适用于iOS9以下)
在Xcode里选中 Target -> Info -> URL Types,配置 openinstall 为当前应用生成的 Scheme,如图所示:
2. Android 平台
简单配置
将sample/Android
目录中的AndroidManifest.xml
文件拷贝到项目的Assets/Plugin/Android/
目录下,并修改文件内容:将 openinstall 为应用分配的appkey
和scheme
替换至相应位置
自定义配置
如果需要使用自己的拉起
Activity
,可参考sample/Android/src
目录中的OiUnityActivity.java
在拉起Activity
的onCreate(Bundle savedInstanceState)
和onNewIntent(Intent intent)
中添加拉起处理代码
三、使用指南
导入空间命令并获取实例
使用OpenInstall
之前,请先导入命名空间
using io.openinstall.unity;
然后通过GameObject
获取OpenInstall
实例
private OpenInstall openinstall;
void Start () {
openinstall = GameObject.Find("OpenInstall").GetComponent<OpenInstall>();
}
1. 初始化
确保用户同意《隐私政策》之后,再初始化 openinstall。参考应用合规指南
openinstall.Init();
2. 快速安装
如果只需要 快速安装 功能,无需其它功能(App传参安装、渠道统计、一键拉起),完成初始化相关工作即可
3. 一键拉起
完成文档前面iOS和Android介绍的一键拉起相关配置
获取拉起数据
在Start
方法中,获取到实例之后注册拉起回调,这样当 拉起App 时,会回调方法,并可在回调中获取拉起数据
openinstall.RegisterWakeupHandler(getWakeupFinish);
public void getWakeupFinish(OpenInstallData wakeupData)
{
Debug.Log("OpenInstallUnity getWakeupFinish : 渠道编号=" +wakeupData.channelCode
+ ", 自定义数据=" + wakeupData.bindData);
}
4. App传参安装高级版功能
获取安装数据
在应用需要安装参数时,调用以下 api 获取由 SDK 保存的安装参数,可设置超时时长(一般为8~15s),单位秒
openinstall.GetInstall(10, getInstallFinish);
public void getInstallFinish(OpenInstallData installData)
{
Debug.Log("OpenInstallUnity getInstallFinish : 渠道编号=" + installData.channelCode
+ ",自定义数据=" + installData.bindData
+ ",是否需要重试=" + installData.shouldRetry);
}
_备注:
- 注意这个安装参数尽量不要自己保存,在每次需要用到的时候调用该方法去获取,因为如果获取成功sdk会保存在本地
- 该方法可重复获取参数,如需只要在首次安装时获取,可设置标记,详细说明可参考openinstall官网的常见问题
5. 渠道统计高级版功能
SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。其它业务相关统计由开发人员代码埋点上报
5.1 注册上报
在用户注册成功后,调用接口上报注册量
openinstall.ReportRegister();
5.2 效果点上报
统计终端用户对某些特殊业务的使用效果,如充值金额,分享次数等等。调用接口前,请先进入 openinstall 管理后台 “效果点管理” 中添加效果点,第一个参数对应管理后台 效果点ID
openinstall.ReportEffectPoint("effect_test", 1);
5.3 效果点明细统计请在openinstall 控制台的 “效果点管理” 中添加对应的效果点,并启用“记录明细”,添加自定义参数
Dictionary<string,string> extraDict = new Dictionary<string, string>();
extraDict.Add("k1", "v1");
extraDict.Add("k2", "v2");
openinstall.ReportEffectPoint("effect_detail", 1, extraDict);
6. 裂变分享高级版功能
分享上报主要是统计某个具体用户在某次分享中,分享给了哪个平台,再通过JS端绑定被分享的用户信息,进一步统计到被分享用户的激活回流等情况。
openinstall.ReportShare("123456", "QQ", reportFinish);
可根据返回的数据中的shouldRetry
决定是否需要重试,以及message
查看失败的原因
public void reportFinish(OpenInstallData installData)
{
Debug.Log("OpenInstallUnity reportFinish : shouldRetry=" + installData.shouldRetry);
}
四、导出apk/ipa包并上传
- 代码集成完毕后,需要导出安装包上传openinstall后台,openinstall会自动完成所有的应用配置工作。
- 上传完成后即可开始在线模拟测试,体验完整的App安装/拉起流程;待测试无误后,再完善下载配置信息。
下面是apk包的上传界面(后台截图):
五、广告补充文档
Android 平台
1、针对广告平台接入,新增配置接口,在调用 init 之前调用。参考广告平台对接Android集成指引
OpenInstallParam param = new OpenInstallParam();
param.adEnabled = true;
openinstall.Config(param);
OpenInstallParam 中Android相关字段说明如下:
参数名 | 参数类型 | 描述 |
---|---|---|
adEnabled | bool | 是否需要 SDK 获取广告追踪相关参数 |
macDisabled | bool | 是否禁止 SDK 获取 mac 地址 |
imeiDisabled | bool | 是否禁止 SDK 获取 imei |
gaid | string | 通过 google api 获取到的 advertisingId,SDK 将不再获取gaid |
oaid | string | 通过移动安全联盟获取到的 oaid,SDK 将不再获取oaid |
2、为了精准地匹配到渠道,需要获取设备唯一标识码(IMEI),因此需要做额外的权限申请
在 AndroidManifest.xml 中添加权限声明
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
3、在权限申请成功后,再进行openinstall初始化。无论终端用户是否同意,都要调用初始化
注意:
openinstall.Init(permission);
接口已移除,请自行进行权限申请。
iOS平台
分为广告平台渠道统计和ASA渠道统计
1、UnityFramework中需导入相关的库文件,IDFA库文件为AdSupport.framework
,ASA库文件为AdServices.framework
2、针对广告平台接入,新增配置 Config 接口,在调用 Init 之前调用(Unity层传入idfa,ASA等相关参数 ):
OpenInstallParam param = new OpenInstallParam();
param.idfa = "获取的idfa值";
param.ASAEnabled = true;//开启ASA渠道统计
openinstall.Config(param);
注意:广告平台统计里面,获取idfa申请权限的方法,需要在app becomes active的时候调用,避免弹窗无法正常弹出的情况出现。
3、如果需要使用广告平台渠道统计功能,参考官网文档,配置plist:
参考广告平台渠道 iOS集成指南,开启后台开关,并配置Info.plist文件,添加IDFA的权限申请描述,详细如下:
<key>NSUserTrackingUsageDescription</key>
<string>通过后可用于广告的追踪定位(文案自定)</string>
4、如果需要使用ASA渠道统计功能,则需要替换为集成了ASA的代码文件:
在完成导入openinstall.unitypackage包后,将Assets/Plugins/iOS/libs
目录下的OpenIsntallUnity3DBridge.m
文件,替换为sample/iOS/ad-track/
目录下的OpenIsntallUnity3DBridge.m
文件
ASA渠道统计其它配置可参考ASA渠道 iOS集成指南