xinstall

YonBuilder移动开发接入

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

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

一、概述

Xinstall 支持 YonBuilder移动开发 平台的插件接入,你可以在 YonBuilder移动开发-工作台 ,打开一个应用,插件库中搜索找到 Xinstall 插件,添加Xinstall 插件。

本插件封装了 Xinstall 官方 SDK,是集智能传参、快速安装、一键拉起、客户来源统计等功能,帮您提高拉新转化率、安装率和多元化精确统计渠道效果的产品。为用户提供点击、安装、注册、留存、活跃等等精准统计报表,并可实时排重,杜绝渠道流量猫腻,大大降低运营成本。 具体详细介绍可前往 Xinstall 官网 进行查看。

二、如何接入

1、添加 Xinstall 插件

在 YonBuilder移动开发 控制台中,找到需要接入的 YonBuilder移动开发 应用,点击【插件】按钮,再点击【插件库】,搜索 “xinstall”,找到插件后,点击插件右上角【+】按钮,将插件集成进入该 App(点击后该按钮变为灰色的已添加字样):

2、创建 Xinstall 应用

进入 Xinstall 官网 注册账号,并在控制台中创建一个对应的应用,应用名字可以任意填写: 注意记录 Xinstall 中新创建应用的 appkey(后续配置需要用到):

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

3、初始化配置

进入 YonBuilder移动开发 应用的工程,配置工程目录下的 config.xml 文件,配置完毕,必须通过应用打包生效,配置方法如下:

参数:urlScheme、appKey

3.1、配置 config.xml 文件

配置示例:

<permission name="internet" />
<preference name="urlScheme" value="将这里替换成 Xinstall 官方自动分配的 scheme" />
// Android
<meta-data name="com.xinstall.APP_KEY" value="将这里替换成 Xinstall 官方自动分配的 appKey" />
// iOS
<feature name="xinstall">
    <param name="com.xinstall.APP_KEY" value="将这里替换成 Xinstall 官方自动分配的 appKey" />
</feature>

字段介绍:

  • internet:添加网络权限
  • urlScheme:如需使用一键拉起功能则必须配置。urlScheme 的 value 值详细获取位置:Xinstall 应用控制台 -> Android下载配置 中获取
  • com.xinstall.APP_KEY:必须配置。插件接入前准备工作时,从 Xinstall 平台获取的 AppKey

示例图片(示例图片中开发工具均为 YonBuilder移动开发 Studio ):

###3.2、Info.plist 相关配置(针对iOS) **进入 YonBuilder移动开发 应用工程的 res 目录下(该目录与 config.xml 同级)新增 Info.plist 文件,配置完毕,必须通过应用打包生效,配置方法如下: **

配置示例:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.xinstall.APP_KEY</key>
  <string>Xinstall 分配给应用的 appkey</string>
</dict>
</plist>

示例图片:

补充说明

如果你的工程中已经在 res 中添加了 Info.plist 文件,则直接在文件的<dict></dict>之间添加如下键值对即可:

  <key>com.xinstall.APP_KEY</key>
  <string>Xinstall 分配给应用的 appkey</string>

###3.3、Universal links 相关配置(针对 iOS) 开启 Associated Domains 服务

对于 iOS,为确保能正常使用一键拉起功能,AppID 必须开启 Associated Domains 功能,请到苹果开发者网站,选择 “Certificate, Identifiers & Profiles”,再选择 iOS 对应的 AppID,开启 Associated Domains:

注意:当 AppID 重新编辑过之后,需要更新相应的 mobileprovision 描述文件并下载。下载后,需要在 YonBuilder移动开发 管理后台对应的 App 中,进入左侧菜单栏中的「证书」页面,更新「iOS 证书」中对应环境的描述文件。更新完成后,应用打包时才能使用最新的这份描述文件。

若对制作证书和描述文件的过程有疑问,可以参考 YonBuilder移动开发 的官方文章:iOS证书及描述文件制作流程

配置 Universal links 关联域名

关联域名 (Associated Domains) 的值请在 Xinstall 控制台获取(Xinstall 应用控制台 -> iOS下载配置)

