SuperPlatform integration guide
After reading this page, you should know what SuperPlatform is, what capabilities it offers, which modules your project should use, and where to find detailed documentation. Each section covers the shortest path; details are in the dedicated articles listed in the “Documentation Index” at the end.
What is SuperPlatform?
Section titled “What is SuperPlatform?”SuperPlatform (formerly SuperSDK) is an all-in-one App development and operations platform. Business teams write only business code; platform handles all infrastructure work unrelated to business:
- App Side: The Android/iOS SDK provides an H5 container (WebView + JSBridge + offline package), where H5 calls native capabilities such as login, payment, sharing, ads, and file operations via a single
supersdk.js. - Deployment: Static sites (SuperSite) and container backends (SuperRun) are deployed with a single command, automatically assigning domain names and HTTPS.
- Operations: Cloud control configuration, event analytics, user feedback, message push, short links, channel attribution, scheduled tasks, and database access are all managed uniformly in a single console by “project × environment”.
The platform has three entry points with identical capabilities, each targeting different users:
| Entry Point | What it is | Who uses it |
|---|---|---|
| Console | Web management console, https://console.superplatform.ai | Humans: Create projects, view data, modify configurations. |
| SuperCLI | Command-line tool supercli (npm package @supersdk/supercli) | Humans, AI Agents, CI: Create projects, build, deploy, query, and maintain. |
| SDK | Android / iOS SDK and frontend supersdk.js | Business code running on user devices. |
Each capability is independent; you can use only one module. You can host sites and backends using SuperCLI without integrating the SDK, or integrate the SDK without using hosting.
Platform capabilities
Section titled “Platform capabilities”| Capability | What it solves | How to use it | Details |
|---|---|---|---|
| H5 Container | Instant loading of web pages within the App, with the ability to call native capabilities. | Android / iOS SDK + supersdk.js | Android · iOS · JSSDK |
| Login, Payment, Ads | Third-party login, in-app purchases, and ad monetization integrated once. | supersdk.js API + Native Optional Modules | Login · Payment · Ads |
| Cloud control configuration | Modify copy, switches, and activity rules without releasing a new version; support rollback | Edit via the console or supercli settings; the client reads using the SDK. | JSSDK Environment and Configuration · SuperCLI §8 |
| Event analytics | Embed tracking data to view trends, retention, and custom dashboards | SDK reportEvent reporting; query via console or supercli analytics | JSSDK Host Methods · SuperCLI §9 |
| A/B testing | Group devices to test different strategies and compare results using embedded tracking | Create and adjust traffic in the console under “Business Operations → AB Experiment”; H5 uses SuperSDK.experiment to read the group (managed uniformly by the native SDK within the app); native code uses SExperiment (Android / iOS, starting from 1.0.0.69-SNAPSHOT). | JSSDK “Experiment” section |
| User feedback | Collect feedback within the app and process it centrally via the console | SDK submitFeedback; view in the console | JSSDK Host Methods |
| Message push | Send push notifications to app users and track delivery and open rates per device (SuperPush · Android and console delivered, iOS planned) | Android push external package supersdk-push-firebase + Firebase (iOS in planning); sent via console or sst_ API (supercli push in planning) | SuperPush |
| Short links | Convert long links or HTML snippets into shareable short links | SDK requestShortUrl or supercli shortlink | JSSDK Share · SuperCLI §9.1 |
| Channel attribution | Identify the source channel for each user | Configure channels and Webhooks via console (console operation only) | Ads and Attribution |
| SuperSite Static Site | Deploy websites and H5 pages to global acceleration nodes with rollback support | supercli deploy、supercli site | SuperCLI §6 |
| SuperRun Container Service | Run backend services from images: environment variables, secrets, logs, rollback, and custom domains | supercli deploy、supercli super-run | SuperCLI §6.1 |
| SuperScheduler Scheduled Tasks | Send requests to specified HTTP(S) endpoints on a cron schedule, with a minimum interval of 1 minute | supercli scheduler or the console | SuperCLI §8.1 |
| Database Integration | Register existing PostgreSQL or MySQL databases to the platform for controlled querying and binding to services | supercli db or the console | SuperCLI §9 |
| CDN Bucket | Upload images and other static resources to the CDN | supercli cdn bucket、supercli cdn file | SuperCLI §9.1 |
| Multi-Environment Support | Isolate configurations, data, sites, and services between testing and production environments | Console or supercli env; SDK runtime switching | See the “Before You Start” section below |
| Organizations and Members | Enable multi-user collaboration with role-based permissions for admin and member | Console or supercli org | SuperCLI §7 |
Choose an integration path
Section titled “Choose an integration path”| Your Situation | Which components to use | Read in this order |
|---|---|---|
| You have an existing native app and need to embed H5 pages | Android / iOS SDK + supersdk.js | See the “Android”, “iOS”, and “Frontend” sections on this page for corresponding dedicated articles |
| Build an app from scratch | SuperCLI project template + three-platform SDKs | See the “CLI” section on this page for the SuperCLI dedicated article §1 |
| Only websites or H5, no App. | SuperSite hosting; add supersdk.js browser mode for tracking and feedback. | This page covers “CLI” and “Frontend”. |
| Only host backend services. | SuperRun; add database access and scheduled tasks on demand; no SDK required. | This page “CLI” → SuperCLI dedicated document §6.1. |
| Only call your own interfaces periodically. | SuperScheduler | SuperCLI dedicated document §8.1. |
| Already integrated; want to perform operations and data analysis. | Cloud control configuration, event analysis, and user feedback. | The corresponding row in the capabilities overview. |
| Want to send push notifications to App users. | SuperPush (requires a Firebase project). | SuperPush Special Document |
| AI Agent or CI automated operation platform. | SuperCLI + API Token | This page “Agent and CI” → SuperCLI dedicated document §7, §10. |
Before you start
Section titled “Before you start”Prepare three things first, which will be used in every subsequent step:
- Project and
spid: Register and create a project in the Console to obtainspid. It is the unique identifier for the project, consisting of 8 lowercase letters or digits (the example below uniformly usesab12cd34). Both SDK initialization and SuperCLI’ssuper.jsonrequire it. - Project Environment: Each project includes a
prodenvironment and can create additional test environments (up to 5 per project, with names consisting of 1–10 lowercase letters or digits). Configuration, data, sites, and services are isolated by environment. The SDK selects the environment at runtime usingsetAPIEnvironment, while most SuperCLI commands select the environment via the--envflag. - Credentials: Users log in via the browser using
supercli loginon the local machine; AI Agents and CI usesst_API Tokens issued by the console. The permissions of the credentials match the role of the issuer within the organization.
In supercli login --environment prod, prod selects the production console. Project environments are configured separately. Use prod for normal CLI access.
SuperCLI is the command-line entry point for the operation platform: creating workspaces, generating or registering projects from templates, building, publishing sites and services, and managing configuration, scheduled tasks, databases, short links, and query data. Requires Node.js 18 or higher.
npm install -g @supersdk/superclisupercli login --environment prod
supercli init my-workspace # Interactively prompt for spid to generate super.json.cd my-workspacesupercli add site apps/web --project web --env-target prod --slug acme --env prod
supercli build-all --output-dir .super/buildsupercli deploy --project web --env-target prod --build-dir .super/buildsuper.json is the workspace configuration file, where one configuration corresponds to a single spid. Existing projects register via supercli register without modifying project files. For the complete command, configuration format, and troubleshooting, see SuperCLI Integration Guide.
Introduce supersdk.js in H5 and invoke capabilities using the global object SuperSDK. The same code supports two execution modes:
- Within an App’s H5 container, call capabilities passed to native execution via JSBridge.
- In a standard browser, first call
initFallbackwithspidand the server address; features like event tracking and feedback operate directly over the network, while native-only capabilities degrade.
if (SuperSDK.isInApp()) { const env = await SuperSDK.getEnv();}await SuperSDK.reportEvent('page_view', { page: 'home' });The shortest path and all APIs are documented in JSSDK Documentation (web version https://www.superplatform.ai/en/jssdk/)].
Integrate via SPM or xcframework, then set the project environment and initialize upon startup.
try SuperSDKManager.shared.setAPIEnvironment("prod")try SuperSDKManager.shared.initialize(spid: "ab12cd34", provider: MySDKProvider())See the iOS Integration Guide (web version https://www.superplatform.ai/en/ios/)] for details.
Android
Section titled “Android”Add com.supersdk:supersdk via Maven, then configure the environment and initialize it within Application. The minimum supported version is Android 6.0 (minSdk 23).
implementation 'com.supersdk:supersdk:<VERSION>'SuperSDK.setAPIEnvironment("prod");SuperSDK.init(this, "ab12cd34", new MySDKProvider());See the changelog ] for the latest version number; SNAPSHOT versions require adding an additional snapshot repository. Google Sign-In, Google Play In-App Purchases, AdMob, Tencent GDT, and CSJ ads can all be integrated via optional modules. For details, refer to the Android integration documentation ] (web version https://www.superplatform.ai/en/android/).
Server
Section titled “Server”The platform’s server is operated by SuperPlatform, so business parties do not need to deploy any platform components. The relationship between the business backend and the platform includes the following:
- Hosting: Package your backend as an image and run it using SuperRun, as described in the SuperCLI integration guide ] §6.1. Alternatively, you can continue running it on your own server without affecting the use of other capabilities.
- Payment: After the client completes a purchase, the business backend verifies the transaction and ships the item; the backend is the sole basis for shipping. See IAP Recommended Architecture ] and Payment API ].
- Login: The SDK returns an identity credential issued by a third party, which is verified by the business backend to obtain its own login session. See Login API.
- Event Reporting: Reported directly from the client SDK to the platform; the backend does not need to forward it. See JSSDK reportEvent; use
supercli analyticswhen the backend or scripts need to query data. - Cloud Control Pull: The client SDK retrieves configurations based on
spidand the environment. See JSSDK Environment and Configuration; usesupercli settingsfor backend or scripts to read/write configurations. - Scheduled task: SuperScheduler requests the backend business interface according to the schedule, and the backend verifies the source using the HMAC signature in the request header. See SuperCLI Integration Guide §8.1.
- Attribution: Channels and return Webhooks are configured in the console. See Ads and Attribution.
- Push: The business backend uses the
sst_Token to call the Push API to send notifications to devices, tags, or user IDs. Devices are automatically registered by the client SDK. See SuperPush §3. - Server-side experiment: A/B experiment groups managed by the business backend. The frontend includes the variant IDs exposed on this device in the request header
X-Super-AB-Vids(or query parametersuper_ab_vids) when sending requests to the backend. The backend reads the request header first, then the query parameter, and routes logic based on thevid; if the value is empty, default logic is applied. Requests from H5 to its own backend are not automatically prefixed with headers; useSuperSDK.experiment.fetchorgetRequestHeaders()/appendVidsToUrl()to add them. For cross-origin requests, the backend’sAccess-Control-Allow-Headersmust includeX-Super-AB-Vids. Since request headers can be tampered with, the backend must verify pricing, quotas, or entitlements by callingassignwithside: "server"using thedevice_id. Before ending an experiment, the backend must switch the winning logic back to the default and deploy it. See the JSSDK “Server-side experiment” section.
Agents and CI
Section titled “Agents and CI”AI Agent and CI operate via the SuperCLI platform, following these rules:
- Do not run
supercli login(it requires a browser). Inject thesst_API Token issued by the console via theSUPERCLI_TOKENenvironment variable before building and publishing; do not write the Token into command-line arguments. - Add
--output json --no-inputto each command: standard output contains exactly one line of JSON, process logs go to standard error, and the result is determined by the exit code (0 for success, 2 for business or permission errors, 3 for invalid credentials, 4 for rate limiting, 5 for network or server errors, 6 for usage errors). - In non-interactive mode,
supercli initwill not prompt forspid; a validsuper.jsonmust already exist in the workspace. - Some tasks cannot be handled by Token: database writes (
db execute) are restricted to human execution, and channel attribution management can only be performed via the console. - Run
supercli <command> --helpwhen parameters are uncertain; do not guess.
export SUPERCLI_TOKEN=sst_...supercli deploy --project web --env-target prod --build-dir .super/build --output json --no-inputFor the complete agreement, see SuperCLI Integration Guide §7 “Account, Credentials, and Permissions” and §10 “Agent Contract and Exit Codes”.
Documentation index
Section titled “Documentation index”Addresses ending with .md return plain text Markdown, suitable for direct reading by Agents; the web version contains the same content, organized by topic across pages.
| Documentation | What is Overridden | Plain Text | Web Version |
|---|---|---|---|
| Integration Overview | This Page | guide.md | https://www.superplatform.ai/en/guide/ |
| SuperCLI Integration Guide | All commands, super.json, build and release, credentials and permissions, Agent conventions, and troubleshooting | supercli.md | None |
| Android Integration Guide | Integration, initialization, container and offline package, all Service interfaces, optional modules, and obfuscation configuration. | android.md | https://www.superplatform.ai/en/android/ |
| iOS Integration Guide | Integration, initialization, container, all Service protocols, and complete examples. | ios.md | https://www.superplatform.ai/en/ios/ |
| JSSDK Documentation | Browser fallback, all APIs, ads, and IAP recommended architecture (longest section; when searching for a specific topic, prioritize the corresponding web page). | jssdk.md | https://www.superplatform.ai/en/jssdk/ |
| SuperPush Message Push | What is Push, Android client integration, server-side APIs, and console usage (delivered), SuperCLI (planned). | superpush.md | None |
| Offline Package Specification | Site-side super_meta.json manifest and offline package packaging constraints | offline-pkg-spec.md | None |
| Changelog | Version changes and latest version number | changelog.md | https://www.superplatform.ai/en/changelog/ |
| Platform capabilities overview | Capability descriptions aligned with business objectives | None | https://www.superplatform.ai/en/platform/ |
A machine-readable list of documents is available at https://www.superplatform.ai/en/llms.txt.