Skip to content

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.

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:

  • config must be a plain object; spid must match ^[a-z0-9]{8}$; environment defaults to prod if omitted, and if explicitly provided, must match ^[a-z0-9]{1,10}$.
  • The legacy aid field 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).
  • baseUrls takes precedence over baseUrl; if not configured, the default is ['https://api.supersdk.com/superapi']; the legacy baseUrl field 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 initFallback is 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).

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.

CategoryAPIDegradation behaviorNeed to call initFallback
Page NavigationopenPage / openExternal / openWithBrowser / openBrowserwindow.open(url, '_blank')No
closePagewindow.close() or history.back()No
UI FeedbackshowToast(msg)console.log('[SuperSDK Toast]:', msg)No
share(content)console.log('[SuperSDK Share]:', content)No
Environment ConfigurationgetEnv()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 Seriesresolve {} or nullNo
Event TrackingreportEvent(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 FeedbacksubmitFeedback(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 Listenersubscribe / onForeground / onBackground etc.Normal registration (but will not receive Native push notifications)No
Pushpush.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 DowngradecallHostMethod / requestShortUrl / downloadWithCache / file operations / ZIP / attribution / payment / nativeBlock, etc.reject, error message "Not in app environment..."-