tencent cloud

腾讯云超级应用服务

文档腾讯云超级应用服务代码接入指引iOSiOS SDK 说明SDK 快速集成

SDK 快速集成

Download
聚焦模式
字号
最后更新时间： 2026-08-26 10:30:17
说明：
集成样例代码：您可以 通过 GitHub 获取 Demo 地址。

前置条件

环境要求

iOS >= 9.0
Xcode >= 10.0

组件依赖

tars
MQQComponents
TMFShark
SSZipArchive
PromiseObjC
MJRefresh
SocketRocket
Brotli
CocoaAsyncSocket

集成方式

TCMPPSDK 可通过以下方式进行集成：
CocoaPods 集成
手动集成
SPM 集成

CocoaPods 集成

1. 在您项目中的 Podfile 文件里添加源及小程序依赖模块：
#Pods 仓库
source 'https://github.com/TCMPP-Team/tcmpp-repo.git'

target 'YourTarget' do
     # ――― TCSAS -----―――――――――――――――――――――――――――――――――――――――――――――――――――――--- #
     pod 'TCMPPSDK'
     pod 'TCMPPExtScanCode'
     pod 'TCMPPExtMedia'
     #预置基础库
     pod 'TCSASBaseLib' 
end
其中，YourTarget 为您的项目需要引入 SDK 的 target 的名字。
2. Terminal cd 到 Podfile 文件所在目录，并执行 pod install 进行组件安装。
$ pod install
说明：
如果报 Couldn't determine repo type for URL: 'https://github.com/TCMPP-Team/tcmpp-repo.git':错误，则需要在执行 pod install 前执行 pod repo add specs https://github.com/TCMPP-Team/tcmpp-repo.git。

手动集成

说明：
集成样例代码：您可以 点击下载手动集成 Demo。
1. 添加 SDK
将 SDK 组件的目录添加到您项目的 Xcode Project 中的合适位置，并选择合适的 target。
您可以把组件的目录从 Finder 直接拖动到 Xcode Project 中，以进行快捷添加。

2. 添加依赖的 SDK
把 SDK 依赖的所有组件添加到项目中，依赖的组件列表，请参见前置条件中的 组件依赖。
3. 添加依赖的系统库
把 SDK 依赖的系统库添加到项目中，在 Xcode 中打开 project 设置页，选中相关的 target，单击 General，在“Linked Frameworks and Libraries”中进行添加。
4. 系统库依赖如下：
Foundation.framework
CoreTelephony.framework
CFNetwork.framework
Security.framework
SystemConfiguration.framework
CoreService.framework
CoreFoundation.framework
libz.tbd
libc++.tbd
libc.tbd
libbz2.tbd
libsqlite3.0.tbd
5. project 设置
添加 SDK 后，需要进行相关的 Project 设置。在 Xcode 中打开 Project 设置页，选中相关的 target，进行以下设置：
选择 Build Settings > Linking > Other Linker Flags，增加：-ObjC。
选择 Build Settings > Apple Clang - Custom Compiler Flags > Other C Flags，增加：
  -fshort-wchar
  -D__FIXWCHART__
选择 Build Phases > Copy Bundle Resources,添加 SDK 资源文件：


SPM 工程集成

在 Xcode 中 Select File > Add Packages，搜索窗口中输入 URL：https://github.com/TCMPP-Team/TCMPPSDK.git

选择版本规则（建议使用 Up to Next Major Version），最后点击 Add Package 按钮。
添加 SDK 后，您需要在 Xcode 中进行以下项目设置：
选择 Build Settings > Linking > Other Linker Flags 然后添加 -ObjC。
其它扩展库添加参考：https://github.com/TCMPP-Team/TCMPPSDK

初始化配置

控制台创建应用

小程序 SDK 的初始化依赖于从小程序控制台获取的小程序加密密钥或 SDK 配置文件；如果您还未在控制台创建应用，可以参考以下流程进行创建。
登录控制台后，请单击创建 superapp：
填写 superapp 信息：

必填信息：
Superapp 名称：支持中文、大小写英文字母、数字、空格和部分特殊符号（"+"、"="、","、"."、"@"、"-"、"_"），3-64个字符。
非必填信息：
Superapp 说明：此处可填写 superapp 的简介信息，主要用于团队内部查看。
Superapp icon：支持上传 jpg、png 格式的方形图片、分辨率为128*128，图片大小在 2M 以内，若不上传 logo 图片，则使用系统默认 icon 图片。
Scheme：只能包含小写字母和数字，不超过64个字符。设置 scheme 后，小程序（或小游戏）的二维码信息会包含 scheme，使用手机系统自带的扫码功能，可直接唤起 superapp 并打开小程序（或小游戏）。

添加应用包名：
添加 Bundle ID 时，需要选择和填写的字段有：
类型：类型选择后不允许修改，非生产类型的包名仅用于 superapp 测试版本使用，每个月有使用设备数量限制（最多500）。
Bundle ID：只能包含小写字母（a-z）、数字（0-9）、点（.）和连字符（-），不超过 255 个字符。建议采用反向域名表示法，例如 com.example.myapp。
下载地址：只能包含大小写字母（a-z）、数字（0-9）、点（.）、连字符（-）和斜杠（/），不超过 2048 个字符。



