uni-app 接入指引

插件介绍

此插件是 openinstall 为了方便 uni-app 集成使用 openinstall 功能而开发的，实现了App传参安装，渠道统计(H5渠道、广告平台渠道、ASA渠道等)，一键拉起全部功能。

openinstall可帮助 Android/iOS 开发者精确的获取 App 每一次安装来源；在 App 安装或拉起后，直达指定场景，大大提高用户转化率和留存率。同时，openinstall 在精准的 app 安装来源跟踪的技术上，开发了免打包，跨平台的渠道统计功能，轻松创建与管理成千上万的渠道，实现线上线下全渠道覆盖。openinstall 统计数据完全独立于第三方平台，提供多维度的统计报表，实时客观地反映渠道效果。

使用前准备及说明

前往openinstall 官网，注册账户，登录管理控制台，创建应用后，跳过 "集成指引"，在 "应用集成" 的对应平台的 "应用配置" 中获取appkey和scheme以及 iOS 的关联域名。

针对使用了 渠道统计 功能中的 广告渠道 效果监测功能的集成，需要参考补充文档

注意：为了适配苹果最新的ASA渠道统计API，插件版本1.5.4及以上版本中，iOS插件编译环境为Xcode 12.3，本地打包的用户需要注意。

1. 配置appkey

在 mainfest.json 的App原生插件配置的 openinstall 插件配置框内配置 openinstall 分配给应用的AppKey

2. 配置scheme

在 mainfest.json 的App常用其它配置中配置 openinstall 分配给应用的scheme（获取scheme：openinstall应用控制台 -> Android集成 -> Android应用配置 -> scheme，iOS同理）

3. 配置Universal Links（iOS平台）

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

2）、在新版HBuilderX里面配置关联域（Associated Domains）
示例如图：

以下是旧版本HBuilderX的关联域配置：

HBuilderX2.3.0开始云端打包支持配置Xcode中的Capabilities，包括关联域名（Associated Domains）配置参考文档
在HBuilderX中的manifest.json中配置关联域名：
在"plus" -> "distribute" -> "apple" -> "capabilities" -> "entitlements"节点（uni-app项目在"app-plus" -> "distribute" -> "ios" -> "capabilities" -> "entitlements"）下添加"com.apple.developer.associated-domains"字段，字段值为字符串数组，每个字符串为要关联的域名

    "capabilities": {  
        "entitlements": {  
            "com.apple.developer.associated-domains": [  
                "openinstall分配给应用的关联域名"  
            ]  
        }  
    }

HBuilderX2.3.0之前，需将插件下载到本地修改package.json中内容

"entitlements": {
    "com.apple.developer.associated-domains": [
        "openinstall为应用生成的关联域名"
    ]
}

然后再提交云端打包
参考本地uni-app原生插件提交云端打包

二、使用教程

1. 引用并初始化

const openinstall = uni.requireNativePlugin('openinstall-plugin');

必须先进行初始化，才能调用其他api

openinstall.init();

2. 快速安装

如果只需要快速安装功能，无需其它功能（App传参安装、渠道统计、一键拉起），完成初始化即可

3. 一键拉起

获取拉起数据

registerWakeUp(callback)

• callback: 数据回调函数

示例：
在App.vue的onLaunch方法中注册拉起回调

openinstall.registerWakeUp(function(result){
    console.log('getWakeup : channel=' + result.channelCode + ', data=' + result.bindData);
});

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

获取安装数据
getInstall(seconds, callback)

• seconds: 回调超时时间
• callback: 数据回调函数

示例：

openinstall.getInstall(
    8,
    function(result) {
    console.log('getInstall : channel=' + result.channelCode + ', data=' + result.bindData 
        + ', shouldRetry=' + result.shouldRetry);
    }
);

5. 渠道统计高级版功能

SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。其它业务相关统计由开发人员使用 api 上报

5.1 注册统计
示例：

openinstall.reportRegister();

5.2 效果点统计
reportEffectPoint(effectPointId, effectPointValue)

• effectPointId: 效果点ID
• effectPointValue: 效果点值，数值类型

示例：

openinstall.reportEffectPoint("effect_test", 1);

5.3 效果点明细统计reportEffectPoint(pointId, pointValue, extras)

• pointId: 效果点ID
• pointValue: 效果点值，数值类型
• extras: 效果点自定义参数和值,key和value都必须是string类型

示例：

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

6. 裂变分享上报高级版功能

reportShare(shareCode, sharePlatform, callback)