该文件是给 iOS 平台配置的文件,在网页工程的 res 目录下(该目录与 config.xml 同级)下创建文件名为 UZApp.entitlements 的文件,UZApp.entitlements 内容如下:

注意:一共需要配置2个关联域名

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key><!--固定key值-->
    <array>
     <!--以下两个关联域名均换成你在 xinstall 后台的关联域名(Associated Domains)-->
        <string>applinks:xxxxxx.xinstall.top</string>
        <string>applinks:xxxxxx.xinstall.net</string>
    </array>
</dict>
</plist>

示例图片:

4、导出包上传 Xinstall

代码集成完毕后,需要通过应用打包导出 iOS 和 Android 安装包,并上传 Xinstall 控制台里对应的 App:

示例图片(iOS 端):

示例图片(Android 端):

上传完包后,需要进入「iOS下载配置」和「Android下载配置」中选择下载的包的版本

示例图片(iOS 端):

示例图片(Android 端):

注意:每次上传完新的 ipa 或者 apk 包后,均需要进入「iOS下载配置」和「Android下载配置」中重新选择下载的包的版本

三、如何使用

1、快速下载和一键拉起

如果只需要快速下载功能和一键拉起,无需其它功能(携带参数安装、渠道统计),完成初始化配置即可。其他影响因素如下图

2、初始化 Xinstall 插件

注意:从 v1.5.0 版本开始,在调用 Xinstall 插件的任意方法之前,必须调用一次初始化方法,只需要调用一次即可,不需要反复调用。

v1.5.0 之前的版本会在启动时自动初始化,无需调用,也无法调用。

init

初始化方法。在调用 Xinstall 插件其他方法之前必须调用一次该方法,否则其他方法均无法正常执行。

示例代码

init()

入参说明:无需主动传入参数

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

调用示例

var xinstall = api.require('xinstall');
xinstall.init();

可用性

Android系统,iOS系统

可提供的 1.5.0 及更高版本

3、携带参数安装/唤起

注意:调用该功能对应接口时需要在 Xinstall 中为对应 App 开通专业版服务

在 APP 需要安装参数时(在 web 中下载并安装 App 完成后,由 web 网页中传递过来的,如邀请码、游戏房间号等动态参数),调用 addInstallEventListener 接口添加监听,在回调中获取 web 中传递过来的参数。

在 App 需要唤醒参数时(手机已经安装 App 时,在 web 中直接通过 Universal Links / scheme 一键拉起 App),首先在 App 启动时预先调用 addWakeUpEventListeneraddWakeUpDetailEventListener接口添加监听,在回调中获取 web 中传递过来的参数。

3.1、携带参数安装

addInstallEventListener

添加携带参数安装事件监听者。在 App 启动时(入口程序处,一般为 apiready 中)需要通过该方法添加监听者。监听回调函数里可保存安装参数供后续业务使用。

示例代码

addInstallEventListener({}, callback(ret, err))

入参说明:无需主动传入参数,直接传入 {} 即可

回调说明:传入监听回调 callback(ret, err)

ret:

类型:JSON对象

内部字段:

// 如果没有获取到安装时携带的参数,result 为一个空 json 对象:
{}

// 获取到了安装时携带的参数,result 为 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"
        }
    },
    "timeSpan": 12, // 数字类型。代表下载页面上点击开始下载按钮与第一次打开App时的时间间隔,单位为秒
    "isFirstFetch": true // boolean类型。代表是否为第一次获取到安装参数,只有第一次获取到时为 true
}

调用示例

var xinstall = api.require('xinstall');
xinstall.addInstallEventListener({}, function(ret, err) {
  // 回调函数将在合适的时机被调用,这里编写拿到渠道编号以及携带参数后的业务逻辑代码

  // 空对象时代表没有获取到安装参数
  if (JSON.stringify(ret) == '{}') {
    // 业务逻辑
  } else {
    var channelCode = ret.channelCode;
    var data = ret.data;
    var co = data.co;
    var uo = data.uo;
    var timeSpan = ret.timeSpan;
    var isFirstFetch = ret.isFirstFetch;
    // 根据获取到的数据做对应业务逻辑
  }
});

补充说明

