APICloud 接入指引

拉起至APICloud，获取模块

一、概述

为方便用户集成， openinstall 已在 APICloud 的模块Store中上架了官方模块。此模块封装了openinstall平台的SDK，集成了携参安装，渠道统计，快速安装和一键拉起功能；可用于实现移动广告效果统计，免填邀请码，安装后自动加好友，一键加入游戏房间，用户分享统计，微信中快速安装/一键拉起等功能，根据需求可实现更多场景。

二、初始化配置

1. 使用之前须从openinstall平台申请开发者账号并创建应用，获取AppKey，使用此模块之前建议先配置config.xml 文件，配置完毕，需通过云端编译生效，配置方法如下：

<permission name="internet" />
<preference name="urlScheme" value="openinstall官方自动分配的scheme" />

//android下
<meta-data name="com.openinstall.APP_KEY" value="openinstall官方自动分配的appKey" />
//iOS下
<feature name="openinstall">
    <param name="com.openinstall.APP_KEY" value="openinstall官方自动分配的appKey" />
</feature>
  • 字段描述:
    internet：添加网络权限；
    urlScheme：使用一键拉起功能必须配置
    com.openinstall.APP_KEY：从openinstall平台获取的 AppKey。

注：使用openinstall第三方插件文档集成时，如何快速获取AppKey、Associated Domains和scheme，下图为iOS相关配置信息（Android同理）：

2. Universal Links相关配置（iOS9.0以上）

1）到苹果开发者网站，为当前的 AppID 开启关联域名（Associated Domains）服务：

associatedDev

注意：当AppID重新编辑过之后，需要更新相应的mobileprovision证书。更新mobileprovision证书步骤请查看云编译mobileprovision证书制作中的 “云编译mobileprovision发布证书制作”或“云编译mobileprovision测试证书制作”。

2）创建新的（或更新现有的）描述文件，下载并导入到APICloud开发控制台 -> iOS证书；

3）配置关联域名（Associated Domains），方法如下：

在widget\res下创建文件名为UZApp.entitlements的文件，UZApp.entitlements内容如下：


<?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>
     <!--这里换成你在openinstall后台的关联域名(Associated Domains)-->
        <string>applinks:xxxxxx.openinstall.io</string>
    </array>
</dict>
</plist>

提示：openinstall完全兼容微信和QQ新版本的通用链接拉起功能，在使用微信模块wxPlus或wxpayPlus 时，对于微信要求配置的config.xml，需要传入openinstall相关的universal link链接。链接格式请到openinstall后台的【iOS集成】-【iOS应用配置】获取，参考univerallinks使用指南

三、调用API

1. 安卓广告参数配置（可选）

config
Android 配置接口，设置广告平台相关参数

config(options)

options

adEnabled:

  • 类型：布尔类型；
  • 描述：表示 openinstall SDK 是否需要获取广告追踪相关参数，默认为 false

oaid:

  • 类型：字符串；
  • 描述：通过移动安全联盟获取到的 oaid，默认为 null

gaid:

  • 类型：字符串；
  • 描述：通过 google api 获取到的 advertisingId，默认为 null

macDisabled：

  • 类型：布尔类型；
  • 描述：表示 是否禁止 openinstall SDK 获取 mac 地址，默认为 false
  • 说明：1.5.0版本新增配置

imeiDisabled：

  • 类型：布尔类型；
  • 描述：表示 是否禁止 openinstall SDK 获取 imei，默认为 false
  • 说明：1.5.0版本新增配置

示例代码

var openinstall = api.require('openinstall');
openinstall.config({
  adEnabled: true,
});

补充说明
此接口是 Android 平台针对广告平台接入而新增的配置接口，需要在调用 init 之前调用。参考广告平台对接Android集成指引

2. 初始化

init

示例代码

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

补充说明
如启用了广告平台对接，请按以下操作初始化

对于Android平台，需要在config.xml添加权限申明<permission name="readPhoneState"/>

对于iOS平台，获取idfa使用的是apicloud官方模块iAd，需要用户主动添加，iAd模块

openinstall模块初始化示例代码如下：

apiready = function() {
        var openinstall = api.require('openinstall');
        if (api.systemType == "ios") {
            //只进行H5参数还原和统计
            //openinstall.init();

            //需要用到idfa时，先获取idfa，再初始化
            var iAd = api.require('iAd');//引入iAd模块
               var iAd = iAd.getIDFA({
                  lowerCase: false
            }, function(ret) {
                    openinstall.init({
                            deviceId:ret.IDFA,
                            ASA:true,
                            isDev:false //isDev:true 是开启ASA测试模式，可以测试1234567890渠道下的统计数据，正式环境下请移除该设置或设置为false
                        });
            });

            //不用idfa时
            //openinstall.init({
            //        ASA: true,
            //        isDev:false //isDev:true 是开启ASA测试模式，可以测试1234567890渠道下的统计数据，正式环境下请移除该设置或设置为false
            //    });
        } else if (api.systemType == "android") {
            //获取imei需要申请权限再初始化
            var permissions = [];
            permissions.push('phone-r');
            var result = api.hasPermission({
                list: permissions
            });
            if(result && result[0] && !result[0].granted){
                //没有权限，去申请
                api.requestPermission({
                    list: permissions,
                    code: 100
                }, function(ret, err){
                    //不管是否申请到权限都要调用初始化
                    openinstall.config({
                        adEnabled: true,
                    });
                    openinstall.init();
                });
            }else{
                openinstall.config({
                    adEnabled: true,
                });
               openinstall.init();
            }
        }

 };

