unity3d 接入指引

获取 package 和文档

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替换至相应位置

自定义配置

• 如果项目已存在自己的AndroidManifest.xml文件，根据下图标注的内容做相应的更改
  

• 如果需要使用自己的拉起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相关字段说明如下：

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集成指南