此接口用于获取动态安装参数(由 web 网页中传递过来的,如邀请码、游戏房间号等自定义参数),测试时必须先卸载 App,再安装,才能正确获取参数。在回调中获取到参数后,可实现跳转指定页面、统计渠道数据等场景。调用该函数的时机建议越早越好,尽量在程序启动时的 apiready 内进行注册,以免错过回调时机。

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

传参报表

可用性

Android系统,iOS系统

可提供的 1.1.0 及更高版本

3.2、携带参数唤起

您可以在下述两种回调方法中任选一个进行实现,不同的回调方法有不同的逻辑,请选择最符合您实际场景的方法进行实现,请勿同时实现两个方法。

【方法一】:addWakeUpEventListener() 该方法只会在成功获取到拉起参数时,才会回调。如果无法成功获取到拉起参数,例如不是集成了 Xinstall Web SDK 的页面拉起您的 App 时,将会无法获取到拉起参数,也就不会执行该回调方法。

addWakeUpEventListener

添加唤醒页面事件监听者。在 JS 中获取到 api 对象(由 YonBuilder移动开发 官方提供)的 appintent 事件回调后,可通过该方法添加监听者。监听回调函数里可保存唤醒参数供后续业务使用。

示例代码

addWakeUpEventListener({uri:ret}, callback(ret, err))

入参说明:{uri:ret} 为 appintent 事件回调数据

回调说明:传入监听回调 callback(ret, err)

ret:

类型:JSON对象

内部字段:

// 如果唤醒时没有携带任何参数,result 为一个空 json 对象:
{}

// 如果唤醒时有任意参数,result 为 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"
        }
    }
}

调用示例

// 如果你的应用(安卓端)需要支持在 微信/QQ/QQ浏览器 内通过应用宝拉起,在调用 addWakeUpEventListener 方法前,请先调用一次 openYYBFunction 方法;若不需要支持,则无需调用 openYYBFunction 方法
var xinstall = api.require('xinstall');
xinstall.openYYBFunction({});


// 请严格遵循如下调用顺序,否则可能导致获取不到唤醒参数
var xinstall = api.require('xinstall');
api.addEventListener({
  name:'appintent'
},function(ret,err){
  xinstall.addWakeUpEventListener({'uri': ret}, function(ret, err) { // 唤醒参数
    // 回调函数将在合适的时机被调用,这里编写拿到渠道编号以及携带参数后的业务逻辑代码
    
    // 空对象时代表唤醒了,但是没有任何参数传递进来
    if (JSON.stringify(ret) == '{}') {
      // 业务逻辑
    } else {
      var channelCode = ret.channelCode;
      var data = ret.data;
      var co = data.co;
      var uo = data.uo;
      // 根据获取到的数据做对应业务逻辑
    }
    
  });
});

补充说明

此方法用于获取动态唤醒参数,在拉起 APP 时,获取由 web 网页中传递过来的,如邀请码、游戏房间号等自定义参数,通过预先注册监听后,在回调中获取 web 端传过来的自定义参数。请严格遵循示例中的调用顺序,否则可能导致获取不到唤醒参数。

可用性

Android系统,iOS系统

可提供的 1.1.0 及更高版本

【方法二】:addWakeUpDetailEventListener() 该方法无论是否成功获取到拉起参数,均会回调。如果成功获取到拉起参数,则 ret != undefined 并且 err == undefined;如果没有获取到拉起参数,则 ret != undefined 并且 error == undefined。

addWakeUpDetailEventListener

添加唤醒页面事件监听者。在 JS 中获取到 api 对象(由 YonBuilder移动开发 官方提供)的 appintent 事件回调后,可通过该方法添加监听者。监听回调函数里可保存唤醒参数供后续业务使用。

示例代码

addWakeUpDetailEventListener({uri:ret}, callback(ret, err))

入参说明:{uri:ret} 为 appintent 事件回调数据

回调说明:传入监听回调 callback(ret, err)

ret:

类型:JSON对象

内部字段:

// 当获取到唤醒参数时,err 为 undefined,ret 为 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"
        }
    }
}


