B端APP集成

一、文档说明

1、阅读对象

本文档阅读对象： 物业系统集成物联云平台应用模块(智慧人行、智慧车行、智慧运维或其他)涉及的研发人员。

二、术语

概念名称 备注
物联云平台应用模块 物联云平台的应用模块是由物联云平台或者其他第三方的服务供应商以物联云平台一体化集成框架为标准制作的标准服务模块，用户可以在集成物联云平台一体化SDK之后完成应用模块的快速对接。
一体化SDK 一体化SDK是物联云平台一体化集成框架的基础SDK，用户可以通过对一体化SDK的集成完成物联云平台一体化集成框架的基础环境搭建。
物联云平台账户授权 物联云平台的所有应用模块所依赖的用户信息皆来源于物联云平台的账户体系，当用户想要进行服务对接需要将自己的账户体系与物联云平台的账户体系进行打通。
模块配置文件 物联云平台方会提供一份环境配置文件，其中包含了所有需要使用到的配置项信息（如： 主色调、应用服务器地址、H5应用服务器地址、相应模块版本等），基于不同的项目情况可能出现一个或者一个以上的环境配置文件。
APP容器 APP容器是应用服务执行的基础环境
XlinkApiServer 物联云平台的应用服务器

三、项目开发流程与步骤

1、进行账户对接

目前账户对接为通过OpenId进行对接，具体相关文档可参考企业成员登录

其中需要完成以下几步：

1.1、完成服务配置

接入方需要将自己应用的登录验证服务器以及token向XlinkApiServer进行注册。具体见上方的文档链接。

1.2、完成校验接口开发

接入方在配置完成之后，当XlinkApiServer收到了第三方登陆请求时，XlinkApiServer会向上一步骤配置的登陆验证服务器发起校验请求，接入方的后端开发需要在特定的接口中完成open_id和access_token的校验并返回结果。具体见上方的文档链接。

2、SDK对接

当对接方和XlinkApiServer完成了用户信息对接后，SDK的对接就可以开始了。

SDK对接一共包含三步： SDK初始化、账户认证、模块跳转，下文将对这每个步骤进行展开讲解。

2.1、SDK初始化

SDK初始化是对一体化SDK的基础环境进行搭建，其中会涉及到初始化参数传递的内容。

SDK初始化要求在后续两步之前完成，不建议进行多次初始化。具体API详见4部分的对应内容。

2.2、账户认证

XlinkApiServer的账户体系不支持多端登陆，同时B端账户信息和管理台的账户无法共存（当你进行管理台登陆时，会导致你在APP中登陆的相同账号发生账户被挤的情况），如果对接方的账户需要支持多端同时登陆，请联系相关的项目经理进行解决。

上文中有提到企业成员登录这个文档，该接口是用于进行第三方账户登录的接口，为了方便对接方完成接入，一体化SDK对该接口进行了封装。具体API详见4部分的对应内容

2.3、模块跳转

一体化SDK使用路由完成应用模块跳转，下表中列出了目前标品的模块路由名和路由参数清单，具体情况请以项目的情况为主，如果您无法从该清单中得到你所要对接的所有模块，请联系相关的项目经理获取完整的路由名和路由参数清单。

应用名称 类型 路由名 参数
设备设施(E3) B端 /app/module/index {“identifier”: “mobile_platformbuiltin_smart_operation”}
智慧通行 B端 /app/module/index {“identifier”: “mobile_platformbuiltin_smart_transmission”}
智慧视频 B端 /app/module/index {“identifier”: “mobile_platformbuiltin_smart_video”}

四、APP容器

1、APP端开发步骤

1.1、iOS开发要点说明

以下项目开发环境以Xcode11.0，运行环境为iOS9.0，依赖管理工具为Cocoapod为例，说明其开发中需要的操作。

1.1.1、获取初始化环境配置

从相关平台中获取配置Bundle，注意Bundle的名称不允许修改, 其中的文件的名称也不允许修改。
配置文件的内容和描述

文件名 描述
xlink-config.xlink Xlink服务依赖的环境参数
XLTheme.bundle XLink模块的全局换肤模块
1.1.2、使用Cocoapod将下列SDK库文件集成到项目中

podfile模板

# Uncomment the next line to define a global platform for your project
platform :ios, '9.0'
 
use_frameworks!
source 'https://code.xlink.cn/sdkLib/Specs.git'
source 'https://github.com/CocoaPods/Specs.git'
 
