Ads
After the Android host app registers the corresponding optional adapter, showBannerAd and showRewardAd can accept adSource: 'GDT' (Tencent GDT) or adSource: 'CSJ' (CSJ), using the ad unit ID corresponding to that platform. Splash ads are controlled by the host app via the Android native AdService.loadSplashAd.
showRewardAd(options)
Section titled “showRewardAd(options)”Display rewarded video ads. Users receive rewards after watching the video in full.
const result = await SuperSDK.showRewardAd({ adUnitId: 'ca-app-pub-xxx/yyy', // Ad Unit ID adSource: 'ADMOB' // Ad source, default ADMOB});console.log(result.rewarded); // true = user received the rewardconsole.log(result.dismissed); // true = Ad is closed| Parameter | Type | Required | Description |
|---|---|---|---|
| options.adUnitId | string | Yes | Ad Unit ID |
| options.adSource | string | No | Ad source, default ‘ADMOB’ |
Return value: { dismissed: boolean, rewarded: boolean }
Error Code:
| code | Description |
|---|---|
| NOT_IMPLEMENTED | Host app did not provide AdService |
| AD_ALREADY_SHOWING | A fullscreen ad is currently being displayed or is loading. |
| NO_ACTIVITY | Activity/ViewController is unavailable or has been destroyed. |
| LOAD_FAILED | Ad loading failed |
| ERROR | Other errors |
showRewardedInterstitialAd(options)
Section titled “showRewardedInterstitialAd(options)”Display rewarded interstitial ads. Before calling this method, the H5 or host app must display the reward content description and provide a clear “Skip/Continue” entry; this method should only be invoked if the user chooses to continue.
// The business logic should first display the reward description/skip UI.const result = await SuperSDK.showRewardedInterstitialAd({ adUnitId: 'ca-app-pub-xxx/yyy', adSource: 'ADMOB'});console.log(result.rewarded);console.log(result.dismissed);| Parameter | Type | Required | Description |
|---|---|---|---|
| options.adUnitId | string | Yes | Rewarded Interstitial Ad Unit ID |
| options.adSource | string | No | Ad source, default ‘ADMOB’ |
Return value: { dismissed: boolean, rewarded: boolean }
Error codes are the same as showRewardAd; when the legacy native bridge does not support this capability, it immediately rejects with NOT_SUPPORTED without waiting for the 120-second timeout.
showInterstitialAd(options)
Section titled “showInterstitialAd(options)”Display interstitial ads. Full-screen display, user can close.
const result = await SuperSDK.showInterstitialAd({ adUnitId: 'ca-app-pub-xxx/yyy', adSource: 'ADMOB'});console.log(result.dismissed); // true = Ad is closedParameters and error codes are the same as showRewardAd.
Return value: { dismissed: boolean, rewarded: false }
showBannerAd(options)
Section titled “showBannerAd(options)”Display a Banner ad. The Banner will continuously display at the top or bottom of the page until hideBannerAd is called to hide it.
const result = await SuperSDK.showBannerAd({ adUnitId: 'ca-app-pub-xxx/yyy', adSource: 'ADMOB', position: 'bottom' // 'top' | 'bottom', default 'bottom'});const adId = result.adId; // Save the adId for subsequent hiding.
// Hide Bannerawait SuperSDK.hideBannerAd(adId);| Parameter | Type | Required | Description |
|---|---|---|---|
| options.adUnitId | string | Yes | Ad Unit ID |
| options.adSource | string | No | Ad source, default ‘ADMOB’ |
| options.position | string | No | Position, ‘top’ or ‘bottom’, default ‘bottom’ |
Return value: { adId: string }
Additional Error Codes:
| code | Description |
|---|---|
| CONTAINER_UNSUPPORTED | WebView parent container does not support overlaying Banner ads. |
hideBannerAd(adId)
Section titled “hideBannerAd(adId)”Hide and destroy the specified Banner ad.
await SuperSDK.hideBannerAd(adId);| Parameter | Type | Required | Description |
|---|---|---|---|
| adId | string | Yes | adId returned by showBannerAd |
attribution
Section titled “attribution”getAttribution(onlyFirst)
Section titled “getAttribution(onlyFirst)”Retrieve attribution data, returning data containing both first attribution and current attribution.
// Obtain complete attribution (first attribution + current attribution network request)const { first, current } = await SuperSDK.getAttribution(false);console.log('First attribution:', first);console.log('Current attribution:', current);
// Retrieve only the first attribution (read from cache, skip network requests, faster speed)const { first } = await SuperSDK.getAttribution(true);Parameter Description:
| Parameter | Type | Description |
|---|---|---|
| onlyFirst | boolean | Does it return only the first attribution? true: returns only the first field; false: returns both the first and current fields. Note: If there is no first attribution cache, a network request will be initiated to attempt retrieval regardless of the parameter value. |
Return Value:
{ first: { // First attribution (read from cache), null if not found. attrFrom: "facebook_ad", // Attribution Source attrCmd: "open_page", // Attribution Command attrParam: "page=home", // Attribution parameters recordId: "attr_xxx" // Attribution Record ID }, current: { // Current attribution (network request) is undefined when onlyFirst=true. matched: true, // Is attribution matched? attrFrom: "google_ad", // Attribution Source attrCmd: "view_product", // Attribution Command attrParam: "...", // Attribution parameters recordId: "..." // Attribution Record ID }}first object:
| Parameter | Type | Description |
|---|---|---|
| attrFrom | string | Attribution source (e.g., facebook_ad, google_ad) |
| attrCmd | string | Attribution command (e.g., open_page) |
| attrParam | string | Attribution parameters |
| recordId | string | Attribution Record ID |
current object:
| Parameter | Type | Description |
|---|---|---|
| matched | boolean | Is attribution matched? |
| attrFrom | string | Attribution Source |
| attrCmd | string | Attribution Command |
| attrParam | string | Attribution parameters |
| recordId | string | Attribution Record ID |
Use Cases:
// Scenario 1: Focus only on first attribution (e.g., tracking user source channels)async function init() { // If there is a cache, return it directly; otherwise, initiate a network request. const { first } = await SuperSDK.getAttribution(true); if (first) { console.log('User source:', first.attrFrom); trackUserSource(first.attrFrom); }}
// Scenario 2: Requires initial attribution and current attribution (e.g., dynamic ad delivery)async function onShareClick() { const { first, current } = await SuperSDK.getAttribution(false); // first: first attribution (for statistics) // current: current attribution (for dynamic content) console.log('First attribution:', first); console.log('Current attribution:', current);}Note:
- First attribution (first) is the attribution that matches for the first time after the user installs the app, and it is persisted.
- When
onlyFirst=true, if there is no first attribution cache, a network request is initiated to attempt retrieval.- When
onlyFirst=false, always initiate a network request to fetchcurrent.- If the current match succeeds and there is no initial attribution, it will be automatically saved as the initial attribution.
Native Block (Native Component Embedding)
Section titled “Native Block (Native Component Embedding)”The Native Block module provides “pseudo-layer rendering” capabilities between H5 and Native View, allowing native views provided by the host app (such as ads, video players, etc.) to be embedded within H5 pages.
nativeBlock.init()
Section titled “nativeBlock.init()”Initialize the Native Block module, scan static <native-block> elements in the page, and register them. It is recommended to call this after DOMContentLoaded.
document.addEventListener('DOMContentLoaded', function() { SuperSDK.nativeBlock.init();});Static declaration method
Section titled “Static declaration method”Declare the <native-block> element directly in HTML:
<native-block block-id="ad-1" block-type="ad-banner" block-config='{"adUnitId":"xxx"}' style="width:320px;height:50px;"></native-block>Attribute Description:
| Attributes | Type | Required | Description |
|---|---|---|---|
| block-id | string | Yes | Unique Identifier |
| block-type | string | Yes | Component Type (Host App defined, e.g., “ad-banner”) |
| block-config | string | No | JSON-formatted configuration passed through to the host app |
nativeBlock.create(options)
Section titled “nativeBlock.create(options)”Dynamically create a Native Block.
const block = await SuperSDK.nativeBlock.create({ blockId: 'video-1', blockType: 'video-player', config: { videoUrl: 'https://example.com/video.mp4' }, container: document.getElementById('video-container'), style: { width: '100%', height: '200px' }});
// Destroy this Blockblock.destroy();Parameter Description:
| Parameter | Type | Required | Description |
|---|---|---|---|
| blockId | string | Yes | Unique Identifier |
| blockType | string | Yes | Component Type (Host App Defined) |
| config | object | No | Configuration passed to the host app |
| container | HTMLElement | No | Which container to insert into, default is document.body |
| style | object | No | CSS Style Object |
Return Value:
| Parameter | Type | Description |
|---|---|---|
| blockId | string | Unique identifier of the block |
| element | HTMLElement | placeholder DOM element |
| destroy | function | Method to destroy the Block |
nativeBlock.updatePositions()
Section titled “nativeBlock.updatePositions()”Manually update the positions of all Blocks. Typically, manual invocation is not required; the SDK automatically listens for scroll and window size changes.
SuperSDK.nativeBlock.updatePositions();nativeBlock.destroy(blockId)
Section titled “nativeBlock.destroy(blockId)”Destroy the specified Native Block.
SuperSDK.nativeBlock.destroy('ad-1');nativeBlock.destroyAll()
Section titled “nativeBlock.destroyAll()”Destroy all Native Blocks.
SuperSDK.nativeBlock.destroyAll();Complete example
Section titled “Complete example”<!DOCTYPE html><html><head> <script src="supersdk.js"></script> <style> .ad-container { margin: 20px 0; } native-block { display: block; } </style></head><body> <h1>Native Block example</h1>
<!-- Static declared ad placement --> <div class="ad-container"> <native-block block-id="banner-1" block-type="ad-banner" block-config='{"adUnitId":"ca-app-pub-xxx"}' style="width:320px;height:50px;"> </native-block> </div>
<p>Page content...</p>
<!-- Dynamically created container --> <div id="dynamic-ad"></div>
<script> // Initialize static Block document.addEventListener('DOMContentLoaded', function() { SuperSDK.nativeBlock.init(); });
// Dynamically create a Block async function createDynamicAd() { try { const block = await SuperSDK.nativeBlock.create({ blockId: 'dynamic-banner', blockType: 'ad-banner', config: { adUnitId: 'ca-app-pub-yyy' }, container: document.getElementById('dynamic-ad'), style: { width: '300px', height: '250px' } }); console.log('Ad created:', block.blockId); } catch (e) { console.error('Could not create ad:', e); } } </script></body></html>Important Notes:
- The content of the Native Block is provided by the host app, and the SDK is only responsible for position synchronization.
- The host app needs to implement the
INativeBlockProviderinterface and register it.blockTypeis defined by the host app and must be agreed upon with the host app to support the specified types.- The page automatically cleans up all Blocks when closed, or you can manually call
destroyAll().
Response code (suenc)
Section titled “Response code (suenc)”suenc is a lightweight response obfuscation protocol uniformly maintained by SuperSDK: when explicitly requested by the client, the server encodes the JSON response body using a custom Base64 table and returns X-Su-Enc: b64t1.
⚠️ It is only used to reduce the effectiveness of generic keyword scanning and rule matching, not for encryption. It does not provide confidentiality, tamper resistance, or replay protection, and cannot prevent an attacker who has obtained the client-side code from restoring the encoding table.
Requests initiated by SuperSDK itself are automatically decoded (e.g., settings / reportEvent / attribution / short links, etc.), so business-side intervention is not required. The following two APIs are intended for fetch requests initiated by the business side.
getSuEncCapabilities()
Section titled “getSuEncCapabilities()”Query the codecs supported by the current runtime to decide whether to send suenc=1. This method does not exist in older SDK versions; therefore, you must perform an existence check first.
const capabilities = SuperSDK.getSuEncCapabilities();// { supported: true, codecs: ['b64t1'] }
const canUseSuEnc = typeof SuperSDK.getSuEncCapabilities === 'function' && capabilities.supported && capabilities.codecs.includes('b64t1');Return value: { supported: boolean, codecs: string[] } (synchronous return, frozen object)
decodeSuEnc(encodedData, codec)
Section titled “decodeSuEnc(encodedData, codec)”Decode the suenc response body and return the raw UTF-8 JSON text. Synchronous pure function, no JSBridge round-trip.
| Parameter | Type | Required | Description |
|---|---|---|---|
| encodedData | string | Yes | Complete encoded response body returned by the server |
| codec | string | Yes | The raw value of the X-Su-Enc header, custom encoding tables are not supported. |
// Only append suenc=1 after confirming support.const url = canUseSuEnc ? `${api}?suenc=1` : api;const response = await fetch(url);
const codec = response.headers.get('X-Su-Enc');if (codec) { const decoded = SuperSDK.decodeSuEnc(await response.text(), codec); return JSON.parse(decoded);}
// 🔴 If the current request includes suenc=1 but receives a response without headers, it must be marked as failed (to prevent plaintext downgrade).// Do not directly pass plaintext responses to the business logic.if (canUseSuEnc) throw new Error('SUENC_DOWNGRADE');return response.json();Error Codes (all are SuperSDKError, error.code can be used to determine):
| Error Codes | Trigger conditions |
|---|---|
UNSUPPORTED_SUENC_CODEC | X-Su-Enc points to an unknown codec on this side; will not attempt other encoding tables. |
SUENC_DECODE_FAILED | Invalid characters, length not a multiple of 4, or invalid padding position or count. |
SUENC_INVALID_UTF8 | Decoded result is not valid UTF-8 |
Important Notes:
codecmust be directly taken from the response header value, do not hard-code it, so that no business code changes are needed whenb64t2is added in the future.- Decoding failures are uniformly treated as request failures; falling back to read plaintext is absolutely prohibited—that is precisely the downgrade the protocol aims to prevent.
- Encoded volume increases by approximately 33%; binary responses (APK / ZIP / images / file streams) are not obfuscated.
- The encoding table never changes after the SDK is released; new tables must use a new codec key.