cordova-plugin-xinstall

本模块是为了方便 Cordova 开发同学接入而封装的 SDK

【重要说明】：从 v1.5.0 版本（含）开始，调用 Xinstall 模块的任意方法前，必须先调用一次初始化方法（init 或者 initWithAd），否则将导致其他方法无法正常调用。

从 v1.5.0 以下升级到 v1.5.0 以上版本后，需要自行修改代码调用初始化方法，Xinstall 模块无法在升级后自动兼容。

前期准备

在Xinstall官网注册自己的账号
创建应用，获得需要使用的appKey 和 scheme

安装插件

执行下列命令安装并配置xinstall插件

cordova plugin add cordova-plugin-xinstall --variable XINSTALL_APPKEY={AppKey} --variable XINSTALL_SCHEME={Scheme}

客户端配置

1. Android

Android 不需要任何配置

2. iOS

在xxx-Info.plist 文件中需要添加

<key>com.xinstall.APP_KEY</key>
<string>{appKey}</string>

调用API

1.快速下载

如果只需要快速下载功能，无需其它功能（携带参数安装、渠道统计、一键拉起），完成初始化即可(这里指安装插件)

2.初始化SDK

window.xinstall.init();

3. 一键拉起

拉起参数获取

调用以下代码注册拉起回调，应尽早调用。如在 deviceready 事件回调之时注册

window.xinstall.registerWakeUpHandler(function(data) {
       // 对data进行处理
}, function(msg){
       console.log("xinstall.wakeup error : " + msg)
});

Xinstall 通过 Scheme(iOS < 9) 和 universal link（iOS≥9） ,在app已安装的情况下，从各种浏览器（包括微信、QQ、新浪微博、钉钉等主流社交软件的内置浏览器）拉起app并传递动态参数，避免重复安装。

3.1 通用链接集成（Universal Link)

首先，我们需要到苹果开发者网站，为当前的 App ID 开启关联域名 (Associated Domains) 服务：

为刚才开发关联域名功能的 App ID 创建新的（或更新现有的）描述文件，下载并导入到Xcode中(通过xcode自动生成的描述文件，可跳过这一步)：

在Xcode中配置Xinstall为当前应用生成的关联域名 (Associated Domains) ：applinks:xxxx.xinstall.top 和 applinks:xxxx.xinstall.net

具体的关联域名可在 Xinstall管理后台 - 对应的应用控制台 - iOS下载配置页面中找到

3.2 集成Scheme

此方法为XinstallSDK 1.2.2最新添加的方法，如果使用报错，请先更新SDK 更多问题见iOS常见问题

3.2.1 在Xcode选中Target -> Info -> URL Types,配置Xinstall 为当前应用生成的 Scheme,如图所示：

图中4中的值为实例值，具体为xi+appkey格式，如xi4z9yxu8，您也可以在iOS集成-功能集成-一键拉起的文档中找到您对应的Scheme值

4. 携带参数安装

window.xinstall.getInstallParams(function(data) {
        //对安装data进行处理
}, function(msg){
        console.log('xinstall.getInstall error: ' + msg);
}, 15);

【注】过期时间只有androidSDK 提供，后期可能会去除。

成功回调的data数据为

{"channelCode":"渠道号","timeSpan":"获取数据间隔时间","data":{"uo":"{\"testkey\":\"1111\"}","co":""}}
// uo 为页面参事
// co 为点击参数

您可以在 Xinstall 管理后台对应的 App 内，看到所有的传递参数以及参数出现的次数，方便你们做运营统计分析，如通过该报表知道哪些页面或代理带来了最多客户，客户最感兴趣的 App 页面是什么等。具体参数名和值，运营人员可以和技术协商定义，或联系 Xinstall 客服咨询。具体效果如下图：

5. 渠道统计相关

5.1 注册量统计

window.xinstall.reportRegister();

5.2 渠道效果统计

window.xinstall.reportEffectEvent(eventId, eventVal);

补充说明

只有 Xinstall 后台创建事件统计，并且代码中 传递的事件ID 与 后台创建的ID 一致时，上报数据才会被统计。

6. 广告平台渠道功能

如果您在 Xinstall 管理后台对应 App 中，只使用「自建渠道」，而不使用「广告平台渠道」，则无需进行本小节中额外的集成工作，也能正常使用 Xinstall 提供的其他功能。

注意：根据目前已有的各大主流广告平台的统计方式，目前 iOS 端和 Android 端均需要用户授权并获取一些设备关键值后才能正常进行 [ 广告平台渠道 ] 的统计，如 IDFA / OAID / GAID 等，对该行为敏感的 App 请慎重使用该功能。

6.1 配置工作

iOS 端：

在 Xcode 中打开 iOS 端的工程，在 Info.plist 文件中配置一个权限作用声明（如果不配置将导致 App 启动后马上闪退）：

<key>NSUserTrackingUsageDescription</key>
<string>这里是针对获取 IDFA 的作用描述，请根据实际情况填写</string>

在 Xcode 中，找到 App 对应的「Target」，再点击「General」，然后在「Frameworks, Libraries, and Embedded Content」中，添加如下两个框架：

AppTrackingTransparency.framework
AdSupport.framework

Android 端：

相关接入可以参考广告平台联调指南中的《Android集成指南》

接入IMEI需要额外的全下申请，需要在AndroidManifest中添加权限声明
```
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
```
如果使用OAID，因为内部使用反射获取oaid 参数，所以都需要外部用户接入OAID SDK 。具体接入参考《Android集成指南》

6.2、更换初始化方法

使用新的 initWithAd 方法，替代原先的 init 方法来进行模块的初始化

iOS 端使用该方法时，需要传入 IDFA（在 JS 脚本内）。您可以使用任意方式在 JS 脚本中获取到 IDFA，例如第三方获取 IDFA 的模块。

入参说明：需要主动传入参数，字典

入参内部字段：

iOS 端：

参数名参数类型描述

idfa 字符串 iOS 系统中的广告标识符

参数名	参数类型	描述
idfa	字符串	iOS 系统中的广告标识符

Android 端：

参数名	参数类型	描述
adEnabled	boolean	是否使用广告功能
oaid （可选）	string	OAID
gaid（可选）	string	GaID(google Ad ID)

调用示例

  // oaid和gaid 为选传，不传则代表使用SDK自动去获取（SDK内不包括OAID SDK，需要自己接入）
  xinstall.initWithAd({adEnabled:true,idfa:"idfa需要自己传入",oaid:"oaid测试",gaid:"测试"});
  // 如果希望在完成初始化，立即执行之后的步骤可以通过 下列代码实现-------------------------
  //window.xinstall.initWithAd({adEnable:true,idfa:"外部获取的idfa"},function() {
    //        window.xinstall.getInstallParams 或者 window.xinstall.registerWakeUpHandler 等操作
    //});
  //-----------------------------------------------------------------------------