cordova-plugin-xinstall

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

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

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

前期准备

  1. 在Xinstall官网注册自己的账号
  2. 创建应用,获得需要使用的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 事件回调之时注册

// 第一种回调方法 只有是wakeup 操作才会回调------------
window.xinstall.registerWakeUpHandler(function(data) {
       // 对data进行处理
}, function(msg){
       console.log("xinstall.wakeup error : " + msg)
});
// -----------------------------------------------

// 第二种回调方法, 只要调用方法,就一定有回调------------
 window.xinstall.registerWakeUpDetailHandler(function(data) {
       // 对data进行处理
},function(msg) {
        console.log("xinstall.registerWakeUpDetailHandler : " + msg)
});
//-----------------------------------------------------

【注】:两种回调方法选择一个使用。

两种回调返回的data格式分别为:

// 第一种回调的json 数据
{
    "channelCode":"渠道编号",  // 字符串类型。渠道编号,没有渠道编号时为 ""
    "data":{                                    // 对象类型。唤起时携带的参数。
        "co":{                                // co 为唤醒页面中通过 Xinstall Web SDK 中的点击按钮传递的数据,key & value 均可自定义,key & value 数量不限制
            "自定义key1":"自定义value1", 
            "自定义key2":"自定义value2"
        },
        "uo":{                               // uo 为唤醒页面 URL 中 ? 后面携带的标准 GET 参数,key & value 均可自定义,key & value 数量不限制
            "自定义key1":"自定义value1",
            "自定义key2":"自定义value2"
        }
    }
}

// 第二种回调的json 数据
{
  "wakeUpData":
  {
    "channelCode":"渠道编号",  // 字符串类型。渠道编号,没有渠道编号时为 ""
    "data":{                                    // 对象类型。唤起时携带的参数。
        "co":{                                // co 为唤醒页面中通过 Xinstall Web SDK 中的点击按钮传递的数据,key & value 均可自定义,key & value 数量不限制
            "自定义key1":"自定义value1", 
            "自定义key2":"自定义value2"
        },
        "uo":{                               // uo 为唤醒页面 URL 中 ? 后面携带的标准 GET 参数,key & value 均可自定义,key & value 数量不限制
            "自定义key1":"自定义value1",
            "自定义key2":"自定义value2"
        }
    }
  },
  "error": 
  {
    "errorType" : 7,                    // 数字类型。代表错误的类型,具体数字对应类型可在下方查看
    "errorMsg" : "xxxxx"            // 字符串类型。错误的描述
  }
}
/**   errorType 对照表:
*   iOS
*   -1 : SDK 配置错误;
*   0 : 未知错误;
*   1 : 网络错误;
*   2 : 没有获取到数据;
*   3 : 该 App 已被 Xinstall 后台封禁;
*   4 : 该操作不被允许(一般代表调用的方法没有开通权限);
*   5 : 入参不正确;
*   6 : SDK 初始化未成功完成;
*   7 : 没有通过 Xinstall Web SDK 集成的页面拉起;
*
*   Android
*   1006 : 未执行init 方法;
*   1007 : 未传入Activity,Activity 未比传参数
*   1008 : 用户未知操作 不处理
*   1009 : 不是唤醒执行的调用方法
*   1010 : 前后两次调起时间小于1s,请求过于频繁
*   1011 : 获取调起参数失败
*   1012 : 重复获取调起参数
*   1013 : 本次调起并非为XInstall的调起
*   1004 : 无权限
*   1014 : SCHEME URL 为空
*/

iOS 由于使用Universal Link 技术

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

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

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

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

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":""},"isFirstFetch":true}
// uo 为页面参事
// co 为点击参数
// isFirstFetch 是否第一次获取安装参数

5. 事件统计相关

5.1 注册量统计

window.xinstall.reportRegister();

5.2 渠道效果统计

window.xinstall.reportEffectEvent(eventId, eventVal);

补充说明

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

5.3 事件明细统计

除了旧有事件业务,我们还开发了事件明细统计,用来统计各个事件具体发生情况。

1.5.7 及以后版本可用

在使用之前要现在后台管理系统中打开该事件明细统计功能,具体如下:

在开启权限之后,我们直接使用Xinstall SDK 的reportEventWhenOpenDetailInfo方法上传单个事件的第二个详细值

window.xinstall.reportEventWhenOpenDetailInfo(eventId, eventVal,eventSubValue);

最终在事件列表中可以点击查看查阅具体详情的内容

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

  1. 接入IMEI需要额外的全下申请,需要在AndroidManifest中添加权限声明

    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    
  2. 如果使用OAID,因为内部使用反射获取oaid 参数,所以都需要外部用户接入OAID SDK 。具体接入参考《Android集成指南》

6.2、更换初始化方法

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

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

入参说明:需要主动传入参数,字典

入参内部字段:

  • iOS 端:

    参数名 参数类型 描述
    idfa 字符串 iOS 系统中的广告标识符
    asaEnable boolean 是否开启 ASA 渠道,不需要时可以不传。详见《8. 苹果搜索广告(ASA)渠道功能》
  • Android 端:

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

调用示例

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

在使用了广告平台渠道后,若您的 App 需要上架,请认真阅读本段内容。

7.3.1 iOS 端:上架 App Store
  1. 如果您的 App 没有接入苹果广告(即在 App 中显示苹果投放的广告),那么在提交审核时,在广告标识符中,请按照下图勾选:

IDFA

  1. 在 App Store Connect 对应 App —「App隐私」—「数据类型」选项中,需要选择:“是,我们会从此 App 中收集数据”

AppStore_IDFA_1

在下一步中,勾选「设备 ID」并点击【发布】按钮:

AppStore_IDFA_2

点击【设置设备 ID】按钮后,在弹出的弹框中,根据实际情况进行勾选:

  • 如果您仅仅是接入了 Xinstall 广告平台而使用了 IDFA,那么只需要勾选:第三方广告
  • 如果您在接入 Xinstall 广告平台之外,还自行使用 IDFA 进行别的用途,那么在勾选 第三方广告 后,还需要您根据您的实际使用情况,进行其他选项的勾选

AppStore_IDFA_3

AppStore_IDFA_4

勾选完成后点击【下一步】按钮,在 “从此 App 中收集的设备 ID 是否与用户身份关联?” 选项中,请根据如下情况进行选择:

  • 如果您仅仅是接入了 Xinstall 广告平台而使用了 IDFA,那么选择 “否,从此 App 中收集的设备 ID 未与用户身份关联”
  • 如果您在接入 Xinstall 广告平台之外,还自行使用 IDFA 进行别的用途,那么请根据您的实际情况选择对应的选项

AppStore_IDFA_5

最后,在弹出的弹框中,选择 “是,我们会将设备 ID 用于追踪目的”,并点击【发布】按钮:

AppStore_IDFA_6

7.3.2 Android 端

无特殊需要注意,如碰上相关合规问题,参考 《应用合规指南》

8. 苹果搜索广告(ASA)渠道功能

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

8.1 更换初始化方法

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

initWithAd

入参说明:需要主动传入参数,JSON对象

入参内部字段:

  • iOS 端:

    参数名 参数类型 描述
    idfa string iOS 系统中的广告标识符(不需要时可以不传)
    asaEnable boolean 是否开启 ASA 渠道,true 时为开启,false 或者不传时均为不开启

回调说明:无需传入回调函数

调用示例

// idfa 为广告传入参数,如果未使用到,可以不传入
window.xinstall.initWithAd({asaEnable:true},function() {
       // 初始化回调 为选传参数
       window.xinstall.getInstallParams(function(data){

       }, 10);
 });

可用性

iOS系统

可提供的 1.5.5 及更高版本

导出apk/ipa包并上传

参考官网文档

iOS集成-导出ipa包并上传

Android-集成

如何测试功能

参考官方文档 测试集成效果

更多 Xinstall 进阶功能

若您想要自定义下载页面,或者查看数据报表等进阶功能,请移步 Xinstall 官网 查看对应文档。

若您在集成过程中如有任何疑问或者困难,可以随时联系 Xinstall 官方客服 在线解决。

results matching ""

    No results matching ""