target 'XLHolderDemo' do
  use_frameworks!
   
  # 基础SDK
  pod 'BANativeContainerGlue/Common', "1.0.3"
  pod 'XLinkRestUtil', '1.0.3'
   
# # 模块首页
# pod 'BANativeContainerGlue/BAModuleIndex', "1.0.3"
# # 播放器
# pod 'BANativeContainerGlue/IPCPlayer', "1.0.3"
#
## E3
# pod 'DeviceManage/Base'
# pod 'DeviceManage/NativeContainer'
   
  target 'XLHolderDemoTests' do
    inherit! :search_paths
  end
   
  target 'XLHolderDemoUITests' do
  end
   
end
 
post_install do |installer|
    installer.pods_project.targets.each do |target|
        if target.name == "Masonry"
            target.build_configurations.each do |config|
                config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '9.0'
            end
        end
    end
end
1.1.3、SDK初始化

用户APP引入SDK集合之后，调用应用服务前，需要先进行SDK初始化，SDK会自行读取配置文件中的配置信息，示例代码如下:

需要注意的是注册时会要求提供一个处理token过期的回调，通常这个回调调用是在用户发生了异地登录导致的Token失效，接入方的开发需要在这个地方进行相应的跳转处理。

[XLHolderApi registerWithTokenExpiredCallBack:^{
        // XLink授权 token过期回调
    }];
1.1.4、授权信息同步

SDK进行业务处理时，需要得到XLink的授权信息。
得到授权信息之后，通过相关API同步到SDK中。 如下:

// corpId 企业ID
// openId openId
// accessToken accessToken
[XLHolderApi syncXLinkCorpAuthInfoWithCorpId:corpId openId:openId accessToken:accessToken source:@"10" completeCallBack:^(id  _Nonnull response, NSError * _Nonnull error) {
             
}];
1.1.5、应用模块集成

当你想要进行功能跳转之时。

联系相关的功能应用模块开发得到对应的模块SDK以及功能页面的路由清单，如果模块为纯H5模块则不需要模块SDK。

将SDK添加到工程中，如：如果是Localpod的SDK则通过cocoapods添加到主工程中。容器SDK会自动将所有的模块SDK进行初始化。

发起路由调用。

例如：集成智慧运维应用的任务管理模块，路由信息如下：

路由: /device_manage/task_manage/task_collect_list
参数:

键值 是否必填 值类型 值 值描述
role 否 Array 具体值查看资源点清单所列举的数据 模块中允许访问的资源点清单

集成代码如下：

[XLHolderApi router:@"/device_manage/task_manage/task_collect_list" parameters:@{} callBack:^(id  _Nullable callbackObjc, NSError * _Nullable error) {
             
}];
1.1.6、第三方平台分享

当对接的模块中存在第三方分享的功能时，需要实现相关的接口。
关于分享中所需要的关于分享SDK的注册以及分享的UI界面由目标APP完成，XLHolder只提供要求被分享出去的内容，以及相关的页面信息。
涉及分享的相关数据都存在在block中的content字典中，其中Key与数据内容的对应关系如下：

Key 数据类型
content 分享的文本
title 分享的标题
url 分享的内容链接
dataUrl 数据流链接(视频、音乐等)
path 小程序的页面路径
type 分享的数据类型

其中type的值与分享类型的对应关系

Type 分享的数据类型
text 纯文本
image 图片
web 网页
video 视频
wx_mini 微信小程序 
[XLHolderApi handlerShareMessage:^(NSDictionary * _Nonnull content, UIViewController * _Nonnull vc, void (^ _Nonnull completeCallBack)(NSError * _Nonnull)) {
    // 分享的数据类型
    NSString *type = content[@"type"];
     
    NSString *title = content[@"title"];
    NSString *text = content[@"text"];
     
    // ----
    // TODO: 实现选择分享平台的UI内容 并将相关内容分享出去
    UIViewController *platSelectVC = nil;
    // TODO: 当分享完成之后 根据用户的操作返回是否成功分享 如果失败给出失败原因
    void(^handler)(NSError *error) = ^(NSError *error) {
        if (completeCallBack) {
            completeCallBack(error);
        }
    };
     
    //
    NSError *error = [NSError errorWithDomain:NSCocoaErrorDomaincode:500 userInfo:@{NSLocalizedDescriptionKey: @"用户取消分享"}];
    handler(error);
     
    [vc presentViewController:platSelectVC animated:YEScompletion:nil];
    // ----
}];

