# iOS 集成
集成样例代码
我们提供了包含“微信登录,微信支付,高德地图、百度地图”功能的样式 DEMO 工程,开发者可以在Github(国外) (opens new window)或Gitee(国内) (opens new window) 获取集成样例代码。
# 1. 获取凭据
请注意
集成 SDK 需要先在 FinClip 平台中创建应用并绑定小程序,获得每个应用专属的SDK KEY
及SDK SECRET
后,随后就可以在集成 SDK 时填写对应的参数。打开小程序时 SDK 会自动初始化,并校验SDK KEY
,SDK SECRET
与BundleID(Application ID)
是否正确。
您可以 【点击这里】 查看如何获取所需要的SDK KEY
及SDK SECRET
。请务必确认集成 SDK 时填写的参数正确,否则会导致小程序无法打开。
# 2. 集成SDK
FinClip 小程序 SDK 目前支持pod集成
或者手动集成
。
# 2.1 Pod集成
# 2.1.1 安装pod环境
Cocoapods 提供了一个非常简单的依赖管理系统,避免手动导入产生的错误。 如果您没有安装过Cocoapods,可以查看官方安装指南(英文) (opens new window)或CocoaPods安装教程(中文) (opens new window)。
sudo gem install cocoapods
pod setup
# 2.1.2 创建Podfile文件
注意
从2.8.5
版本开始,FinClip 小程序 SDK 拆分为多个SDK:FinApplet(核心SDK)
、FinAppletExt
、FinAppletBDMap
、FinAppletGDMap
、FinAppletWebRTC
、FinAppletBLE
、FinAppletAgoraRTC
、FinAppletContact
、FinAppletClipBoard
、FinAppletWXExt
、FinAppletShare
、FinAppletLive
、FinAppletCalendar
。
其中只有FinApplet
是必须的,其他扩展 SDK 可根据实际情况选择集成。
如果你不需要使用扩展 SDK,那么在podfile
中只依赖FinApplet
即可。如果你需要使用扩展 SDK 中的 API,那么你还需要依赖FinAppletExt
。
- 当你在使用
Map
组件的功能时,如果想使用三方地图来实现的话,可引用FinAppletBDMap(百度地图)
或FinAppletGDMap(高德地图)
,默认情况下则由原生地图实现; - 如果需要在小程序中使用WebRTC功能,可以在
podfile
中添加FinAppletWebRTC
依赖,这个库是我们基于Google WebRTC库
的二次封装库,支持iOS9
以上系统版本; - 如果需要在小程序中使用蓝牙功能,可以在
podfile
中添加FinAppletBLE
依赖; - 如果需要在小程序中使用
live-pusher
,live-player
功能,可以在podfile
中添加FinAppletLive
依赖; - 如果需要在小程序中使用
addPhoneContact
,添加手机通讯录联系人,可以在podfile
中添加FinAppletContact
依赖; - 如果需要在小程序中使用剪贴板功能,可以在
podfile
中添加FinAppletClipBoard
依赖; - 如果需要在小程序中接入微信的登录,支付,获取用户信息等能力,可以在
podfile
中添加FinAppletWXExt
依赖; - 如果需要在小程序中接入分享到微信好友,朋友圈,网页链接,并能打开对应的小程序和分享时所在的页面的能力,可以在
podfile
中添加FinAppletShare
依赖; - 如果需要在小程序中使用日历功能,可以在
podfile
中添加FinAppletCalendar
依赖;
注意
在使用FinAppletWXExt
,FinAppletShare
时,需要按照 微信接入指南-iOS 接入指南 (opens new window) 进行配置,具体有如下内容:
- 配置应用的
Universal Links
; - 打开
Associated Domains
开关,将Universal Links
域名加到配置上; - 在工程的Target -> 【Info】 -> 【URL Types】,新增一个
URL Schemes
(key为weixin,value为wx+在微信申请的Appid); - 在工程
info.plist
中增加应用访问白名单LSApplicationQueriesSchemes
,对应的要填写的值为wechat
,weixin
,weixinULAPI
。记得在苹果开发者中心App ID Configuration
处勾选Associated Domains
。 - 如果遇到引用微信头文件报错,把 target 下的 Build Settings 中的 Allow Non-modular includes in Framework Modules 设置成YES。
在Xcode
项目的根目录下,新建一个Podfile
文件,在Podfile
文件中添加对小程序SDK的依赖:
pod 'FinApplet'
pod 'FinAppletExt'
pod 'FinAppletBDMap'
pod 'FinAppletGDMap'
pod 'FinAppletWebRTC'
pod 'FinAppletBLE'
pod 'FinAppletAgoraRTC'
pod 'FinAppletContact'
pod 'FinAppletClipBoard'
pod 'FinAppletWXExt'
pod 'FinAppletShare'
pod 'FinAppletLive'
pod 'FinAppletCalendar'
Podfile示例:
platform :ios, "9.0"
inhibit_all_warnings!
target "FinoAppletDemo" do
pod 'FinApplet'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['ENABLE_STRICT_OBJC_MSGSEND'] = 'NO'
config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'NO'
end
end
end
# 2.1.3 安装或更新依赖
然后,执行 pod update
或者 pod install
即可。
# 2.1.4 打开工程
执行完 pod update
或者 pod install
,打开工程目录,找到xxx.xcworkspace
文件,双击打开即可。
# 2.2 手动集成
为了方便开发者快速体验运行以及使用模拟器开发调试,我们的SDK中包含x86_64
架构,所以在上架AppStore
之前,一定要记得删除x86_64
架构。
您可以自己手动删除,也可以自己网上找脚本删除,或者按照3.2.4
给工程配置脚本。工程配置脚本,开发调试依然可以使用模拟器,但是archive
时,会自动去除模拟器架构。
当然,你也可以说明只需要真机架构,那么我们就只交付包含真机架构的SDK。
含x86_64
和不含x86_64
架构的SDK下载地址如下,如果需要下载其他版本,替换2.41.5即可:
含模拟器x86:
https://app.finogeeks.com/finchat/sdk/FinApplet-2.41.5.zip https://app.finogeeks.com/finchat/sdk/FinAppletExt-2.41.5.zip
不含模拟器x86:
https://app.finogeeks.com/finchat/sdk/FinApplet-Min-2.41.5.zip https://app.finogeeks.com/finchat/sdk/FinAppletExt-Min-2.41.5.zip
注意
由于百度地图、高德地图、腾讯地图、微信SDK都是静态库,所以FinAppletBDMap(百度地图)
、FinAppletGDMap(高德地图)
、FinAppletTXMap(腾讯地图)
、FinAppletWXExt(微信拓展SDK)
、FinAppletShare(分享SDK)
也均为静态库。
# 2.2.1 集成步骤
2.2.1.1 添加SDK至工程
将FinApplet.framework拖进工程。
当然,如果你需要用到FinAppletExt
、FinAppletWebRTC
、FinAppletBLE
、FinAppletAgoraRTC
、FinAppletContact
中的 API,那么,你还得把FinAppletExt.framework
、FinAppletWebRTC.framework
、FinAppletBLE.framework
、FinAppletAgoraRTC.framework
、FinAppletContact.framework
、FinAppletClipBoard.framework
、FinAppletCalendar.framework
也拖进工程。
如果你需要用到FinAppletLive
中的 API,那么,你还得把FinAppletLive.framework
、以及我们定制化的WebRTC.framework
拖进工程。
2.2.1.2 修改工程配置
则需要按照如下配置即可:
如果你需要用到FinAppletExt
、FinAppletWebRTC
、FinAppletBLE
、FinAppletAgoraRTC
、FinAppletContact
、FinAppletClipBoard
、FinAppletGDMap
、FinAppletBDMap
、FinAppletLive
、FinAppletCalendar
中的 API,那么,你还需要把对应的framework
也添加进Copy Files
中。
注意
FinAppletWebRTC.framework
是基于 Google 的 WebRTC 库做的二次封装,所以也需要导入GoogleWebRTC库 (opens new window)(需科学上网),如果因网络问题不能下载也可以在我们平台下载GoogleWebRTC库 (opens new window);FinAppletGDMap.framework
是基于高德地图 SDK 做的二次封装,集成需要导入高德地图AMap3DMap-NO-IDFA
、AMapLocation-NO-IDFA
、AMapSearch-NO-IDFA
这 3 个 SDK ,2.37.9
及以上版本可以使用最新的9.40
版本,2.37.9
之前的版本需要用高德地图9.4.0
之前的版本,可以去高德地图官网 (opens new window)下载相关 SDK ;FinAppletBDMap.framework
是基于百度地图 SDK 做的二次封装,需要集成导入百度地图BMKLocationKit
、BaiduMapKit/Map
、BaiduMapKit/Search
这 3 个 SDK ,可以去百度地图官网 (opens new window)下载相关 SDK ;FinAppletTXMap.framework
是基于腾讯地图 SDK 做的二次封装,需要集成导入腾讯地图Tencent-MapSDK
、FinAppletTencentLBSp
这 2 个 SDK ,可以去腾讯地图官网 (opens new window)下载相关 SDK ;FinAppletAgoraRTC.framework
是基于声网 SDK 做的二次封装,可以去声网 (opens new window)下载对应 SDK 导入到工程;FinAppletWXExt
、FinAppletShare
是基于微信终端 SDK 做的二次封装,可以去微信开放平台 (opens new window)下载sdk包导入到工程。FinAppletLive
目前只支持arm64
架构。并且不支持跟FinAppletWebRTC
同时使用。
2.2.1.3 打开工程
双击xxxx.xcodeproj
,打开工程。
2.2.1.4 配置archive脚本
小程序 SDK 中包含x86_64
架构,便于我们开发时用模拟器调试。但是x86_64
架构的SDK
,打包上传应用市场时会报错,所以配置一个打包时自动去除模拟器架构的脚本,可以让我们既可以用模拟器开发调试,又能正常提交应用市场。
当然,你也可以找我们要一个不包含模拟器的SDK。
脚本内容如下:
#!/bin/sh
# Strip invalid architectures
strip_invalid_archs() {
binary="$1"
echo "current binary ${binary}"
# Get architectures for current file
archs="$(lipo -info "$binary" | rev | cut -d ':' -f1 | rev)"
stripped=""
for arch in $archs; do
if ! [[ "${ARCHS}" == *"$arch"* ]]; then
if [ -f "$binary" ]; then
# Strip non-valid architectures in-place
lipo -remove "$arch" -output "$binary" "$binary" || exit 1
stripped="$stripped $arch"
fi
fi
done
if [[ "$stripped" ]]; then
echo "Stripped $binary of architectures:$stripped"
fi
}
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
strip_invalid_archs "$FRAMEWORK_EXECUTABLE_PATH"
done
请注意:
如果集成完后运行到模拟器上报如下错误:Building for iOS Simulator, but the linked and embedded framework 'FinApplet.framework' was built for iOS + iOS Simulator.
则需要按照如下方式修改。
解决办法:
如下图修改Validate Workspace
为Yes
后,可以重新编译通过;之后可以改回成NO
,就不会报错了。
# 2.3 Swift 工程集成OC第三方库
如果你的工程是用 Swift 写的,则集成 OC 第三方库需要额外配置。
如果你的工程从没添加过 OC 文件,则新建一个 OC 文件时,会询问你是否自动生成桥接文件,点
Create Bridge Header
以生成头文件。如果你的工程添加过 OC 文件,但没有生成桥接文件,则需要自己手动新建一个 Header ,命名为
"{target名-Bridging-Header.h}"
,如"SwiftDemo-Bridging-Header.h"
。并且在项目的 targets 里的 Build Settings 选项里,找到 Objective-c Bridging Header 选项,将这一项设置为刚刚创建的.h文件,如"SwiftDemo/SwiftDemo-Bridging-Header.h"
。(其中 SwiftDemo 是 target 名)往该文件中添加一行代码:
#include <FinApplet/FinApplet.h>
然后 Swift 工程就可以使用 FinApplet 的 OC 第三方库了。
# 3. 增加权限描述
根据您的实际需求,集成响应的SDK,并在工程info.plist
文件中增加权限配置
如果您集成所有的 SDK,那么需要配置的权限包括:相册、相机、麦克风、位置、蓝牙、通讯录,日历。这些权限,全都是调用相应的api和组件时才会触发。
权限名称 | 权限对应的 KEY |
---|---|
相册读取 | NSPhotoLibraryUsageDescription |
相册写入 | NSPhotoLibraryAddUsageDescription |
相机 | NSCameraUsageDescription |
麦克风 | NSMicrophoneUsageDescription |
位置 | NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription、NSLocationWhenInUseUsageDescription |
蓝牙 | NSBluetoothAlwaysUsageDescription、NSBluetoothPeripheralUsageDescription |
通讯录 | NSContactsUsageDescription |
日历 | NSCalendarsUsageDescription |
其中各个SDK中涉及的权限如下(您可以根据实际情况选择集成):
其中核心SDK(FinApplet)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
相册读取 | NSPhotoLibraryUsageDescription | chooseImage、chooseVideo、chooseMedia |
相册写入 | NSPhotoLibraryAddUsageDescription | saveImageToPhotosAlbum、saveVideoToPhotosAlbum |
相机 | NSCameraUsageDescription | scanCode、chooseImage、chooseVideo、chooseMedia、CameraContext(Camera组件) |
麦克风 | NSMicrophoneUsageDescription | chooseVideo、chooseMedia、CameraContext(Camera组件) |
注意
录制视频时,系统会先后访问相机和麦克风权限。
扩展SDK(FinAppletExt)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
麦克风 | NSMicrophoneUsageDescription | startRecord、RecorderManager |
位置 | NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription、NSLocationWhenInUseUsageDescription | chooseLocation、getLocation、openLocation、choosePoi |
扩展SDK-WebRTC(FinAppletWebRTC)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
相机 | NSCameraUsageDescription | webrtc-video组件 |
麦克风 | NSMicrophoneUsageDescription | webrtc-video组件 |
扩展SDK-BDMap(FinAppletBDMap)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
位置 | NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription、NSLocationWhenInUseUsageDescription | Map组件 |
扩展SDK-GDMap(FinAppletGDMap)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
位置 | NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription、NSLocationWhenInUseUsageDescription | Map组件 |
扩展SDK-BLE(FinAppletBLE)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
蓝牙 | NSBluetoothAlwaysUsageDescription、NSBluetoothPeripheralUsageDescription | openBluetoothAdapter |
扩展SDK-AgoraRTC(FinAppletAgoraRTC)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
相机 | NSCameraUsageDescription | live-pusher,live-player组件 |
麦克风 | NSMicrophoneUsageDescription | live-pusher,live-player组件 |
扩展SDK-Contact(FinAppletContact)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
通讯录 | NSContactsUsageDescription | addPhoneContact |
分享SDK-shareSDK(FinAppletShare)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
相册写入 | NSPhotoLibraryAddUsageDescription | 保存按钮 |
扩展SDK-Live(FinAppletLive)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
相机 | NSCameraUsageDescription | live-pusher 组件 |
麦克风 | NSMicrophoneUsageDescription | live-pusher 组件 |
扩展SDK-Calendar(FinAppletCalendar)涉及的权限:
权限名称 | 权限对应的 KEY | 权限涉及的 API |
---|---|---|
日历 | NSCalendarsUsageDescription | addPhoneRepeatCalendar,addPhoneCalendarapi |
注意
如果你的工程里已经配置过这些权限,那就不用再添加了。
另外,如果你的小程序中的请求或者网页有使用到http
协议的,还需要在工程里配置如下参数:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
也就是【App Transport Security Settings】-> 【Allow Arbitrary Loads】设置为YES。
# 4. 添加URL Type
注意
第4步和第7步不是必须项,如果您的 App 会通过其他 App(safari、微信等)打开您 App 中的小程序,那么就必须配置第4步和第7步。
选择 Target -> 【Info】 -> 【URL Types】,新增一个URL Schemes(URL Schemes的格式是fat+sdkKey的md5。)
先将 SDK KEY 生成 16 位小写 MD5 ,然后在加上fat
前缀。
关于如何使用,可参考使用路由的形式打开小程序。
# 5. 设置工程支持的方向
注意
1.由于小程序的公共UI,比如loading页、关于、设置、投诉反馈等页面都是固定竖屏,所以App需要勾选Portrait。 2.小程序内的app.json和page.json里pageOrientation可以设置为portrait、landscape、auto,所以App需要支持横屏和竖屏。
具体的关于SDK横竖屏的处理场景见SDK中横竖屏的详细说明
# 6. 添加SDK头文件
在需要使用 FinClip 小程序 SDK 的地方,添加如下代码:
#import <FinApplet/FinApplet.h>
如果还集成了扩展 SDK,那么调用扩展 SDK 中的 API,还需要加上下面的代码:
#import <FinAppletExt/FinAppletExt.h>
如果要使用封装的百度地图 SDK,还需要加上下面的代码:
#import <FinAppletBDMap/FinAppletBDMap.h>
如果要使用封装的高德地图 SDK,还需要加上下面的代码:
#import <FinAppletGDMap/FinAppletGDMap.h>
如果要使用封装的腾讯地图 SDK,还需要加上下面的代码:
#import <FinAppletTXMap/FinAppletTXMap.h>
如果要使用封装的 WebRTC 库,还需要加上下面的代码:
#import <FinAppletWebRTC/FinAppletWebRTC.h>
如果需要使用蓝牙库,还需要加上下面的代码:
#import <FinAppletBLE/FinAppletBLE.h>
如果需要使用封装的声网 SDK,还需要加上下面的代码:
#import <FinAppletAgoraRTC/FinAppletAgoraRTC.h>
如果需要使用封装的联系人 SDK,还需要加上下面的代码:
#import <FinAppletContact/FinAppletContact.h>
如果需要使用封装的剪贴板 SDK,还需要加上下面的代码:
#import <FinAppletClipBoard/FinAppletClipBoard.h>
如果需要使用封装的微信扩展 SDK,还需要加上下面的代码:
#import <FinAppletWXExt/FinAppletWXExt.h>
如果需要使用封装的分享 SDK,还需要加上下面的代码:
#import <FinAppletShare/FinAppletShare.h>
如果需要使用封装的直播 SDK,还需要加上下面的代码:
#import <FinAppletLive/FinAppletLive.h>
如果需要使用封装的日历 SDK,还需要加上下面的代码:
#import <FinAppletCalendar/FinAppletCalendar.h>
当然,最方便的方式是在pch
文件中添加以上代码,这样在使用的地方就不用再引用了。
# 7. 初始化 SDK
在工程的AppDelegate
中的以下方法中,调用 SDK 的初始化方法。
注意
从2.13.109
版本开始,FinClip 小程序 SDK 支持配置多个服务器信息,可以同时打开多个不同服务器上的小程序,所以初始化方式有所变更,您可以将服务器配置信息写入plist
文件,然后按照如下示例初始化。
NSString *plistPath = [[NSBundle mainBundle] pathForResource:@"servers" ofType:@"plist"];
NSArray *array = [NSArray arrayWithContentsOfFile:plistPath];
NSMutableArray *storeArrayM = [NSMutableArray array];
for (NSDictionary *dict in array) {
FATStoreConfig *storeConfig = [[FATStoreConfig alloc] init];
storeConfig.sdkKey = dict[@"sdkKey"];
storeConfig.sdkSecret = dict[@"sdkSecret"];
storeConfig.apiServer = dict[@"apiServer"];
storeConfig.apmServer = dict[@"apmServer"];
if ([@"SM" isEqualToString:dict[@"cryptType"]]) {
storeConfig.cryptType = FATApiCryptTypeSM;
} else {
storeConfig.cryptType = FATApiCryptTypeMD5;
}
[storeArrayM addObject:storeConfig];
}
FATConfig *config = [FATConfig configWithStoreConfigs:storeArrayM];
[[FATClient sharedClient] initWithConfig:config error:nil];
也可以这样初始化:
NSMutableArray *storeArrayM = [NSMutableArray array];
FATStoreConfig *storeConfig = [[FATStoreConfig alloc] init];
storeConfig.sdkKey = @"您的sdkKey信息";
storeConfig.sdkSecret = @"您的sdkSecret信息";
storeConfig.apiServer = @"服务器域名";
storeConfig.apmServer = @"apm统计事件的域名";
[storeArrayM addObject:storeConfig];
FATStoreConfig *storeConfig2 = [[FATStoreConfig alloc] init];
storeConfig2.sdkKey = @"您的sdkKey信息";
storeConfig2.sdkSecret = @"您的sdkSecret信息";
storeConfig2.apiServer = @"服务器域名";
storeConfig2.apmServer = @"apm统计事件的域名";
storeConfig2.cryptType = FATApiCryptTypeSM;
[storeArrayM addObject:storeConfig2];
FATConfig *config = [FATConfig configWithStoreConfigs:storeArrayM];
[[FATClient sharedClient] initWithConfig:config error:nil];
当需要使用百度地图/高德地图
来实现MAP
组件的功能时,需要去对应的平台申请 KEY,并进行初始化。
// 准备地图sdk初始化
[FATBDMapComponent setAgreePrivacy:YES];
[FATBDMapComponent setBDMapAppKey:@"申请的key"]
[FATGDMapComponent setGDMapPrivacyShow:AMapPrivacyShowStatusDidShow privacyInfo:AMapPrivacyInfoStatusDidContain PrivacyAgreement:AMapPrivacyAgreeStatusDidAgree];
[FATGDMapComponent setGDMapAppKey:@"申请的key"]
[FATTXMapComponent setPrivacyAgreement:YES];
[FATTXMapComponent setTXMapAppKey:@"申请的key"]
当需要使用WebRTC
组件的功能时,需要进行初始化注册组件。
// WebRTC初始化
[FATWebRTCComponent registerComponent]
当需要使用AgoraRTC
组件的功能时,需要进行初始化注册组件。
// AgoraRTC初始化
[FATAgoraRTCComponent registerComponent]
当需要使用直播能力时,需要进行初始化注册组件。
// 直播组件初始化
#ifdef __arm64__
[FATLiveComponent registerComponent];
#endif
当需要使用addPhoneContact
API 的功能时,需要进行初始化注册组件。
// ContactSDK初始化
[FATContactComponent registerComponent]
当需要使用getClipboardData
,setClipboardData
API 的功能时,需要进行初始化注册组件。
// ClipBoard初始化
[FATClipBoardComponent registerComponent];
当需要使用微信的支付,登录,获取用户信息
等能力时,需要进行初始化注册组件。
// 微信扩展SDL初始化
[FATWXExtComponent registerComponent:@"微信appid" universalLink:@"universalLink"];
并在AppDelegate.m
中增加下面的代码。
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
/* 微信登录和分享 */
if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
return YES;
}
return YES;
}
// iOS 9.0 之前
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
/* 微信登录和分享 */
// `WeChatHandleURLDelegate ` 为 `WXApiDelegate`代理文件
if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{
/* 微信登录和分享 */
if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
return [WXApi handleOpenUniversalLink:userActivity delegate:[FATWXApiManager sharedManager]];
}
当需要使用分享能力时,需要进行初始化注册组件。
// 分享SDK初始化
[FATShareComponent registerComponent:@"微信appid" universalLink:@"universalLink" scheme:@"配置的scheme"];
自2.40.11版本开始,ShareSDK支持自定义分享落地页的链接、分享链接中的ipa文件下载地址,如果需要自定义配置可使用下面的方法:
// 分享SDK的初始化方法 since:2.40.11
/// - Parameters:
/// - appld: 小程序id
/// - customUrl: 自定义分享的短链,可不传
/// - universalLink: universalLink
/// - scheme: 打开App的scheme,如果采用fat+${SDKKey的16位小写md5}的方式生成可以打开对应的小程序。否则只能打开App
/// - appDownloadLink: App的下载链接 可不传
+ (BOOL)registerComponent:(NSString *)appld customUrl:(NSString *)customUrl universalLink:(NSString *)universalLink scheme:(NSString *)scheme appDownloadLink:(NSString *)appDownloadLink;
并在AppDelegate.m
中增加下面的代码。
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
if ([WXApi handleOpenURL:url delegate:[FATShareApiManager sharedManager]]) {
return YES;
}
return YES;
}
// iOS 9.0 之前
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
if ([WXApi handleOpenURL:url delegate:[FATShareApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{
if ([WXApi handleOpenURL:url delegate:[FATShareApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
return [WXApi handleOpenUniversalLink:userActivity delegate:[FATShareApiManager sharedManager]];
}
注意
如果同时使用微信SDK和分享SDK,代理方法的实现类可以只设置[FATWXApiManager sharedManager]
来实现。
如果工程中已经自己实现了微信代理方法的实现类,需要处理微信的请求- (void)onReq:(BaseReq*)req
方法,并处理req为LaunchFromWXReq类型,得到对应的json字符串后,解析参数并通过核心SDK的打开小程序的方法,才能实现点击分享到微信的链接后打开对应的分享小程序,否则流程无法闭环。
下面是实例代码:
- (void)onReq:(BaseReq *)req {
if ([req isKindOfClass:[LaunchFromWXReq class]]) {
LaunchFromWXReq *launchReq = (LaunchFromWXReq *) req;
[self managerDidRecvLaunchFromWXReq:launchReq];
}
}
- (void)managerDidRecvLaunchFromWXReq:(LaunchFromWXReq *)launchReq {
NSString *ext = launchReq.message.messageExt;
NSDictionary *dic = [self dictionaryWithJsonString:ext];
NSString *appId = dic[@"appId"];
[[FATClient sharedClient] closeAllAppletsWithCompletion:^{
[[FATClient sharedClient] startRemoteApplet:appId startParams:@{@"path":dic[@"path"] ? dic[@"path"] : @"", @"query":dic[@"query"] ? dic[@"query"] : @""} InParentViewController:[FATShareTools topViewController] completion:nil];
}];
}
- (NSDictionary *)dictionaryWithJsonString:(NSString *)jsonString {
if (jsonString == nil) {
return nil;
}
NSData *jsonData = [jsonString dataUsingEncoding:NSUTF8StringEncoding];
NSError *err;
NSDictionary *dic = [NSJSONSerialization JSONObjectWithData:jsonData options:NSJSONReadingMutableContainers error:&err];
if(err) {
NSLog(@"json解析失败:%@",err);
return nil;
}
return dic;
}
注意
使用微信扩展SDK必须保证核心SDK版本在2.37.13
或以上,使用分享SDK必须保证核心SDK版本在2.39.11
或以上。
注意
由于FinAppletWXExt需要覆盖buttonOpenTypeDelegate(2.37.13前的版本为FATAppletDelegate)中的open-type相关的方法,具体为chooseAvatar、contact、feedback、getPhoneNumber、launchApp、shareAppMessage六个方法。 因此若您实现了buttonOpenTypeDelegate并实现了以上六个方法,FinAppletWXExt将会接管getPhoneNumber,剩余的五个方法请按以下方式迁移,若您未实现buttonOpenTypeDelegate或没有用到以上六个方法,可以忽略此处,若是既需要集成FinAppletWXExt又需要实现open-type相关的方法,则参考下边的说明。 1.在核心SDK和微信扩展SDK初始化成功后,设置您的代理方法实现类
[FATDelegateClientHelper sharedHelper].buttonOpenTypeDelegate = [FINWXButtonDelegate sharedHelper];
2.实现buttonOpenTypeDelegate的代理方法
- (BOOL)forwardAppletWithInfo:(NSDictionary *)contentInfo completion:(void (^)(FATExtensionCode code, NSDictionary *result))completion {
return YES;
}
- (BOOL)getUserInfoWithAppletInfo:(FATAppletInfo *)appletInfo bindGetUserInfo:(void (^)(NSDictionary *result))bindGetUserInfo {
return YES;
}
- (BOOL)contactWithAppletInfo:(FATAppletInfo *)appletInfo sessionFrom:(NSString *)sessionFrom sendMessageTitle:(NSString *)sendMessageTitle sendMessagePath:(NSString *)sendMessagePath sendMessageImg:(NSString *)sendMessageImg showMessageCard:(BOOL)showMessageCard {
return YES;
}
- (BOOL)getPhoneNumberWithAppletInfo:(FATAppletInfo *)appletInfo bindGetPhoneNumber:(void (^)(NSDictionary *result))bindGetPhoneNumber {
NSLog(@"小程序信息:%@", appletInfo);
return YES;
}
- (BOOL)launchAppWithAppletInfo:(FATAppletInfo *)appletInfo appParameter:(NSString *)appParameter bindError:(void (^)(NSDictionary *result))bindError bindLaunchApp:(void (^)(NSDictionary *result))bindLaunchApp {
return YES;
}
- (BOOL)feedbackWithAppletInfo:(FATAppletInfo *)appletInfo {
return YES;
}
- (BOOL)chooseAvatarWithAppletInfo:(FATAppletInfo *)appletInfo bindChooseAvatar:(void (^)(NSDictionary *result))bindChooseAvatar {
return YES;
}
蓝牙库无需进行初始化,在项目中引用了头文件即可。
注意
2.21.1
以及之后的版本,不再需要调用配置扩展 SDK,SDK 内部会自动判断是否集成扩展 SDK,自动触发配置扩展SDK。
当然,如果您需要使用到扩展 SDK 中的 API,那么您还需要在初始化 SDK 之后,配置扩展 API。 调用一次如下代码即可:
// 准备扩展api
[[FATExtClient sharedClient] fat_prepareExtensionApis];
注意
如果未设置currentUserId
,则缓存数据会缓存到默认目录,获取最近打开小程序列表时,获取到的是默认目录下的小程序。如果要不同用户使用不同的缓存目录,请不同用户设置不同的currentUserId
。
# 8. handleOpenURL处理
小程序支持外部通过链接打开小程序,需要做如下处理。
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
if ([[FATClient sharedClient] handleOpenURL:url]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
if ([[FATClient sharedClient] handleOpenURL:url]) {
return YES;
}
return YES;
}
# 9. 打开小程序
FATAppletRequest *request = [[FATAppletRequest alloc] init];
request.appletId = @"小程序id";
request.apiServer = @"服务器地址";
request.transitionStyle = FATTranstionStyleUp;
request.startParams = startParams;
[[FATClient sharedClient] startAppletWithRequest:request InParentViewController:self completion:^(BOOL result, FATError *error) {
NSLog(@"打开小程序:%@", error);
} closeCompletion:^{
NSLog(@"关闭小程序");
}];
其他关于 FinClip 小程序 SDK 的 API介绍,请查看 API 说明文档。
# 10. 扩展SDK
对扩展SDK使用的快速集成说明,详细使用方式参考上面的 集成SDK
# 10.1 微信扩展SDK
微信SDK的快捷接入,提供调起微信通过微信小程序获得登录、用户信息、手机号、支付的能力。 快捷集成方式:
pod 'FinAppletWXExt'
注意
在使用FinAppletWXExt
时,需要按照 微信接入指南-iOS 接入指南 (opens new window) 进行配置,具体有如下内容:
- 配置应用的
Universal Links
; - 打开
Associated Domains
开关,将Universal Links
域名加到配置上; - 在工程的Target -> 【Info】 -> 【URL Types】,新增一个
URL Schemes
(key为weixin,value为wx+在微信申请的Appid); - 在工程
info.plist
中增加应用访问白名单LSApplicationQueriesSchemes
,对应的要填写的值为wechat
,weixin
,weixinULAPI
。记得在苹果开发者中心App ID Configuration
处勾选Associated Domains
。
进行初始化注册组件:
// 微信扩展SDL初始化
[FATWXExtComponent registerComponent:@"微信appid" universalLink:@"universalLink"];
并在AppDelegate.m
中增加下面的代码。
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
/* 微信登录和分享 */
if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
return YES;
}
return YES;
}
// iOS 9.0 之前
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
/* 微信登录和分享 */
// `WeChatHandleURLDelegate ` 为 `WXApiDelegate`代理文件
if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{
/* 微信登录和分享 */
if ([WXApi handleOpenURL:url delegate:[FATWXApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
return [WXApi handleOpenUniversalLink:userActivity delegate:[FATWXApiManager sharedManager]];
}
注意
使用微信扩展SDK必须保证核心SDK版本在2.37.13
或以上。
注意
由于FinAppletWXExt
需要覆盖buttonOpenTypeDelegate(2.37.13前的版本为FATAppletDelegate)中的open-type相关的方法,具体为chooseAvatar
、contact
、feedback
、getPhoneNumber
、launchApp
、shareAppMessage
六个方法。
因此若您实现了buttonOpenTypeDelegate
并实现了以上六个方法,FinAppletWXExt将会接管getPhoneNumber,剩余的五个方法请按以下方式迁移,若您未实现buttonOpenTypeDelegate或没有用到以上六个方法,可以忽略此处,若是既需要集成FinAppletWXExt又需要实现open-type相关的方法,则参考下边的说明。
1.在核心SDK和微信扩展SDK初始化成功后,设置您的代理方法实现类
[FATDelegateClientHelper sharedHelper].buttonOpenTypeDelegate = [FINWXButtonDelegate sharedHelper];
2.实现buttonOpenTypeDelegate的代理方法
- (BOOL)forwardAppletWithInfo:(NSDictionary *)contentInfo completion:(void (^)(FATExtensionCode code, NSDictionary *result))completion {
return YES;
}
- (BOOL)getUserInfoWithAppletInfo:(FATAppletInfo *)appletInfo bindGetUserInfo:(void (^)(NSDictionary *result))bindGetUserInfo {
return YES;
}
- (BOOL)contactWithAppletInfo:(FATAppletInfo *)appletInfo sessionFrom:(NSString *)sessionFrom sendMessageTitle:(NSString *)sendMessageTitle sendMessagePath:(NSString *)sendMessagePath sendMessageImg:(NSString *)sendMessageImg showMessageCard:(BOOL)showMessageCard {
return YES;
}
- (BOOL)getPhoneNumberWithAppletInfo:(FATAppletInfo *)appletInfo bindGetPhoneNumber:(void (^)(NSDictionary *result))bindGetPhoneNumber {
NSLog(@"小程序信息:%@", appletInfo);
return YES;
}
- (BOOL)launchAppWithAppletInfo:(FATAppletInfo *)appletInfo appParameter:(NSString *)appParameter bindError:(void (^)(NSDictionary *result))bindError bindLaunchApp:(void (^)(NSDictionary *result))bindLaunchApp {
return YES;
}
- (BOOL)feedbackWithAppletInfo:(FATAppletInfo *)appletInfo {
return YES;
}
- (BOOL)chooseAvatarWithAppletInfo:(FATAppletInfo *)appletInfo bindChooseAvatar:(void (^)(NSDictionary *result))bindChooseAvatar {
return YES;
}
# 10.2 地图扩展SDK
当你在使用Map
组件的功能时,如果想使用三方地图来实现的话,可引用FinAppletBDMap(百度地图)
、FinAppletGDMap(高德地图)
、FinAppletTXMap(腾讯地图)
,默认情况下则由FinAppletExt(原生地图)
实现。
高德地图SDK最多允许app同时有10个map视图对象
当超过10个map视图对象时,新的地图内容会显示黑屏。所以,当使用高德地图来实现map组件(即依赖高德地图扩展SDK)时,需要小程序在页面的onHide()里移除销毁map,然后在onShow()里创建地图和添加地图内容。
快捷集成方式:
#pod 'FinAppletBDMap'
#pod 'FinAppletTXMap'
#pod 'FinAppletGDMap' // 选择一个放开即可
pod 'FinAppletExt'
进行初始化注册组件:
当需要使用百度地图、高德地图、腾讯地图
来实现MAP
组件的功能时,需要去对应的平台申请 KEY,并进行初始化。
#import <FinAppletExt/FinAppletExt.h>
// 根据你实际情况,引入对应的头文件
#import <FinAppletBDMap/FinAppletBDMap.h>
#import <FinAppletGDMap/FinAppletGDMap.h>
#import <FinAppletTXMap/FinAppletTXMap.h>
// 准备地图sdk初始化
[FATBDMapComponent setAgreePrivacy:YES];
[FATBDMapComponent setBDMapAppKey:@"申请的key"]
[FATGDMapComponent setGDMapPrivacyShow:AMapPrivacyShowStatusDidShow privacyInfo:AMapPrivacyInfoStatusDidContain PrivacyAgreement:AMapPrivacyAgreeStatusDidAgree];
[FATGDMapComponent setGDMapAppKey:@"申请的key"]
[FATTXMapComponent setPrivacyAgreement:YES];
[FATTXMapComponent setTXMapAppKey:@"申请的key"]
# 10.3 蓝牙扩展SDK
如果需要在小程序中使用蓝牙功能,可引入蓝牙扩展SDK 快捷集成方式:
pod 'FinAppletBLE'
蓝牙SDK不需要初始化,引入头文件即可
#import <FinAppletBLE/FinAppletBLE.h>
# 10.4 声网扩展SDK
备注
建议使用 live SDK 代替声网SDK
如果需要在小程序中使用live-pusher
,live-player
功能,可引入声网SDK。
快捷集成方式:
pod 'FinAppletAgoraRTC'
进行初始化注册组件:
#import <FinAppletAgoraRTC/FinAppletAgoraRTC.h>
// AgoraRTC初始化
[FATAgoraRTCComponent registerComponent]
# 10.5 WebRTC扩展SDK
如果需要在小程序中使用WebRTC功能,可引入WebRTCSDK 快捷集成方式:
pod 'FinAppletWebRTC'
进行初始化注册组件:
#import <FinAppletWebRTC/FinAppletWebRTC.h>
// WebRTC初始化
[FATWebRTCComponent registerComponent]
# 10.6 联系人扩展SDK
如果需要在小程序中使用addPhoneContact
,添加手机通讯录联系人,可引入联系人SDK
快捷集成方式:
pod 'FinAppletContact'
进行初始化注册组件:
#import <FinAppletContact/FinAppletContact.h>
// ContactSDK初始化
[FATContactComponent registerComponent]
# 10.7 剪贴板扩展SDK
如果需要在小程序中使用剪贴板功能,可引入剪贴板SDK 快捷集成方式:
pod 'FinAppletClipBoard'
进行初始化注册组件:
#import <FinAppletClipBoard/FinAppletClipBoard.h>
// ClipBoard初始化
[FATClipBoardComponent registerComponent];
# 10.8 分享SDK
如果需要在小程序中分享功能,可引入分享SDK 快捷集成方式:
pod 'FinAppletShare'
进行初始化注册组件:
#import <FinAppletShare/FinAppletShare.h>
// share初始化
[FATShareComponent registerComponent:@"微信appid" universalLink:@"universalLink" scheme:@"配置的scheme"];
自2.40.11版本开始,ShareSDK支持自定义分享落地页的链接、分享链接中的ipa文件下载地址,如果需要自定义配置可使用下面的方法:
// 分享SDK的初始化方法 since:2.40.11
/// - Parameters:
/// - appld: 小程序id
/// - customUrl: 自定义分享的短链,可不传
/// - universalLink: universalLink
/// - scheme: 打开App的scheme,如果采用fat+${SDKKey的16位小写md5}的方式生成可以打开对应的小程序。否则只能打开App
/// - appDownloadLink: App的下载链接 可不传
+ (BOOL)registerComponent:(NSString *)appld customUrl:(NSString *)customUrl universalLink:(NSString *)universalLink scheme:(NSString *)scheme appDownloadLink:(NSString *)appDownloadLink;
并在AppDelegate.m
中增加下面的代码。
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
if ([WXApi handleOpenURL:url delegate:[FATShareApiManager sharedManager]]) {
return YES;
}
return YES;
}
// iOS 9.0 之前
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
if ([WXApi handleOpenURL:url delegate:[FATShareApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url{
if ([WXApi handleOpenURL:url delegate:[FATShareApiManager sharedManager]]) {
return YES;
}
return YES;
}
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
return [WXApi handleOpenUniversalLink:userActivity delegate:[FATShareApiManager sharedManager]];
}
# 10.9 直播SDK(live SDK)
如果需要在小程序中使用直播功能,可引入直播SDK 快捷集成方式:
pod 'FinAppletLive' # 注意不能同时集成 FinAppletLive 和 FinAppletWebRTC
进行初始化注册组件:
#import <FinAppletLive/FinAppletLive.h>
// 默认值为NO。当设置为YES表示使用内置的live组件
FATUIConfig *uiConfig = [[FATUIConfig alloc] init];
uiConfig.useNativeLiveComponent = YES;
// 直播初始化
#ifdef __arm64__
[FATLiveComponent registerComponent];
#endif
# 10.10 日历扩展SDK
如果需要在小程序中使用日历功能,可引入日历扩展SDK 快捷集成方式:
pod 'FinAppletCalendar'
日历SDK不需要初始化,引入头文件即可
#import <FinAppletCalendar/FinAppletCalendar.h>