获取应用配置完成初始化

方式一：使用加密密钥

该方式需要 SDK 版本 ≥ 2.3.8 才能使用，如果 SDK 版本低于2.3.8，请使用方法二配置文件进行配置。
生成加密密钥
每个 Package name/Bundle Id 都可生成唯一的加密密钥，SDK 使用该密钥进行初始化，密钥与包名 1:1 绑定，相比明文配置文件具有更高的安全性。

生成后点击获取密钥，会出现一个弹窗，点击弹窗中的复制可以将加密密钥复制到剪贴板。

将复制到的密钥保存到您的后台服务，由后台下发给客户端，客户端在 SDK 初始化时使用该密钥即可完成接入。
注意：
加密密钥与 Package name/Bundle ID 1:1 绑定，不同包名对应不同密钥，互不通用。
该方式需要 SDK 版本 ≥ 2.3.8，低版本 SDK 请改用「方式二：下载配置文件」。
请勿将密钥硬编码在客户端代码或公共仓库中，建议由您的业务后台保管，并在客户端运行时按需下发。
仅「应用管理员/应用高级开发者」拥有「生成密钥」权限；「应用开发者」可查看与复制已有密钥；其他角色仅可只读查看是否已生成。
如怀疑密钥泄露，请联系应用管理员处理（如重新生成或更换包名），并同步更新业务后台所保管的密钥。
引入配置
在 AppDelegate.m 下引入 SDK 头文件：
#import <TCMPPSDK/TCMPPSDK.h>
从后台得到加密密钥来获取配置信息：
// 1. 从您的业务后台异步获取 AppSecret（接口由您自行实现，AppSecret 切勿硬编码在客户端）
[self fetchAppSecretFromBackend:^(NSString *appSecret) {
    // 2. 在回调中拿到 AppSecret 后，完成 SDK 配置
    //    setConfigurationWithAppSecret: 返回 BOOL 表示是否配置成功
    BOOL success = [[TMFMiniAppSDKManager sharedInstance] setConfigurationWithAppSecret:appSecret];
    if (!success) {
        NSLog(@"SDK 初始化失败");
    }
}];


方式二：使用配置文件

下载配置文件：
注意：
默认下载的配置文件的名称为：tcsas-ios-configurations.json

添加配置文件到项目
获取配置文件后，需要将配置文件添加到 superapp 源码工程中：
注意：
iOS 工程的 bundleId 必须与控制台中配置的 bundleId 保持一致，否则会导致 SDK 初始化异常。

引入头文件
把 头文件 引入到 AppDelegate 中。
//TCSAS
#import <TCMPPSDK/TCMPPSDK.h>
配置信息设置
根据配置文件初始化 TMAServerConfig 对象，并使用 TMAServerConfig 初始化小程序引擎。
SDK 可以支持直接进行引擎初始化，提前准备网络链接，并更新基础库信息和配置信息，加速后小程序加载，也可以支持在需要的时候进行初始化。
参考代码：
 //配置使用环境
 NSString *filePath = [[NSBundle mainBundle] pathForResource:@"tcsas-ios-configurations" ofType:@"json"];
 if(filePath) {
   TMAServerConfig *config  = [[TMAServerConfig alloc] initWithFile:filePath];
   //直接初始化
   [[TMFMiniAppSDKManager sharedInstance] setConfiguration:config];
}

增加权限设置

如果您只集成了 SDK 的核心库，即 TCMPPSDK，需要在 info.plist 文件中添加权限申请信息。
其中核心 SDK(TCMPPSDK) 涉及的权限：
权限名称
权限对应的 KEY
权限涉及的 API
相册写入
NSPhotoLibraryAddUsageDescription
saveImageToPhotosAlbum、saveVideoToPhotosAlbum
相机
NSCameraUsageDescription
CameraContext(Camera 组件)
麦克风
NSMicrophoneUsageDescription
CameraContext(Camera 组件)
如果您需要使用扩展 SDK，那么就要在项目的 info.plist 文件中添加对应的权限申请信息。
可以查看 扩展组件 SDK 相关文档。

设置设备支持横屏

SDK 中的 loading 页面，video 组件等都支持横屏效果，但前提是 superapp 工程支持横屏。
请在 Xcode 设置中勾选以下选项：

注意：
如果不勾选横屏，那么 SDK 中涉及到横屏的功能就没有效果。

其它初始化动作

使用者可根据需要，设置开放接口实现实例。如果需要集成扩展模块时，初始化扩展接口准备。
//设置小程序引擎代理类实现
[TMFMiniAppSDKManager sharedInstance].miniAppSdkDelegate = [MIniAppDemoSDKDelegateImpl sharedInstance];
MIniAppDemoSDKDelegateImpl 必须实现 TMFMiniAppSDKDelegate 协议，可以参考 介绍 和 Demo 工程中的 MIniAppDemoSDKDelegateImpl 文件。

打开小程序

可以通过 AppId 直接调用 API 打开小程序。
[[TMFMiniAppSDKManager sharedInstance] startUpMiniAppWithAppID:appId parentVC:self completion:^(NSError * _Nullable error) {
   NSLog(@"open applet error:%@",error);
}];


上一篇: SDK 介绍下一篇: SDK 集成常见问题

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