3. 快速安装

在App未安装的情况下，openinstall帮助您在社交平台一键下载并安装App，实现App的快速安装，从此告别“右上角打开浏览器”，大幅提升安装概率，助力用户增长；

在App已安装的情况下，openinstall通过标准的scheme，universal links等技术，从各种浏览器（兼容国内50+主流浏览器与社交平台，包括QQ、新浪微博、钉钉等主流社交软件的内置浏览器）一键拉起App并传递自定义参数，一键直达页面。

4. 一键拉起

获取拉起参数

getWakeup

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

callback(ret, err)

ret：

  • 类型：JSON对象
  • 内部字段：
{
    channelCode: '渠道编号',//渠道编号
    data:    '唤醒携带的参数'  //有携带参数，则返回数据，没有则为空
}

示例代码

var openinstall = api.require('openinstall');
          api.addEventListener({
              name: 'appintent'
          }, function(ret, err) {
              openinstall.getWakeup({
                  "uri": ret
              }, function(ret, err) {
                  alert(JSON.stringify(ret));
              });
          });

补充说明
此接口用于获取动态唤醒参数，通过动态参数，在拉起App时，获取由web网页中传递过来的，如邀请码、游戏房间号等自定义参数，拉起指定页面
监听appintent事件，调用以上代码,获取web端传过来的自定义参数,并回调给getWakeup方法调用;

可用性
Android系统,iOS系统

可提供的1.0.0及更高版本

5. App传参安装高级版功能

getInstall

getInstall({params},callback(ret, err))

params
timeout：
类型：数字类型
描述：超时时长，单位秒(s)，默认为10秒

callback(ret, err)

ret：

  • 类型：JSON对象
  • 内部字段：
{
    channelCode: '渠道编号', //推广安装来源渠道编号
    data:    '自定义参数', // 推广携带的自定义参数 
    shouldRetry:    '是否需要重试' //true代表超时，可以重试
}

示例代码

var openinstall = api.require('openinstall');
openinstall.getInstall({
   timeout:10
},function(ret, err){
   alert(JSON.stringify(ret));
});

补充说明
此接口用于获取动态安装参数（可重复获取），测试时候建议卸载再安装正确获取参数,在App需要个性化安装参数时（由web网页中传递过来的，如邀请码、游戏房间号等自定义参数），在回调中获取参数，可实现拉起指定页面、统计渠道数据等

可用性

Android系统,iOS系统

可提供的1.0.0及更高版本

6. 渠道统计高级版功能

SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。

6.1 reportRegister

上报注册量
reportRegister()

示例代码

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

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

可用性

Android系统,iOS系统

可提供的1.0.0及更高版本

6.2reportEffectPoint**

效果点统计
reportEffectPoint({params})

params
effectId：
类型：字符串
描述：效果点ID

effectValue：
类型：数字类型
描述：效果点值，货币以分为单位

extras（可选）:

  • 类型：JSON对象
  • 描述：自定义参数和值
  • 说明：1.7.0 版本及更高版本可用

示例代码

var openinstall = api.require('openinstall');
openinstall.reportEffectPoint({
  effectId:'effect_test',
  effectValue:1
});

效果点携带自定义参数上报

var openinstall = api.require('openinstall');
openinstall.reportEffectPoint({
  effectId:'effect_detail',
  effectValue:1,
  extras: {
    "key1": "value1",
    "key2": "value2"
  }
});

补充说明
effectID与effectValue对应的值与openinstall平台的效果点管理的效果点名称与效果点ID必须一一对应。在openinstall平台即可看到渠道管理的渠道效果点。
效果点

6. 裂变分享高级版功能

分享统计

reportShare({params},callback(ret, err))

params

shareCode：

  • 类型：字符串
  • 描述：分享标识码

platform：

  • 类型：字符串
  • 描述：分享平台，参考官网定义的平台字符串

callback(ret, err)

ret：

  • 类型：JSON对象
  • 内部字段：
{
    shouldRetry: false, //是否上报失败需要重试
    message: '返回的错误信息' //返回的错误信息
}

示例代码

var openinstallModule = api.require('openinstall');
openinstallModule.reportShare({
    shareCode: "10001",
    platform: "QQ"
}, function(ret, err) {
    if(ret.shouldRetry){
        alert("需要重试");
    }
});

可用性

Android系统,iOS系统

可提供的1.8.0及更高版本

四、导出apk/ipa包并上传

  • 代码集成完毕后，需要导出安装包上传openinstall后台，openinstall会自动完成所有的应用配置工作。
  • 上传完成后即可开始在线模拟测试，体验完整的App安装/拉起流程；待测试无误后，再完善下载配置信息。

下面是apk包的上传界面（后台截图）：

上传安装包