SDK 快速集成
下载
聚焦模式
字号
集成样例代码
前置条件
环境要求
sdk: '>=3.0.0 <4.0.0'
flutter: '>=3.3.0'
插件依赖
plugin_platform_interface
flutter_plugin_android_lifecycle
集成方式
从 pub.dev 添加核心插件
2.安装依赖关系
从终端 运行 flutter pub get。
从 VS 代码： 单击位于 pubspec.yaml 顶部操作功能区右侧、由下载图标指示的 Get Packages（获取软件包）。
从 Android Studio/IntelliJ：单击 pubspec.yaml 顶部操作功能区中的 Pub get。
初始化配置
1. 控制台创建应用
小程序 SDK 初始化依赖于从小程序控制台获取的应用的加密密钥或配置文件, 如果您还未在控制台创建应用，可以参考下面流程创建。
1.1 登录小程序控制台进入应用管理页面
1.2 创建 superapp
1.3 填写 superapp 信息
必填信息：
Superapp 名称：支持中文、大小写英文字母、数字、空格和部分特殊符号（"+"、"="、","、"."、"@"、"-"、"_"），3-64个字符。
非必填信息：
Superapp 说明：此处可填写 superapp 的简介信息，主要用于团队内部查看。
Superapp icon：支持上传 jpg、png 格式的方形图片、分辨率为128*128，图片大小在 2M 以内，若不上传 logo 图片，则使用系统默认 icon 图片。
Scheme：只能包含小写字母和数字，不超过64个字符。设置 scheme 后，小程序（或小游戏）的二维码信息会包含 scheme，使用手机系统自带的扫码功能，可直接唤起 superapp 并打开小程序（或小游戏）。
1.4 添加应用包名
添加 Package name/Bundle ID 时，需要选择和填写的字段有：
类型：类型选择后不允许修改，非生产类型的包名仅用于 superapp 测试版本使用，每个月有使用设备数量限制（最多500）。
Package name/Bundle ID：只能包含小写字母（a-z）、数字（0-9）、点（.）和连字符（-），不超过 255 个字符。建议采用反向域名表示法，例如 com.example.myapp。
下载地址：只能包含大小写字母（a-z）、数字（0-9）、点（.）、连字符（-）和斜杠（/），不超过 2048 个字符。
2. 获取应用配置完成初始化
2.1 配置方式说明
添加 Package name/Bundle ID 后，superapp 需要从控制台获取 SDK 初始化配置。当前提供两种获取方式，二选一即可，可在配置获取方式区域查看说明：
配置方式 | 适用场景 | 安全性 | SDK 版本要求 | 绑定关系 |
方式一：使用加密密钥（Encryption key） | 新版 SDK，推荐用于生产环境 | 较高（密钥下发由后台控制） | ≥ 2.3.8 | 与 Package name/Bundle ID 1:1 绑定 |
方式二：下载配置文件（Config file） | 旧版 SDK 或离线场景 | 配置文件为明文存储，需要自行保护 | ≥ 2.2.15 | 与应用维度绑定 |
说明：
两种方式只需任选其一进行 SDK 初始化，不需要同时使用。
推荐优先采用方式一：使用加密密钥，安全性更高且与包名一一绑定，便于权限控制与审计。
若所使用的 SDK 版本低于 2.3.8，请使用方式二：下载配置文件。
2.2 方式一：使用加密密钥
2.2.1 生成加密密钥
1. 按照上文所述为应用配置生产和非生产的 Package name/Bundle ID，每个 Package name/Bundle ID 都可生成唯一的加密密钥，SDK 使用该密钥进行初始化，密钥与包名 1:1 绑定，相比明文配置文件具有更高的安全性，推荐用于生产环境。
2. 在对应包名所在行，找到加密密钥字段：
若状态为未生成，单击生成密钥，系统会为该包名生成唯一密钥，生成成功后会展示掩码（如
A7B9***********************6Q8R0）并提示密钥生成成功。每个 Package name/Bundle ID 仅对应一份加密密钥，重复点击不会生成新的密钥。
2.2.2 查看与复制密钥
1. 密钥生成后，在加密密钥字段会展示掩码字符串以及获取密钥。
2. 单击获取密钥，系统会弹出密钥详情弹窗，展示完整密钥内容。
3. 单击弹窗内的复制，将密钥复制到剪贴板，提示复制成功。
4. 将复制到的密钥保存到您的后台服务，由后台下发给客户端，客户端在 SDK 初始化时使用该密钥即可完成接入。
注意：
加密密钥与 Package name/Bundle ID 1:1 绑定，不同包名对应不同密钥，互不通用。
该方式需要 SDK 版本 ≥ 2.3.8，低版本 SDK 请改用「方式二：下载配置文件」。
请勿将密钥硬编码在客户端代码或公共仓库中，建议由您的业务后台保管，并在客户端运行时按需下发。
仅「应用管理员/应用高级开发者」拥有「生成密钥」权限；「应用开发者」可查看与复制已有密钥；其他角色仅可只读查看是否已生成。
如怀疑密钥泄露，请联系应用管理员处理（如重新生成或更换包名），并同步更新业务后台所保管的密钥。
2.2.3 使用加密密钥完成初始化代理配置
创建 tcsas-plugin-settings.json 配置文件，分别在 android 与 ios 信息中添加 appSecret key 用于设置对用密钥内容。
2.3 方式二：使用配置文件
2.3.1 下载配置文件
注意：
默认下载的配置文件的名称为：tcsas-android-configurations.json。
2.3.2 添加配置文件
1. 将配置文件放在 Flutter 项目中的某个位置。
2. 在项目根目录下添加名为 “tcsas-plugin-settings.json” 的文件。
3. 编辑 pubspec.yaml 文件并为上述文件添加 flutter 资源。
在 tcsas-plugin-settings.json 文件中，您可以选择配置 SDK 的设置。
Android：
字段 | 类型 | 说明 |
configAssetsName | string | Android 配置文件路径 |
debug | bool | 启用 SDK 调试和日志 |
iOS:
字段 | 类型 | 说明 |
configAssetsName | string | iOS 配置文件路径 |
debug | bool | 启用 SDK 调试 |
logEnable | bool | 启用 SDK 日志 |
inspectableEnabled | bool | iOS 16.4 后启用可检查功能，可通过 Safari 调试小程序 |
通用：
字段 | 类型 | 说明 |
appName | string | 主机应用程序名称，主要用于小程序中的版权提示 |
appVersion | string | 主机应用程序版本，主要用于小程序中的版权提示 |
assetPathOfPresets | string | 预置离线小程序目录，需要提供 Flutter assets 下的相对路径 |
示例内容：
{"android": {"configAssetsName": "tcsas-android-configurations.json","debug": true},"ios": {"configAssetsName": "tcsas-ios-configurations.json","debug": true,"logEnable": true,"inspectableEnabled": true},"common":{"appName": "tcmpp-flutter","appVersion": "1.0.0","assetPathOfPresets": "res/offline"}}
对于 Android，在 Flutter 项目中打开 android > app > build.gradle，applicationId 可在 android > defaultConfig 部分找到。
对于 iOS，在 Flutter 项目中打开 iOS > Runner.xcodeproj > project.pbxproj，搜索 PRODUCT_BUNDLE_IDENTIFIER。
特定平台
1.针对安卓平台
1. 打开 android > app 目录，编辑 build.gradle 文件。
2. 在 android > defaultConfig 部分，将 minSdkVersion 改为不小于 21。
minSdkVersion 21
3. 在 android > defaultConfig 部分，添加 packagingOptions。
packagingOptions {pickFirst 'lib/arm64-v8a/libc++_shared.so'pickFirst 'lib/armeabi/libc++_shared.so'pickFirst 'lib/armeabi-v7a/libc++_shared.so'pickFirst 'lib/arm64-v8a/libmarsxlog.so'pickFirst 'lib/armeabi/libmarsxlog.so'pickFirst 'lib/armeabi-v7a/libmarsxlog.so'pickFirst 'lib/arm64-v8a/libv8jni.so'}
2.用于 iOS 平台
添加来源
在 iOS 目录中的 Podfile 文件中，添加源代码：
source 'https://github.com/TCMPP-Team/tcmpp-repo.gitsource 'https://github.com/CocoaPods/Specs.git'
执行 pod 安装
cd 到 iOS 目录，执行 pod install：
pod install
打开小程序
使用 API, import 'package:tcmpp_flutter/tcmpp_flutter.dart'
然后创建一个 TcmppFlutter 对象，并用它来调用 API 打开小程序。
Superapp 后台服务域名 ID
当 superapp 配置了多套后台服务域名时，可以通过以下配置指定具体使用哪套域名。
使用示例：
通过 tcsas-plugin-settings.json 文件中 customConfig 项配置 backendDomainId 来实现多域名的指定。
文档反馈