跳转到内容

SuperPlatform 接入总览

读完这一页，你应该知道 SuperPlatform 是什么、有哪些能力、自己的项目该用哪几块、细节文档去哪找。每节只写最短路径，细节在文末「文档索引」列出的专文里。

SuperPlatform 是什么

Section titled “SuperPlatform 是什么”

SuperPlatform（原名 SuperSDK）是一站式的 App 开发与运营平台。业务团队只写业务代码，与业务无关的基础工作由平台承接：

  • App 端：Android / iOS SDK 提供 H5 容器（WebView + JSBridge + 离线包），H5 通过一份 supersdk.js 调用登录、支付、分享、广告、文件等原生能力。
  • 上线：静态站点（SuperSite）和容器后端（SuperRun）一条命令发布，自动分配域名和 HTTPS。
  • 运营：云控配置、事件分析、用户反馈、短链、渠道归因、定时任务、数据库接入，统一在一个控制台里按「项目 × 环境」管理。

平台有三个入口，能力相同、面向不同使用者：

入口是什么谁用
控制台网页管理后台，https://console.superplatform.ai人：建项目、看数据、改配置
SuperCLI命令行工具 supercli（npm 包 @supersdk/supercli）人、AI Agent、CI：建工程、构建、发布、查询、运维
SDKAndroid / iOS SDK 与前端 supersdk.js运行在用户设备上的业务代码

各能力相互独立，可以只用其中一块：不集成 SDK 也能用 SuperCLI 托管站点和后端；不用托管也能只集成 SDK。

能力一览

Section titled “能力一览”
能力解决什么怎么用细节
H5 容器App 内网页秒开，并能调用原生能力Android / iOS SDK + supersdk.jsAndroid · iOS · JSSDK
登录、支付、广告第三方登录、应用内购买、广告变现一次接入supersdk.js 的 API + Native 可选模块登录 · 支付 · 广告
云控配置不发版就能改文案、开关、活动规则，可回滚控制台或 supercli settings 编辑；客户端用 SDK 读取JSSDK 环境与配置 · SuperCLI §8
事件分析埋点入库，看趋势、留存和自定义看板SDK reportEvent 上报；控制台或 supercli analytics 查询JSSDK 宿主方法 · SuperCLI §9
用户反馈应用内收集反馈，控制台集中处理SDK submitFeedback；控制台查看JSSDK 宿主方法
短链把长链接或一段 HTML 变成可分享的短链SDK requestShortUrl 或 supercli shortlinkJSSDK 分享 · SuperCLI §9.1
渠道归因知道用户从哪个渠道来控制台配置渠道与 Webhook（仅控制台可操作）广告与归因
SuperSite 静态站点网站、H5 发布到全球加速节点，带回滚supercli deploy、supercli siteSuperCLI §6
SuperRun 容器服务有镜像就能跑后端：环境变量、密钥、日志、回滚、自定义域名supercli deploy、supercli super-runSuperCLI §6.1
SuperScheduler 定时任务按 cron 向指定 HTTP(S) 地址发请求，最短 1 分钟supercli scheduler 或控制台SuperCLI §8.1
数据库接入把已有的 PostgreSQL / MySQL 登记到平台，受控查询并绑定给服务supercli db 或控制台SuperCLI §9
CDN 上传把图片等静态资源传到 CDNsupercli cdnSuperCLI §9.1
多环境测试与线上的配置、数据、站点、服务相互隔离控制台或 supercli env；SDK 运行时切换见下文「开始前」
组织与成员多人协作，按 admin / member 分权控制台或 supercli orgSuperCLI §7

按场景选路径

Section titled “按场景选路径”
你的情况用哪几块按这个顺序读
已有原生 App，要内嵌 H5 页面Android / iOS SDK + supersdk.js本页「Android」「iOS」「前端」→ 对应专文
从零做一个 AppSuperCLI 工程模板 + 三端 SDK本页「CLI」→ SuperCLI 专文 §1
只有网站或 H5，没有 AppSuperSite 托管；需要埋点、反馈时加 supersdk.js 的浏览器模式本页「CLI」「前端」
只要托管后端服务SuperRun，按需加数据库接入和定时任务；不需要任何 SDK本页「CLI」→ SuperCLI 专文 §6.1
只要定时调用自己的接口SuperSchedulerSuperCLI 专文 §8.1
已经接入，想做运营和数据分析云控配置、事件分析、用户反馈能力一览里对应行
AI Agent 或 CI 自动操作平台SuperCLI + API Token本页「Agent 与 CI」→ SuperCLI 专文 §7、§10

开始前

Section titled “开始前”

三样东西先准备好，后面每一步都会用到：

  1. 项目与 spid：在控制台注册并创建项目，得到 spid。它是项目的唯一标识，8 位小写字母或数字（下文示例统一用 ab12cd34）。SDK 初始化和 SuperCLI 的 super.json 都要用它。
  2. 项目环境：每个项目自带 prod 环境，可以再建测试环境（一个项目最多 5 个，名字为 1–10 位小写字母或数字）。配置、数据、站点、服务都按环境隔离。SDK 在运行时用 setAPIEnvironment 选环境，SuperCLI 的多数命令用 --env 选环境。
  3. 凭据：人在本机用 supercli login 浏览器登录；AI Agent 和 CI 用控制台签发的 sst_ API Token。凭据的权限等于签发者在组织内的角色。

supercli login --environment prod 里的 prod 指平台自身的线上控制台，和上面的「项目环境」不是一回事；正常使用一律填 prod。

CLI

Section titled “CLI”

SuperCLI 是操作平台的命令行入口：创建工作空间、从模板生成或登记工程、构建、发布站点和服务，以及管理配置、定时任务、数据库、短链和查询数据。需要 Node.js 18 及以上。

