Browser fallback
SuperSDK supports running in non-App environments (such as browsers), providing reasonable fallback behavior to allow frontend projects to run and debug in browsers.
initFallback(config)
Section titled “initFallback(config)”Initialize the fallback configuration in a non-end environment. The configuration will first be validated; valid calls from within the app (with appbridge) will be ignored.
SuperSDK.initFallback({ baseUrls: ['https://api.supersdk.com/superapi'], // Server address list (used for reportEvent reporting; business path appended to baseUrl) baseUrl: 'https://api.supersdk.com/superapi', // Supports legacy fields; used when `baseUrls` is not provided; `/superapi` can be omitted. spid: 'ab12cd34', // Replace with the real spid (8 lowercase alphanumeric characters) issued by the console. environment: 'staging', // Optional, default is prod; 1 to 10 lowercase alphanumeric characters appName: 'MyApp', // App Name appIcon: '', // App Icon Base64 (Optional) deviceId: '', // Device ID (optional; auto-generated if not provided)});Behavioral Rules:
configmust be a plain object;spidmust match^[a-z0-9]{8}$;environmentdefaults toprodif omitted, and if explicitly provided, must match^[a-z0-9]{1,10}$.- The legacy
aidfield is incompatible; do not trim or convert case. Invalid input immediately throws an error without modifying any active configurations. - In-app (with appbridge) also executes the above validation first; if valid, the fallback configuration is ignored, and all APIs follow the original in-app logic.
- Can be called multiple times, using merge semantics (only the fields passed in this call are updated; fields not passed retain their previous values).
baseUrlstakes precedence overbaseUrl; if not configured, the default is['https://api.supersdk.com/superapi']; the legacybaseUrlfield is compatible and automatically appends/superapi.- The request will prioritize using the last successful baseUrl; if the HTTP status is not 2xx or a network error occurs, it will switch to the next baseUrl among the remaining candidates in random order.
- When
initFallbackis not called, the environment configuration class API returns default empty values (without rejecting).
deviceId Explanation:
- Automatically generate a UUID and store it in
localStorage(key:supersdk_device_id) if not provided, maintaining consistency across sessions. - Clear method:
localStorage.removeItem('supersdk_device_id') - In privacy mode, localStorage may be restricted, causing deviceId to degrade to in-memory storage (different for each session).
isFallbackMode()
Section titled “isFallbackMode()”Check if the current state is in downgrade mode.
if (SuperSDK.isFallbackMode()) { // Non-end environment and initFallback has been called // Available for conditional rendering (e.g., hiding feature buttons that are not supported).}Return true if the environment is not an end environment (no appbridge) and initFallback has been called.
API downgrade behavior
Section titled “API downgrade behavior”| Category | API | Degradation behavior | Need to call initFallback |
|---|---|---|---|
| Page Navigation | openPage / openExternal / openWithBrowser / openBrowser | window.open(url, '_blank') | No |
closePage | window.close() or history.back() | No | |
| UI Feedback | showToast(msg) | console.log('[SuperSDK Toast]:', msg) | No |
share(content) | console.log('[SuperSDK Share]:', content) | No | |
| Environment Configuration | getEnv() | resolve { os:'web', spid, environment, appName, deviceId, ... } | No (more fields are returned via configuration) |
setAPIEnvironment(env) / getAPIEnvironment() | Switch project environment during web fallback execution; native host controls set reject, get passes through native values. | set is (initFallback must be called first) | |
getAppName() / getAppIcon() | resolve configuration value or "" | No | |
| Settings Series | resolve {} or null | No | |
| Event Tracking | reportEvent(name, params) | fetch POST to {baseUrl}/v2/reportEvent; body includes basic_data.host_spid/env, and header includes X-Aid=<spid> and X-Super-API-ENV. | Yes (requires baseUrl/baseUrls + spid) |
| User Feedback | submitFeedback(params) | fetch POST to {baseUrl}/v2/feedback; body includes spid/env/platform=web, header includes X-Aid=<spid> and X-Super-API-ENV; business rejection (INVALID_REQUEST/NOT_FOUND) does not switch lines. | Yes (requires baseUrl/baseUrls + spid) |
| Event Listener | subscribe / onForeground / onBackground etc. | Normal registration (but will not receive Native push notifications) | No |
| Push | push.getStatus() | resolve { supported: false } | No |
push.requestPermission() / push.setTags() / push.setUserId() | reject Error('NOT_SUPPORTED') (do not throw synchronous exceptions) | No | |
push.onMessage() / push.onOpened() | Normal registration (but will not receive Native push notifications) | No | |
| No Downgrade | callHostMethod / requestShortUrl / downloadWithCache / file operations / ZIP / attribution / payment / nativeBlock, etc. | reject, error message "Not in app environment..." | - |