FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

# iOS 集成

集成样例代码

可以在这里获取集成样例代码https://github.com/finogeeks/mop-ios-demo (opens new window)

若您所在的环境无法访问 Github,也可以点击这里访问 gitee (opens new window) 的镜像仓库。

# 1. 获取小程序凭据

使用 SDK 需要申请 SDK KEY 及 SDK SECRET ,只有在 SDK 初始化的时候配置了正确的 SDK KEY 及 SDK SECRET ,才能初始化成功并正常使用。

# 1.1 创建应用

注册用户需要登录「应用管理-新增合作应用」,完成应用创建;
image.png

# 1.2 获取 SDK KEY 及 SDK SECRET

创建应用并添加 Bundle ID 后,若需要导出对应的 SDK KEY 与 SDK SECRET,请选择对应 Bundle ID 后的「复制」,即可通过Ctrl+VCommand+V进行粘贴操作;
image.png

其中:

  • SDK KEY:是合作应用能使用小程序SDK的凭证,如果SDK Key校验失败,则SDK的所有Api都无法使用。
  • SDK SECERT:是访问服务的安全证书,不要给第三方。

提示

关于创建应用与获取 SDK KEY 及 SDK SECRET 的详细操作,见「介绍-操作指引-企业端操作指引-7.关联移动应用」一节。

# 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。其中只有FinApplet是必须的,其他扩展SDK可根据实际情况选择集成。

所以,如果你不需要使用扩展SDK,那么在podfile中只依赖FinApplet即可。如果你需要使用扩展SDK中的api,那么你还需要依赖FinAppletExt

当你在使用map组件的功能时,如果想使用三方地图来实现的话,可引用FinAppletBDMap(百度地图)或FinAppletGDMap(高德地图),默认由原生地图实现。

如果需要在小程序中使用WebRTC功能,可以在podfile中添加FinAppletWebRTC依赖,这个库是我们基于GoogleWebRTC的二次封装库,支持iOS9以上系统版本。

如果需要在小程序中使用蓝牙功能,可以在podfile中添加FinAppletBLE依赖。

如果需要在小程序中使用live-pusher,live-player功能,可以在podfile中添加FinAppletAgoraRTC依赖。

如果需要在小程序中使用addPhoneContact,添加手机通讯录联系人,可以在podfile中添加FinAppletContact依赖。

如果需要在小程序中使用剪贴板功能,可以在podfile中添加FinAppletClipBoard依赖。

在 Xcode 项目的根目录下,新建一个Podfile文件,在Podfile文件中添加对小程序SDK的依赖:

pod 'FinApplet'
pod 'FinAppletExt'
pod 'FinAppletBDMap'
pod 'FinAppletGDMap'
pod 'FinAppletWebRTC'
pod 'FinAppletBLE'
pod 'FinAppletAgoraRTC'
pod 'FinAppletContact'
pod 'FinAppletClipBoard'

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。

注意

  1. 由于百度地图和高德地图都是静态库,所以FinAppletBDMap(百度地图)或FinAppletGDMap(高德地图)也均为静态库。

# 2.2.1 集成动态库

2.2.1.1 添加SDK至工程

将FinApplet.framework拖进工程。
image.png

当然,如果你需要用到FinAppletExt、FinAppletWebRTC、FinAppletBLE、FinAppletAgoraRTC、FinAppletContact中的api,那么,你还得把FinAppletExt.framework、FinAppletWebRTC.framework、FinAppletBLE.framework、FinAppletAgoraRTC.framework、FinAppletContact.framework、FinAppletClipBoard.framework也拖进工程。

2.2.1.2 修改工程配置

则需要按照如下配置即可:
image.png

如果你需要用到FinAppletExt、FinAppletWebRTC、FinAppletBLE、FinAppletAgoraRTC、FinAppletContact、FinAppletClipBoard中的api,那么,你还得把FinAppletExt.framework、FinAppletWebRTC.framework、FinAppletBLE.framework、FinAppletAgoraRTC.framework、FinAppletContact.framework、FinAppletClipBoard.framework也添加进Copy Files中。

2.2.1.3 打开工程

双击xxxx.xcodeproj,打开工程。

2.2.1.4 配置archive脚本

SDK中包含x86_64架构,便于我们开发时用模拟器调试。但是x86_64架构的SDK,打包上传应用市场时会报错,所以配置一个打包时自动去除模拟器架构的脚本,可以让我们既可以用模拟器开发调试,又能正常提交应用市场。

当然,你也可以找我们要一个不包含模拟器的SDK。
image.png
image.png

脚本内容如下:

#!/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

# 2.3 Swift 工程集成OC第三方库

如果你的工程是用 Swift 写的,则集成 OC 第三方库需要额外配置。

  1. 如果你的工程从没添加过 OC 文件,则新建一个 OC 文件时,会询问你是否自动生成桥接文件,点 Create Bridge Header 以生成头文件。 image.jpg

  2. 如果你的工程添加过 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 名) image.jpg

  3. 往该文件中添加一行代码:

#include <FinApplet/FinApplet.h>

然后Swift工程就可以使用 FinApplet 的 OC 第三方库了。

# 3. 增加权限描述

根据您的实际需求,集成响应的SDK,并在工程info.plist文件中增加权限配置

