一、SDK 使用流程介绍
SDK 的使用流程如下：
- SDK 依赖并集成
- SDK 初始化
- 调用 SDK 进行第三方账号登录
- 根据业务需求使用相应的功能
二、SDK 集成
SDK 集成需要完成相关依赖库的集成操作。
iOS 的集成建议使用 Cocoapods 本地库的方式提供。另外有部分公共依赖库需要引用我们提供的远程库。
1、集成环境
| 环境 | 要求 |
|---|---|
| 支持最低SDK版本 | iOS 10.0系统 |
2、配置依赖库
2.1、配置 Cocoapods 仓库
在项目下的Podfile文件中，添加上依赖库相关的的远程库 pod 源。
# CocoaPods 官方 Specs
source "https://github.com/CocoaPods/Specs.git"
# XLink 容器 Specs
source "https://code.xlink.cn/sdkLib/Specs.git"在主项目（或需要使用 SDK 的项目）下，在其对应的podfile的文件中，配置以下的依赖库。
其中第三方依赖库可以根据需要调整版本号。
//xlink依赖库
#远程库
pod 'XFServerManagerFramework'
pod 'XFH5ServerFramework'如果使用家居模块的话，还需要进行以下本地库的引用
将提供的LocalPods文件夹下所有内容复制到工程所在目录根目录中；
并配置路径：
$xlink_local_path = "./LocalPods"#本地库
pod "XLinkHomeKit", :path => "#$xlink_local_path/XLinkHomeKit/XLinkHomeKit.podspec"2.2、应用权限要求
SDK 使用时需要使用到以下的权限。部分权限是业务场景中具体使用到的，不使用到相应的业务功能可以移除掉相关的权限。
<key>NSCameraUsageDescription</key>
<string>使用您的相机或相册完成应用内图片的拍摄和选择,以及二维码扫描功能。</string>
<key>NSMicrophoneUsageDescription</key>
<string>使用您的麦克风应用可视对讲、语音控制等功能</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>使用您的相机或相册完成应用内图片的拍摄和选择</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>使用您的相机或相册完成应用内图片的拍摄和选择</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>使用您的位置来获取附近的房屋或项目信息，允许系统使用定位，才能使用APP配网功能</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>使用您的位置来获取附近的房屋或项目信息，允许系统使用定位，才能使用APP配网功能</string>
<key>NSLocationUsageDescription</key>
<string>使用您的位置来获取附近的房屋或项目信息，允许系统使用定位，才能使用APP配网功能</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>使用您的位置来获取附近的房屋或项目信息，允许系统使用定位，才能使用APP配网功能</string>| 权限 | 使用范围 |
|---|---|
| 蓝牙 | 用于APP配网 |
| 定位 | 用于APP配网以及获取业主附近的房屋 |
| 相机 | 扫描二维码加入家庭 |
3、SDK 初始化
SDK 集成后需要在使用前初始化。必须确保 SDK 初始化后才能正常使用。初始化 SDK 的部分配置以配置文件的方式提供，需要加载配置文件进行初始化。
建议在application:didFinishLaunchingWithOptions:方法里进行初始化
注意不能修改配件文件名称。
//默认的配置初始化，必须使用这个初始化
[XFUnionKit autoInit];通过以上的操作，初始化操作就完成了。请留意日志中是否有相关的错误信息输出，有的话请参考错误信息说明处理或进行反馈。
4、SDK 使用
SDK 的核心为服务，通过提供各种服务来解决业务需求或功能的使用。
tips：服务的介绍说明请参考APP集成说明
三、服务调用
SDK 初始化成功后，即可调用相关的服务，服务调用时统一从 XFServerManager 中获取服务并使用。
1、显式调用
服务支持显式调用，显式调用时表示调用者明确知道自己使用的服务类型，并且必须依赖具体的服务类型。一般的显式调用如下：
// 明确知道服务是 XFAuthServer 类型，并直接调用其中的方法，同时也必须在编译时依赖该服务
XFAuthServer *authServer = [[XFServerManager shareInstance] getServer:@"XFAuthServer"];
// 明确知道服务是有该方法
[authServer authThirdPartWithOpenId:openId accessToken:accessToken nickName:nickName resource:resource callback:^(NSDictionary * _Nullable result, NSError * _Nullable error) {
if (error) {
//登录失败
} else {
//登录成功后的 xlink 用户 token 信息
NSDictionary *userInfo = result;
}
}];
其中 getServer 的操作会确保服务在使用前初始化，该操作是异步的。
2、隐式调用
服务也支持隐式调用，隐式调用时，调用者可以不明确知道自己使用的服务类型，或服务操作，但是必须明确服务调用需要的参数及返回信息。一般的隐式调用如下：
[XFServerManager createInvokeBuilder:^(XFServerInovkeBuilder * _Nonnull builder) {
//指定调用的服务ID
builder.serverId = @"A";
//指定调用的服务路由
builder.routerPath = @"B";
//配置服务使用的参数,这里参数的类型和数值需要和服务提供者确认。
builder.param = @"context"
} invokeServerWithCallback:^(NSDictionary * _Nullable result, NSError * _Nullable error) {
//调用服务返回的数据。
}];
- 隐式调用的前提是调用者与被调用者是通过约定的方法进行调用的，如果双方没有约定好或者是不清楚时，可能导致入参错误或出参类型错误，则无法正确完成调用。
在以上示例中，表示：通过调用服务ID为“A”的服务，并使用路由地址为“B”的功能，提供服务需要的参数“context”，调用服务得到返回类型为“NSDictionary”类型的数据。 - 隐式调用是需要服务本身支持的，如果服务没有实现路由功能的支持与处理，进行隐式调用是肯定会失败的。
- 隐式调用时，返回的参数类型默认是支持可空类型的，在实现时需要留意一下。
四、更新说明
| 日期 | 版本 | 更新内容 |
|---|---|---|
| 2021-12-29 | v1.1 | 更新文档信息 |
| 2021-10-15 | v1.0 | 集成文档 |
