uni-app 接入指引

插件介绍

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

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

使用前准备及说明

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

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

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

一、配置

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

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平台)

  • 开启Associated Domains服务
    苹果开发者网站,为当前的 AppID 开启关联域名(Associated Domains)服务:

注:开启Associated Domains服务后需要重新生成profile文件,提交云端打包时使用

1)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分配给应用的关联域名"  
            ]  
        }  
    }

获取关联域名:openinstall应用控制台 -> iOS集成 -> iOS应用配置 -> 关联域名(Associated Domains)

2)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. 快速下载

如果只需要快速下载功能,无需其它功能(携带参数安装、渠道统计、一键跳转),完成初始化即可

3. 一键跳转

获取跳转数据

registerWakeUp(callback)

  • callback: 数据回调函数

示例:
App.vueonLaunch方法中注册跳转回调

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

4. 携带参数安装高级版功能

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

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

示例:

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

5. 渠道统计高级版功能

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

5.1 注册统计
示例:

openinstall.reportRegister();

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

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

示例:

openinstall.reportEffectPoint("effect_test", 1);

三、导出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.vueonLaunch方法中进行初始化,先申请权限,之后进行配置和初始化

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.vueonLaunch方法中进行初始化,如下:

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

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