如果您集成所有的SDK,那么需要配置的权限包括:相册、相机、麦克风、位置、蓝牙。

权限名称 权限对应的key
相册读取 NSPhotoLibraryUsageDescription
相册写入 NSPhotoLibraryAddUsageDescription
相机 NSCameraUsageDescription
麦克风 NSMicrophoneUsageDescription
位置 NSLocationAlwaysAndWhenInUseUsageDescription、NSLocationAlwaysUsageDescription、NSLocationWhenInUseUsageDescription
蓝牙 NSBluetoothAlwaysUsageDescription、NSBluetoothPeripheralUsageDescription
通讯录 NSContactsUsageDescription

其中各个SDK中涉及的权限如下(您可以根据实际情况选择集成): 其中核心SDK(FinApplet)涉及的权限:

权限名称 权限对应的key 权限涉及的api
相册读取 NSPhotoLibraryUsageDescription chooseImage、chooseVideo
相册写入 NSPhotoLibraryAddUsageDescription saveImageToPhotosAlbum、saveVideoToPhotosAlbum
相机 NSCameraUsageDescription scanCode、chooseImage、chooseVideo、CameraContext(Camera组件)
麦克风 NSMicrophoneUsageDescription chooseVideo、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 蓝牙-通用、蓝牙-低功耗中心设备、蓝牙-低功耗外围设备、蓝牙-信标一些列api

扩展SDK-AgoraRTC(FinAppletAgoraRTC)涉及的权限:

权限名称 权限的key 权限涉及的api
相机 NSCameraUsageDescription live-pusher,live-player组件
麦克风 NSMicrophoneUsageDescription live-pusher,live-player组件

扩展SDK-Contact(FinAppletContact)涉及的权限:

权限名称 权限的key 权限涉及的api
通讯录 NSContactsUsageDescription addPhoneContact

注意

如果你的工程里已经配置过这些权限,那就不用再添加了。

另外,如果你的小程序中的请求或者网页有使用到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。)

先将sdkKey生成16位小写md5,然后在加上fat前缀。
image.jpg


关于如何使用,可参考使用路由的形式打开小程序

# 5. 添加SDK头文件

在需要使用FinClip小程序SDK的地方,添加如下代码:

#import <FinApplet/FinApplet.h>

如果还集成了扩展SDK,那么调用扩展SDK中的api,还需要加上下面的代码:

#import  <FinAppletExt/FinAppletExt.h>

如果要使用封装的百度地图sdk,还需要加上下面的代码:

#import  <FinAppletBDMap/FinAppletBDMap.h>

如果要使用封装的高德地图sdk,还需要加上下面的代码:

#import  <FinAppletGDMap/FinAppletGDMap.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>

当然,最方便的方式是在 pch 文件中添加以上代码,这样在使用的地方就不用再引用了。

# 6. 初始化 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 setBDMapAppKey:@"申请的key"]
[FATGDMapComponent setGDMapAppKey:@"申请的key"]

当需要使用WebRTC组件的功能时,需要进行初始化注册组件。

// WebRTC初始化
[FATWebRTCComponent registerComponent]

当需要使用AgoraRTC组件的功能时,需要进行初始化注册组件。

// AgoraRTC初始化
[FATAgoraRTCComponent registerComponent]

当需要使用addPhoneContact Api的功能时,需要进行初始化注册组件。

// ContactSDK初始化
[FATContactComponent registerComponent]

当需要使用getClipboardData,setClipboardData Api的功能时,需要进行初始化注册组件。

// ClipBoard初始化
[FATClipBoardComponent registerComponent];

蓝牙库无需进行初始化,在项目中引用了头文件即可。

注意

2.21.1 以及之后的版本,不再需要调用配置扩展SDK,SDK 内部会自动判断是否集成扩展SDK,自动触发配置扩展SDK。

当然,如果您需要使用到扩展SDK中的Api,那么您还需要在初始化SDK之后,配置扩展api。 调用一次如下代码即可:

// 准备扩展api
[[FATExtClient sharedClient] fat_prepareExtensionApis];

注意

如果未设置currentUserId,则缓存数据会缓存到默认目录,获取最近打开小程序列表时,获取到的是默认目录下的小程序。如果要不同用户使用不同的缓存目录,请不同用户设置不同的currentUserId。

# 7. 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;
}

# 8. 打开小程序

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 说明文档

© 2022 FinClip with ❤

👋🏻 嘿,你好!

「FinClip」是一套基于云原生框架设计的小程序容器。能够让任何移动应用在集成小程序SDK之后,获得可用、安全的小程序运行能力。

>> 点我免费注册体验

查看产品文档
了解与 FinClip 相关的一切信息

产品博客 👈  了解产品更新与核心功能介绍
资源下载 👈  获取小程序 SDK 与开发工具
文档中心 👈  查询 FinClip 小程序开发指南与答疑

商务咨询热线
预约 FinClip 产品介绍,咨询商务报价或私有化部署事宜

400-066-00210755-86967467

获取产品帮助
联系 FinClip 技术顾问,获取产品资料或加入开发者社群

联系线上
人工客服

或 👉  点击这里,提交咨询工单

填写 FinClip 问卷抽缤纷夏日盲盒
Hi,这里是我们为 FinClip 用户准备的一封调研问卷,期待您的参与,您的反馈和建议,将指引 FinClip 未来前进的方向。