Terminal window
npm install -g @supersdk/supercli
supercli login --environment prod


supercli init my-workspace            # 交互式询问 spid，生成 super.json
cd my-workspace
supercli add site apps/web --project web --env-target prod --slug acme --env prod


supercli build-all --output-dir .super/build
supercli deploy --project web --env-target prod --build-dir .super/build

super.json 是工作空间配置，一份配置对应一个 spid。已有工程用 supercli register 登记，不会改动工程文件。完整命令、配置格式和故障处置见 SuperCLI 接入说明。

前端

Section titled “前端”

H5 引入 supersdk.js，用全局对象 SuperSDK 调用能力。同一份代码两种运行方式：

  • 在 App 的 H5 容器里，调用经 JSBridge 交给原生执行。
  • 在普通浏览器里，先调用 initFallback 传入 spid 和服务端地址，埋点、反馈等能力直接走网络，原生独有的能力会降级。
if (SuperSDK.isInApp()) {
  const env = await SuperSDK.getEnv();
}
await SuperSDK.reportEvent('page_view', { page: 'home' });

最短路径和全部 API 见 JSSDK 文档（网页版 https://www.superplatform.ai/jssdk/）。

iOS

Section titled “iOS”

通过 SPM 或 xcframework 集成，启动时设置项目环境并初始化。

try SuperSDKManager.shared.setAPIEnvironment("prod")
try SuperSDKManager.shared.initialize(spid: "ab12cd34", provider: MySDKProvider())

详见 iOS 接入文档（网页版 https://www.superplatform.ai/ios/）。

Android

Section titled “Android”

Maven 引入 com.supersdk:supersdk，在 Application 里设置环境并初始化。最低支持 Android 6.0（minSdk 23）。

implementation 'com.supersdk:supersdk:<版本号>'
SuperSDK.setAPIEnvironment("prod");
SuperSDK.init(this, "ab12cd34", new MySDKProvider());

最新版本号见更新日志；SNAPSHOT 版本需要额外添加快照仓库。Google 登录、Google Play 内购、AdMob 广告是按需引入的可选模块。详见 Android 接入文档（网页版 https://www.superplatform.ai/android/）。

服务端

Section titled “服务端”

平台的服务端由 SuperPlatform 运营，业务方不需要部署任何平台组件。业务后端与平台的关系有这几种：

  • 托管：后端打成镜像后用 SuperRun 运行，见 SuperCLI 接入说明 §6.1。也可以继续跑在自己的服务器上，不影响使用其他能力。
  • 支付：客户端完成购买后，由业务后端校验并发货，后端是发货的唯一依据。见 IAP 推荐架构 与 支付 API。
  • 登录：SDK 返回第三方签发的身份凭证，由业务后端校验后换取自己的登录态。见 登录 API。
  • 事件上报：由客户端 SDK 直接上报到平台，后端不需要转发。见 JSSDK reportEvent；后端或脚本要查数据时用 supercli analytics。
  • 云控拉取：客户端 SDK 按 spid 和环境拉取配置。见 JSSDK 环境与配置；后端或脚本要读写配置时用 supercli settings。
  • 定时任务：SuperScheduler 按计划请求业务后端的接口，后端用请求头里的 HMAC 签名校验来源。见 SuperCLI 接入说明 §8.1。
  • 归因：渠道和回传 Webhook 在控制台配置。见 广告与归因。

Agent 与 CI

Section titled “Agent 与 CI”

AI Agent 和 CI 通过 SuperCLI 操作平台，规则如下：

  • 不要运行 supercli login（它需要浏览器）。用控制台签发的 sst_ API Token，经环境变量 SUPERCLI_TOKEN 注入后再做构建和发布；不要把 Token 写进命令行参数。
  • 每条命令加 --output json --no-input：标准输出恰好一行 JSON，过程日志走标准错误，按退出码判断结果（0 成功，2 业务或权限，3 凭据失效，4 限流，5 网络或服务端错误，6 用法错误）。
  • 非交互模式下 supercli init 不会询问 spid，工作空间里要先有一份有效的 super.json。
  • 有些事 Token 做不到：数据库写入（db execute）只允许真人执行，渠道归因管理只能在控制台操作。
  • 不确定参数时运行 supercli <command> --help，不要猜。
Terminal window
export SUPERCLI_TOKEN=sst_...
supercli deploy --project web --env-target prod --build-dir .super/build --output json --no-input

完整约定见 SuperCLI 接入说明 §7「账号、凭据与权限」和 §10「Agent Contract 与退出码」。

文档索引

Section titled “文档索引”

带 .md 的地址返回纯文本 Markdown，适合 Agent 直接读取；网页版内容相同，按主题拆了页。

文档覆盖什么纯文本网页版
接入总览本页guide.mdhttps://www.superplatform.ai/guide/
SuperCLI 接入说明全部命令、super.json、构建与发布、凭据与权限、Agent 约定、故障处置supercli.md无
Android 接入文档集成、初始化、容器与离线包、各 Service 接口、可选模块、混淆配置android.mdhttps://www.superplatform.ai/android/
iOS 接入文档集成、初始化、容器、各 Service 协议、完整示例ios.mdhttps://www.superplatform.ai/ios/
JSSDK 文档浏览器降级、全部 API、广告、IAP 推荐架构（篇幅最长，只查某个主题时优先读网页版对应分页）jssdk.mdhttps://www.superplatform.ai/jssdk/
离线包规范站点侧 super_meta.json 清单与离线包打包约束offline-pkg-spec.md无
更新日志各版本变更和最新版本号changelog.mdhttps://www.superplatform.ai/changelog/
平台能力介绍面向业务目标的能力说明无https://www.superplatform.ai/platform/

机器可读的文档清单在 https://www.superplatform.ai/llms.txt。