// 当没有获取到唤醒参数时,ret 为 undefined,err 为 json 对象,内部字段为:
{
    "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 为空
 */

调用示例

// 如果你的应用(安卓端)需要支持在 微信/QQ/QQ浏览器 内通过应用宝拉起,在调用 addWakeUpEventListener 方法前,请先调用一次 openYYBFunction 方法;若不需要支持,则无需调用 openYYBFunction 方法
var xinstall = api.require('xinstall');
xinstall.openYYBFunction({});


// 请严格遵循如下调用顺序,否则可能导致获取不到唤醒参数
var xinstall = api.require('xinstall');
api.addEventListener({
  name:'appintent'
},function(ret,err){
  xinstall.addWakeUpDetailEventListener({'uri': ret}, function(ret, err) { // 唤醒参数
    // 回调函数将在合适的时机被调用,这里编写拿到渠道编号以及唤醒数据后的业务逻辑代码
  
    if (ret == undefined) {
      // 没有获取到唤醒参数,可以根据 err.errorType 和 err.errorMsg 做进一步业务处理
    } else {
      var channelCode = ret.channelCode;
      var data = ret.data;
      var co = data.co;
      var uo = data.uo;
      // 根据获取到的数据做对应业务逻辑
    }
  });
});

补充说明

此方法用于获取动态唤醒参数,在拉起 APP 时,获取由 web 网页中传递过来的,如邀请码、游戏房间号等自定义参数,通过预先注册监听后,在回调中获取 web 端传过来的自定义参数。请严格遵循示例中的调用顺序,否则可能导致获取不到唤醒参数。

可用性

Android系统,iOS系统

可提供的 1.5.2 及更高版本

4、渠道统计

注意:调用该功能对应接口时需要在 Xinstall 中为对应 App 开通专业版服务

4.1、注册量统计

在业务中合适的时机(一般指用户注册)调用指定方法上报注册量

reportRegister

示例代码

reportRegister()

入参说明:无需主动传入参数

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

调用示例

var xinstall = api.require('xinstall');
xinstall.reportRegister();

补充说明

Xinstall 会自动完成安装量、留存率、活跃量、在线时长等渠道统计数据的上报工作,如需统计每个渠道的注册量(对评估渠道质量很重要),可根据自身的业务规则,在确保用户完成 App 注册的情况下,调用该方法上报后,即可在 Xinstall 平台即可看到注册量。

可用性

Android系统,iOS系统

可提供的 1.1.0 及更高版本

4.2、事件统计

事件统计,主要用来统计终端用户对于某些特殊业务的使用效果,如充值金额,分享次数,广告浏览次数等等。

调用接口前,需要先进入 Xinstall 管理后台事件统计然后点击新增事件。

reportEventPoint

示例代码

reportEventPoint({params})

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

入参内部字段:

eventId: 类型:字符串 描述:事件ID

eventValue: 类型:数字类型 描述:事件值,货币以分为单位

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

调用示例

var xinstall = api.require('xinstall');
xinstall.reportEventPoint({
  eventId:'payMoney',
  eventValue:13
});

补充说明

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

可用性

Android系统,iOS系统

可提供的 1.1.4 及更高版本

4.3 事件明细统计

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

1.5.7 及以后版本可用

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

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

var xinstall = api.require('xinstall');
console.log("事件明细"x
xinstall.reportEventWhenOpenDetailInfo({
  eventId: 'payMoney',
  eventValue: 12,
  eventSubValue:'张三'
});

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

5、场景定制统计

5.1 分享统计

场景业务介绍,可到分享数据统计页面查看

分享统计主要用来统计分享业务相关的数据,例如分享次数、分享查看人数、分享新增用户等。在用户分享操作触发后(注:此处为分享事件触发,非分享完成或成功),可调用如下方法上报一次分享数据:

var xinstall = api.require('xinstall');
xinstall.reportShareByXinShareId({
  xinShareId: '填写分享人或UID'
});

补充说明

分享人或UID 可由您自行定义,只需要用以区分用户即可。

您可在 Xinstall 管理后台 对应 App 中查看详细分享数据报表,表中的「分享人/UID」即为调用方法时携带的参数,其余字段含义可将鼠标移到字段右边的小问号上进行查看:

分享报表

可用性

Android系统,iOS系统

可提供的 1.5.2 及更高版本

6、广告平台渠道功能

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

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

6.1、配置工作

iOS 端:

由于 iOS 端目前是通过采集 IDFA 进行广告平台渠道统计,而 IDFA 必须使用 YonBuilder移动开发 官方提供的 「iAd」插件进行获取,故您必须在 [YonBuilder移动开发 管理后台] - [插件] - [插件库] 中,添加 「iAd」插件(可以搜索 idfa):

添加完成后,在应用打包页面内,填写获取 IDFA 权限的说明文字

注意:该项若不配置,则会导致 App 启动后闪退!!!

Android 端:

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

  1. 在YonBuilder移动开发 工程里的的config.xml文件中添加(获取IMEI,需要用到该权限)
<permission name="readPhoneState" />
  1. 如果使用OAID,因为内部使用反射获取oaid 参数,所以需要外部用户都接入OAID SDK 。具体接入参考《Android集成指南》

6.2、更换初始化方法

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

initWithAd

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

入参内部字段:

  • iOS 端:

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

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

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

调用示例

var xinstall = api.require('xinstall');
// 由于 iOS 和 Android 两端需要传入的参数不同,故需要根据平台进行判断,传入不同的参数

if (api.systemType == "ios") {
  // 导入 iAd 插件
  var iAd = api.require('iAd');
  // 先请求 IDFA 权限
  iAd.adRequest(function(ret){
    // 权限请求完成后,开始获取 IDFA
    iAd.getIDFA({}, function(ret) {
      // 传入 IDFA 初始化 Xinstall 插件
      Xinstall.initWithAd({idfa:ret.IDFA})
    });
  });
} else if (api.systemType == "android") {
  requestPremission ( function() {
    requestPremission ( function() {
      // oaid和gaid 为选传,不传则代表使用SDK自动去获取(SDK内不包括OAID SDK,需要自己接入)
        Xinstall.initWithAd({adEnable:true,gaid:"gaid测试",oaid:"oaid测试"});
    });
    // 如果希望在完成初始化,立即执行之后的步骤可以通过 下列代码实现-------------------------
    // Xinstall.initWithAd({adEnable:true,gaid:"gaid测试",oaid:"oaid测试"},function() {
    //  xinstall.addWakeUpEventListener 或者xinstall.addInstallEventListener 等方法                
    //});
    //-----------------------------------------------------------------------------
  });
  
}


// Android IMEI获取权限的判断和申请方法
function requestPremission (callback) {
  var rets = api.hasPermission({
    list: ['phone-r']
  });

  var granted = false;
  if (rets.count > 0) {
    granted = rets[0].granted;
  }
  if (granted) {
    // 有权限
    if (callback) {
      callback();
    }
  } else {
    //  无权限
    api.requestPermission({
      list: ['phone-r'],
      code: 100001
    }, function(ret, err) {
      if (callback) {
        callback();
      }
    });
  }
}

可用性

Android系统,iOS系统

可提供的 1.5.0 及更高版本

6.3、上架须知

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

6.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、苹果搜索广告(ASA)渠道功能

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

7.1、更换初始化方法

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

initWithAd

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

入参内部字段:

  • iOS 端:

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

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

调用示例

var xinstall = api.require('xinstall');
// 由于 iOS 和 Android 两端需要传入的参数不同,故需要根据平台进行判断,传入不同的参数

if (api.systemType == "ios") {
  // 只使用 asa 渠道,不使用广告渠道时,只需要传入 asa 参数
  Xinstall.initWithAd({asa:true})
  
  // 如果需要同时使用广告渠道,那么需要同时传入 idfa 参数,根据《6、广告平台渠道功能》中的方法获取到 idfa 后,再调用初始化方法:
  // var iAd = api.require('iAd');
  // iAd.adRequest(function(ret){
  //   iAd.getIDFA({}, function(ret) {
  //     Xinstall.initWithAd({idfa:ret.IDFA, asa:true})
  //   });
  // });
} else if (api.systemType == "android") {
  xinstall.init();
}

可用性

iOS系统

可提供的 1.5.5 及更高版本

四、如何测试功能

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

五、更多 Xinstall 进阶功能

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

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

是否仍需要帮助? 请保持联络!
最后更新于 2024/12/2