# 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? 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, | 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 | 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](https://www.superplatform.ai/en/android.md) · [iOS](https://www.superplatform.ai/en/ios.md) · [JSSDK](https://www.superplatform.ai/en/jssdk.md) | | Login, Payment, Ads | Third-party login, in-app purchases, and ad monetization integrated once. | `supersdk.js` API + Native Optional Modules | [Login](https://www.superplatform.ai/en/jssdk/api/login/) · [Payment](https://www.superplatform.ai/en/jssdk/api/pay/) · [Ads](https://www.superplatform.ai/en/jssdk/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](https://www.superplatform.ai/en/jssdk/api/env-config/) · [SuperCLI](https://console.superplatform.ai/supercli.md) §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](https://www.superplatform.ai/en/jssdk/api/host-methods/) · [SuperCLI](https://console.superplatform.ai/supercli.md) §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](https://www.superplatform.ai/en/jssdk.md) "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](https://www.superplatform.ai/en/jssdk/api/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](https://www.superplatform.ai/en/superpush.md) | | Short links | Convert long links or HTML snippets into shareable short links | SDK `requestShortUrl` or `supercli shortlink` | [JSSDK Share](https://www.superplatform.ai/en/jssdk/api/share/) · [SuperCLI](https://console.superplatform.ai/supercli.md) §9.1 | | Channel attribution | Identify the source channel for each user | Configure channels and Webhooks via console (console operation only) | [Ads and Attribution](https://www.superplatform.ai/en/jssdk/ads/) | | SuperSite Static Site | Deploy websites and H5 pages to global acceleration nodes with rollback support | `supercli deploy`、`supercli site` | [SuperCLI](https://console.superplatform.ai/supercli.md) §6 | | SuperRun Container Service | Run backend services from images: environment variables, secrets, logs, rollback, and custom domains | `supercli deploy`、`supercli super-run` | [SuperCLI](https://console.superplatform.ai/supercli.md) §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](https://console.superplatform.ai/supercli.md) §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](https://console.superplatform.ai/supercli.md) §9 | | CDN Bucket | Upload images and other static resources to the CDN | `supercli cdn bucket`、`supercli cdn file` | [SuperCLI](https://console.superplatform.ai/supercli.md) §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](https://console.superplatform.ai/supercli.md) §7 | ## 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](https://www.superplatform.ai/en/superpush.md) | | AI Agent or CI automated operation platform. | SuperCLI + API Token | This page "Agent and CI" → SuperCLI dedicated document §7, §10. | ## Before you start Prepare three things first, which will be used in every subsequent step: 1. **Project and `spid`**: Register and create a project in the [Console](https://console.superplatform.ai) to obtain `spid`. It is the unique identifier for the project, consisting of 8 lowercase letters or digits (the example below uniformly uses `ab12cd34`). Both SDK initialization and SuperCLI's `super.json` require it. 2. **Project Environment**: Each project includes a `prod` environment 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 using `setAPIEnvironment`, while most SuperCLI commands select the environment via the `--env` flag. 3. **Credentials**: Users log in via the browser using `supercli login` on the local machine; AI Agents and CI use `sst_` 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. ## CLI 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. ```bash npm install -g @supersdk/supercli supercli login --environment prod supercli init my-workspace # Interactively prompt for spid to generate 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` 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](https://console.superplatform.ai/supercli.md). ## Web 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 `initFallback` with `spid` and the server address; features like event tracking and feedback operate directly over the network, while native-only capabilities degrade. ```javascript 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 ](https://www.superplatform.ai/en/jssdk.md) (web version )]. ## iOS Integrate via SPM or xcframework, then set the project environment and initialize upon startup. ```swift try SuperSDKManager.shared.setAPIEnvironment("prod") try SuperSDKManager.shared.initialize(spid: "ab12cd34", provider: MySDKProvider()) ``` See the [iOS Integration Guide ](https://www.superplatform.ai/en/ios.md) (web version )] for details. ## 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). ```groovy implementation 'com.supersdk:supersdk:' ``` ```java SuperSDK.setAPIEnvironment("prod"); SuperSDK.init(this, "ab12cd34", new MySDKProvider()); ``` See the [changelog ](https://www.superplatform.ai/en/changelog.md)] 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 ](https://www.superplatform.ai/en/android.md)] (web version ). ## 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 ](https://console.superplatform.ai/supercli.md)] §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 ](https://www.superplatform.ai/en/jssdk/iap-architecture/)] and [Payment API ](https://www.superplatform.ai/en/jssdk/api/pay/)]. - 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](https://www.superplatform.ai/en/jssdk/api/login/). - Event Reporting: Reported directly from the client SDK to the platform; the backend does not need to forward it. See [JSSDK reportEvent](https://www.superplatform.ai/en/jssdk/api/host-methods/); use `supercli analytics` when the backend or scripts need to query data. - Cloud Control Pull: The client SDK retrieves configurations based on `spid` and the environment. See [JSSDK Environment and Configuration](https://www.superplatform.ai/en/jssdk/api/env-config/); use `supercli settings` for 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](https://console.superplatform.ai/supercli.md) §8.1. - Attribution: Channels and return Webhooks are configured in the console. See [Ads and Attribution](https://www.superplatform.ai/en/jssdk/ads/). - 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](https://www.superplatform.ai/en/superpush.md) §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 parameter `super_ab_vids`) when sending requests to the backend. The backend reads the request header first, then the query parameter, and routes logic based on the `vid`; if the value is empty, default logic is applied. Requests from H5 to its own backend are not automatically prefixed with headers; use `SuperSDK.experiment.fetch` or `getRequestHeaders()` / `appendVidsToUrl()` to add them. For cross-origin requests, the backend's `Access-Control-Allow-Headers` must include `X-Super-AB-Vids`. Since request headers can be tampered with, the backend must verify pricing, quotas, or entitlements by calling `assign` with `side: "server"` using the `device_id`. Before ending an experiment, the backend must switch the winning logic back to the default and deploy it. See the [JSSDK](https://www.superplatform.ai/en/jssdk.md) "Server-side experiment" section. ## 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 the `sst_` API Token issued by the console via the `SUPERCLI_TOKEN` environment variable before building and publishing; do not write the Token into command-line arguments. - Add `--output json --no-input` to 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 init` will not prompt for `spid`; a valid `super.json` must 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 --help` when parameters are uncertain; do not guess. ```bash export SUPERCLI_TOKEN=sst_... supercli deploy --project web --env-target prod --build-dir .super/build --output json --no-input ``` For the complete agreement, see [SuperCLI Integration Guide](https://console.superplatform.ai/supercli.md) §7 "Account, Credentials, and Permissions" and §10 "Agent Contract and Exit Codes". ## 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.md) | | | SuperCLI Integration Guide | All commands, `super.json`, build and release, credentials and permissions, Agent conventions, and troubleshooting | [supercli.md](https://console.superplatform.ai/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.md) | | | iOS Integration Guide | Integration, initialization, container, all Service protocols, and complete examples. | [ios.md](https://www.superplatform.ai/en/ios.md) | | | 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.md) | | | SuperPush Message Push | What is Push, Android client integration, server-side APIs, and console usage (delivered), SuperCLI (planned). | [superpush.md](https://www.superplatform.ai/en/superpush.md) | None | | Offline Package Specification | Site-side `super_meta.json` manifest and offline package packaging constraints | [offline-pkg-spec.md](https://www.superplatform.ai/en/offline-pkg-spec.md) | None | | Changelog | Version changes and latest version number | [changelog.md](https://www.superplatform.ai/en/changelog.md) | | | Platform capabilities overview | Capability descriptions aligned with business objectives | None | | A machine-readable list of documents is available at .