• shareCode: 分享标识码（用户标识）
• platform: 分享平台，参考官网定义的平台字符串
• callback: 上报回调函数 示例：

  openinstall.reportShare("10001", "QQ", function(ret) {
    console.log('shouldRetry = ' + ret.shouldRetry + ', message = ' + ret.message);
    if(ret.shouldRetry){
        console.log('上报失败，请重试');
    }
  });
  

  备注：platform分享平台，具体传入字段，参考文档裂变分享平台列表

三、导出apk/ipa包并上传

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

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

广告接入补充文档

Android平台

（1）针对广告平台接入，新增配置接口，在调用 init 之前调用。参考广告平台对接Android集成指引

var options = {
    adEnabled: true,
    oaid: "通过移动安全联盟获取到的 oaid",
    gaid: "通过 google api 获取到的 advertisingId",
}
openinstall.configAndroid(options);

例如： 开发者自己获取到了 oaid，但是需要 openinstall 获取 gaid，则配置参数为

var options = {
    adEnabled: true,
    oaid: "通过移动安全联盟获取到的 oaid",
    gaid: null,
}

（2） 为了精准地匹配到渠道，需要获取设备唯一标识码，因此需要在manifest.json中声明权限，在 “App模块权限配置” 的 “Android打包权限配置” 勾选上<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

（3）在manifest.json中设置，关闭uni-app自动获取android.permission.READ_PHONE_STATE权限

{
    "app-plus" : {
        "distribute" : {
            "android" : {
                "permissionPhoneState" : {
                    "request" : "none",
                    "prompt" : ""
                },
            }
        }
    }
}

（4）在App.vue的onLaunch方法中进行初始化，先申请权限，之后进行配置和初始化

if (plus.os.name == "Android") {
    plus.android.requestPermissions(["android.permission.READ_PHONE_STATE"], function(event) {
        if(event.granted){
            console.log(event.granted);
        }
        if(event.deniedPresent){
            console.log(event.deniedPresent);
        }
        if(event.deniedAlways){
            console.log(event.deniedAlways);
        }
        // 配置初始化，设置 OAID 和 GAID
        var options = {
            adEnabled: true,
            oaid: null,
            gaid: null,
        }
        openinstall.configAndroid(options);
        // 权限申请成功，不管用户是否同意，都需要做初始化
        openinstall.init();
        // 初始化完成后，才能做其他api调用
        openinstall.registerWakeUp(function(result) {
            console.log('wakeup : channel=' + result.channelCode + ', data=' + result.bindData);
        });
    }, function(event) {
        // 权限申请错误
    })
}

iOS平台

包括广告平台渠道统计和ASA渠道：

广告平台渠道：

openinstall后台配置及上架指引可参考文档广告平台对接iOS集成指引

（1）需在manifest.json的 “App常用其它设置” 中配置勾选 “使用广告标识（IDFA）”

（2）下载官方插件iOS平台获取idfa，并保存到目录下，如js_sdk/dc-idfa/idfa.js

（3）在App.vue中引用此模块，如下：

import idfa from "@/js_sdk/dc-idfa/idfa.js"

（4）在App.vue的onLaunch方法中进行初始化，如下：

if('iOS' == plus.os.name){
    var fid = "";
    fid = idfa.value();//如果需要idfa则开启
    openinstall.init(fid);
    console.log(fid);
};

ASA渠道：

插件1.5.4及以上版本增加了ASA渠道统计功能，已经集成在SDK内部，只需配置增加少量代码。开发者可以通过getInstall方法获取channelCode对应的值，即为ASA渠道编号。
区分ASA渠道和H5渠道及其它渠道，可在openinstall开发者平台创建渠道时，创建不同的渠道编号来做区分，如asa+广告系列ID，例子：asa_1234567890。

//配置asa,也可同时配置idfa
//isDev:"1"是测试模式，可以测试1234567890渠道下的统计数据，正式环境下请去掉该设置
var options = {
    asa: "1",
    isDev: "1",//正式上线前务必注释或删除该设置，否则会影响安装参数还原
    //idfa: null,
}
openinstall.initAdsAttribution(options);

注意：初始化方法只能调用其中一个，即如果使用了openinstall.initAdsAttribution(options);方法，则不需要使用openinstall.init(fid);方法

注意：广告平台统计里面，获取idfa申请权限的方法，需要在app becomes active的时候调用，避免弹窗无法正常弹出的情况出现。

如何在openinstall开发者平台创建ASA渠道，并实现统计功能和上架前测试，请看图文文档ASA渠道使用指南