1.2、Android开发要点说明

1.2.1、复制以下SDK库到项目libs文件夹中

SDK库列表:

SDK名称 描述 提供方式 依赖地址/SDK文件名
xlholder 容器SDK，为上层提供路由、原生容器、H5容器的封装和屏蔽细节 依赖 implementation ‘cn.xlink.business:xlink-holder:1.0.8’
xlink_restful 基于XLink平台的请求SDK库 依赖 implementation ‘cn.xlink.business:xlink-restful:1.1.1’
xlink_h5_container 为H5页面提供原生能力的H5容器SDK SDK文件 implementation ‘cn.xlink.business:xlink-h5-container:1.0.0’, implementation ‘cn.xlink.business:xlink-qrcode-produce:1.0.0’, implementation ‘cn.xlink.business:xlink-qrcode-scan:1.0.0’
barouter 基于ARouter进行再封装的路由SDK 依赖 implementation ‘cn.xlink.business:xlink-barouter:1.0.4’
xlink_native_container 提供本地应用容器生命周期分发，在XLHolder中已经完成了相关调用处理，无需再调用相关API 依赖 implementation ‘cn.xlink.business:xlink-native-container:1.0.0’
注意 : 上面表中除 xlink_h5_container 模块是以aar 包提供的, 其他都是通过添加依赖的方式集成
1.2.2、添加依赖

\1. 在项目的 build.gradle 文件中 引入如下依赖

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
        google()
        jcenter()
        maven {url 'http://maven.aliyun.com/nexus/content/repositories/releases/'}
        maven {url 'https://code.xlink.cn/sdkLib/containersdk_android/-/raw/master/' }
    }
}

\2. 在module的build.gradle文件中引入如下依赖

implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
// xlholder
implementation 'cn.xlink.business:xlink-holder:1.0.8'
// xlink_restful
implementation 'cn.xlink.business:xlink-restful:1.1.1'
// barouter
implementation 'cn.xlink.business:xlink-barouter:1.0.4'
// xlink_native_container
implementation 'cn.xlink.business:xlink-native-container:1.0.0'
 
// Restful依赖库
implementation 'io.reactivex.rxjava2:rxandroid:2.0.2'
implementation 'com.squareup.retrofit2:retrofit:2.3.0'
implementation 'com.squareup.retrofit2:converter-gson:2.3.0'
implementation 'com.squareup.retrofit2:converter-scalars:2.3.0'
implementation 'com.squareup.retrofit2:adapter-rxjava2:2.3.0'
 
//路由依赖库
implementation 'com.alibaba:arouter-api:1.5.0'
 
// 模块依赖库
implementation 'android.arch.persistence.room:runtime:1.1.1'
annotationProcessor 'android.arch.persistence.room:compiler:1.1.1'
implementation 'android.arch.persistence.room:testing:1.1.1'
implementation 'android.arch.persistence.room:rxjava2:1.1.1'
implementation 'com.inuker.bluetooth:library:1.4.0'
 
// H5容器依赖库
implementation 'com.berwin.cocoadialog:cocoadialog:1.3.3'
implementation 'com.jakewharton:butterknife:8.4.0'
implementation 'com.google.code.gson:gson:2.8.5'
implementation 'org.greenrobot:eventbus:3.0.0'
implementation 'com.wcl.notchfit:notchfit:1.4'
implementation 'com.github.wendux:DSBridge-Android:master-SNAPSHOT'
1.2.3、SDK初始化

用户APP引入SDK集合之后，调用应用服务前，需要先向SDK注册您的服务所部署的相关host信息， 如下:

XLHolderApi.getInstance(context).registerHost("API Host", "H5 基础地址", new XLHolderApi.OnTokenExpiredCallBack(){
    public void onTokenExpired(){
        // TODO: 处理Token过期逻辑
    }
});
1.2.4、授权信息同步

SDK进行业务处理时，需要得到XLink的授权信息。
企业成员登录
得到授权信息之后，通过相关API同步到SDK中。 如下:

XLAuthInfo authInfo = fetchAuthInfo();// 获取到的授权信息, 通常是从服务器请求获得
XLHolderApi.getInstance(context).syncXLinkAuthInfo(authInfo);
1.2.5、B端标准登录

XLHolderApi.syncXLinkCorpAuthInfo()

参数名 参数描述 是否必填
context 上下文
corpId 企业id 是
openId openId 是
accessToken 外壳App的用户校验token 是
source 固定值1(项目不同可能值不一样,如果没有特殊说明,值为1) 是
userType 用户类型(保留项) 是
callback 回调
1.2.6、H5 模块使用

