Skip to content

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.

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 reward
console.log(result.dismissed); // true = Ad is closed
ParameterTypeRequiredDescription
options.adUnitIdstringYesAd Unit ID
options.adSourcestringNoAd source, default ‘ADMOB’

Return value: { dismissed: boolean, rewarded: boolean }

Error Code:

codeDescription
NOT_IMPLEMENTEDHost app did not provide AdService
AD_ALREADY_SHOWINGA fullscreen ad is currently being displayed or is loading.
NO_ACTIVITYActivity/ViewController is unavailable or has been destroyed.
LOAD_FAILEDAd loading failed
ERROROther errors

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);
ParameterTypeRequiredDescription
options.adUnitIdstringYesRewarded Interstitial Ad Unit ID
options.adSourcestringNoAd 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.

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 closed

Parameters and error codes are the same as showRewardAd.

Return value: { dismissed: boolean, rewarded: false }

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 Banner
await SuperSDK.hideBannerAd(adId);
ParameterTypeRequiredDescription
options.adUnitIdstringYesAd Unit ID
options.adSourcestringNoAd source, default ‘ADMOB’
options.positionstringNoPosition, ‘top’ or ‘bottom’, default ‘bottom’

Return value: { adId: string }

Additional Error Codes:

codeDescription
CONTAINER_UNSUPPORTEDWebView parent container does not support overlaying Banner ads.

Hide and destroy the specified Banner ad.

await SuperSDK.hideBannerAd(adId);
ParameterTypeRequiredDescription
adIdstringYesadId returned by showBannerAd

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:

ParameterTypeDescription
onlyFirstbooleanDoes 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:

ParameterTypeDescription
attrFromstringAttribution source (e.g., facebook_ad, google_ad)
attrCmdstringAttribution command (e.g., open_page)
attrParamstringAttribution parameters
recordIdstringAttribution Record ID

current object:

ParameterTypeDescription
matchedbooleanIs attribution matched?
attrFromstringAttribution Source
attrCmdstringAttribution Command
attrParamstringAttribution parameters
recordIdstringAttribution 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 fetch current.
  • If the current match succeeds and there is no initial attribution, it will be automatically saved as the initial attribution.

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.

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();
});

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:

AttributesTypeRequiredDescription
block-idstringYesUnique Identifier
block-typestringYesComponent Type (Host App defined, e.g., “ad-banner”)
block-configstringNoJSON-formatted configuration passed through to the host app

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 Block
block.destroy();

Parameter Description:

ParameterTypeRequiredDescription
blockIdstringYesUnique Identifier
blockTypestringYesComponent Type (Host App Defined)
configobjectNoConfiguration passed to the host app
containerHTMLElementNoWhich container to insert into, default is document.body
styleobjectNoCSS Style Object

Return Value:

ParameterTypeDescription
blockIdstringUnique identifier of the block
elementHTMLElementplaceholder DOM element
destroyfunctionMethod to destroy the Block

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();

Destroy the specified Native Block.

SuperSDK.nativeBlock.destroy('ad-1');

Destroy all Native Blocks.

SuperSDK.nativeBlock.destroyAll();
<!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:

  1. The content of the Native Block is provided by the host app, and the SDK is only responsible for position synchronization.
  2. The host app needs to implement the INativeBlockProvider interface and register it.
  3. blockType is defined by the host app and must be agreed upon with the host app to support the specified types.
  4. The page automatically cleans up all Blocks when closed, or you can manually call destroyAll().

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.

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)

Decode the suenc response body and return the raw UTF-8 JSON text. Synchronous pure function, no JSBridge round-trip.

ParameterTypeRequiredDescription
encodedDatastringYesComplete encoded response body returned by the server
codecstringYesThe 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 CodesTrigger conditions
UNSUPPORTED_SUENC_CODECX-Su-Enc points to an unknown codec on this side; will not attempt other encoding tables.
SUENC_DECODE_FAILEDInvalid characters, length not a multiple of 4, or invalid padding position or count.
SUENC_INVALID_UTF8Decoded result is not valid UTF-8

Important Notes:

  1. codec must be directly taken from the response header value, do not hard-code it, so that no business code changes are needed when b64t2 is added in the future.
  2. 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.
  3. Encoded volume increases by approximately 33%; binary responses (APK / ZIP / images / file streams) are not obfuscated.
  4. The encoding table never changes after the SDK is released; new tables must use a new codec key.