如需使用H5模块, 可通过路由跳转到指定H5页面, 并传入参数

实例代码 :

String path = "/APP/H5";
Map<String, Object> param = new HashMap();
param.put("url", url);
XLHolderApi.getInstance(this)
        .router(path, param, new BANavigationCallback() {
            @Override
            public void onFound(BARoute baRoute) {
            }
 
            @Override
            public void onLost(BARoute baRoute) {
            }
 
            @Override
            public void onArrival(BARoute baRoute) {
            }
 
            @Override
            public void onInterrupt(BARoute baRoute) {
            }
        });

注意 : 如需配置成相对地址, 需要在初始化的时候提供 h5 基础地址, 详情见 第三点 SDK初始化

参数描述

参数 描述 是否必填
path 路由地址(固定值) 是
url H5页面要跳转的链接地址, 可以是绝对地址, 也可以是相对地址 是
1.2.7、应用模块集成

当你想要进行功能跳转之时。

  • 联系相关的功能应用模块开发得到对应的模块SDK以及功能页面的路由清单，如果模块为纯H5模块则不需要模块SDK。
  • 将SDK添加到工程中，通过gradle添加到主工程中。容器SDK会自动将所有的模块SDK进行初始化。
  • 发起路由调用。

例如：集成智慧运维应用的任务管理模块，路由信息如下：

路由: /device_manage/task_manage/task_collect_list
参数:

键值 是否必填 值类型 值 值描述
role 否 Array 具体值查看资源点清单所列举的数据 模块中允许访问的资源点清单

集成代码如下：

XLHolderApi.getInstance(context).router("/device_manage/task_manage/task_collect_list", parameters:null, new BANavigationCallback() {
                    @Override
                    public void onFound(BARoute route) {
                       
                    }
 
                    @Override
                    public void onLost(BARoute route) {
                         
                    }
 
                    @Override
                    public void onArrival(BARoute route) {
                    }
 
                    @Override
                    public void onInterrupt(BARoute route) {
                    }
                });
1.2.8、JS代理功能

H5容器支持APP实现部分JS代理功能，应用通过实现XLJavascriptProxy类可实现部分JS功能的代理。目前支持APP自行实现的接口有第三方分享及微信支付功能。APP可通过如下代码实现并注册自己的JS代理实例。

H5App.registerJavascriptProxy(new XLJavascriptProxy() {
            @Override
            public void onShareMessage(Activity activity, Object msg, OnExecuteResultListener listener) {
            }
 
            @Override
            public void onWechatPay(Activity activity, Object msg, OnExecuteResultListener listener) {
            }
        });
1.2.9、第三方分享

当对接的模块中存在第三方分享的功能时，可覆写XLJavascriptProxy的onShareMessage方法实现第三方分享功能。

接口入参activity为当前H5容器Activity，可用于资源获取、界面跳转等，为避免内存泄漏，请不要在方法以外保存该实例的引用。listener为结果监听器，需在逻辑最后执行相关接口将结果返回给H5容器，其抽象接口如下：

public interface OnExecuteResultListener {
        void onSuccess(); // 成功回调
 
        void onFailure(String message); // 失败回调，message为错误描述
    }

msg为Json字符串，其中Key与数据内容的对应关系如下：

Key 数据类型
Key 数据类型
content 分享的文本
title 分享的标题
url 分享的内容链接
dataUrl 数据流链接(视频、音乐等)
path 小程序的页面路径
type 分享的数据类型

其中type的值与分享类型的对应关系

Type 分享的数据类型
text 纯文本
image 图片
web 网页
video 视频
wx_mini 微信小程序
1.2.10、微信支付

当对接的模块中存在微信支付的内容时，可通过覆写XLJavascriptProxy的onWechatPay实现微信支付功能功能。

接口入参与第三方分享基本一致，区别只是msg内容不同，其中Key与数据内容的对应关系如下：

Key 数据类型
partnerid partnerid
prepayid prepayid
package package
nonceStr nonceStr
timeStamp 时间戳
sign 签名信息

五、更新说明

日期 版本号 版本内容 作者 审核人 审核日期
2020年9月28日 V1.0 初稿 胡李辉 - -
2020年10月14日 V1.0 增加Android端接入说明 孙望侠 - -
2021年8月18日 V1.1 增加流程描述 胡李辉 - -
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题