Skip to content

Push notifications (SuperSDK.push namespace)

Device push bridging capability · H5 invokes via SuperSDK.push.*. Android requires the host app to integrate the optional module supersdk-push-firebase and implement SuperSDKProvider.getPushService() (integration details see Android integration documentation “Push” section and SUPERPUSH.md); iOS currently has explicit “not supported” stubs (the four methods reject UNSUPPORTED).

The SDK is responsible only for device registration, forwarding foreground messages/clicks to H5, and reporting app opens. Sending and audience targeting are completed in the console’s “Message Push” section. All interfaces provide explicit results—not errors—in all three environments: browser, host app, and iOS (see table below), allowing business code to call them unconditionally.

EnvironmentgetStatus()The other three methods
Android · Host app connectedActual state (supported: true)Normal execution
Android · Host app not connected (getPushService() is null){ supported: false }reject UNSUPPORTED (Native NOT_IMPLEMENTED normalized via registry · retryable: false)
iOS(stub){ supported: false }reject UNSUPPORTED
Pure browser (no window.appbridge){ supported: false }reject NOT_SUPPORTED (do not throw synchronous exceptions)
Native version too old (no push JSB)reject SDK_TOO_OLDreject SDK_TOO_OLD

Get push status snapshot.

const status = await SuperSDK.push.getStatus();
// {
// supported: true,
// permission: 'granted', // 'granted' | 'denied' | 'prompt'
// registered: true, // Last successful registration exists and no errors have occurred since then
// lastError: 'NETWORK_ERROR', // Optional · The reason for the most recent registration failure (cleared after success)
// lastOpened: { // Optional · One-time field, see description below
// messageId: 'pm_0123456789ab',
// url: 'https://example.com/promo',
// clickType: 'open_url', // 'open_app' | 'open_url'
// openedAt: 1760000000000,
// verified: true
// }
// }

Return value: Promise<PushStatus>

FieldTypeDescription
supportedbooleanfalse when other fields are omitted (browser / unconnected / iOS)
permission'granted' | 'denied' | 'prompt'Notification visibility to the user. denied covers both “permission denied” and “system notification toggle off”; prompt = Android 13+ has not been asked yet.
registeredbooleanDerived Value: true if a previous successful registration fingerprint exists and no errors have occurred since. It remains true transiently between setTags and the new successful registration; it flips to false upon any registration failure (including 24h refresh failure).
lastErrorstringClosed set TOKEN_UNAVAILABLE / NOT_FOUND / INVALID_REQUEST / RATE_LIMITED / NETWORK_ERROR / UNAVAILABLE; server codes outside the closed set are normalized to UNAVAILABLE in Native. Omitted after successful registration.
lastOpenedobjectThe most recent unread push click, with fields identical to the push.opened payload; omitted if there are no unread clicks.

🔴 lastOpened is a one-time field: consumed by the first getStatus() call that reads it (any invocation from any WebView, including polling), and returns nothing thereafter. It addresses the scenario where, upon cold-starting the app via a notification click, the page hasn’t loaded yet and no one is handling the push.opened event. In a multi-WebView environment, only one page can read it. A page that has already received the push.opened event may still read the same entry when calling getStatus() again. Therefore, use both push.opened events and lastOpened as fallbacks, deduplicating by messageId, and do not call getStatus() in polling loops (as this would allow other pages to prematurely consume the click intended for them).

Request notification permission. On Android 13+, the system permission dialog is displayed (each device shows the dialog only once; thereafter, the system decides). On Android 12 and below, no dialog is shown, and the actual reachability is returned directly.

const { permission } = await SuperSDK.push.requestPermission();
if (permission !== 'granted') {
// Guide the user to enable notifications in system settings.
}

Return value: Promise<{ permission: 'granted' | 'denied' | 'prompt' }>

Interaction methods, H5-side callback timeout 120000ms (waiting for the user to operate the system dialog). When no foreground Activity is available (e.g., called from the background), reject UNAVAILABLE (retryable: true); retry later in the foreground. Changes in permission results will trigger the SDK to re-register (the console device enabled status updates accordingly).

Set device tags for audience filtering in the console. The SDK automatically re-registers when the value changes; duplicate values do not trigger repeated requests.

await SuperSDK.push.setTags(['vip', 'zh-CN']);
await SuperSDK.push.setTags([]); // Clear (registration body explicitly with tags: [])
await SuperSDK.push.setTags(null); // Same as above
ParameterTypeDescription
tagsstring[] | null≤10 items, each ≤32 characters (counted by Unicode code points), excluding control characters; the SDK performs trim, remove empty, deduplicate, and preserve order. null and [] are equivalent.

Return value: Promise<void>

Boundary rules are determined by the Native single source: out-of-bounds requests are rejected with INVALID_ARGUMENT (err.nativeCode === 'INVALID_PARAM', err.detail contains the reason) and no request is sent, no landing occurs. The JSSDK locally only intercepts type errors such as “not a string array”.

Set the business user ID for user targeting in the console. The SDK automatically re-registers when the value changes; pass null or '' to clear it upon logout.

await SuperSDK.push.setUserId('u_123456');
await SuperSDK.push.setUserId(null); // Logout: Clear (explicitly set user_id: null in the registration object)
ParameterTypeDescription
userIdstring | null≤128 characters (counted by Unicode code points), excluding control characters; null / '' = clear

Return value: Promise<void>

🔴 userId and tags are merely anonymous identifiers for push targeting, not for identity authentication: They are self-reported by H5 without any validation, and the server does not trust device identity based on them. Do not treat them as a login session, and do not include sensitive information in push content that can be viewed solely by relying on userId.

Listen to push notifications received when the host app is in the foreground (via the existing BROADCAST channel, event key push.message; SuperSDK.subscribe('push.message', cb) is equivalent). Notifications in the background or when the app is killed are displayed directly by the system and do not trigger this callback.

const unsubscribe = SuperSDK.push.onMessage((message) => {
// {
// messageId: 'pm_0123456789ab',
// title: 'Title', body: 'Body', imageUrl: 'https://…' | null,
// url: 'https://example.com/promo' | null,
// clickType: 'open_url', // 'open_app' | 'open_url'
// data: { message_id: '…', url: '…', ... } // FCM data original key passthrough
// }
});
unsubscribe(); // Cancel before page destruction

Return value: The function to cancel the listener.

Listen for push click events (event key push.opened). Clicking a system notification or foreground notification triggers SDK validation and acknowledgment, then dispatches this event. The app is launched (if clickType === 'open_url' and the host app does not handle it, the SDK opens the url).

const unsubscribe = SuperSDK.push.onOpened((opened) => {
// {
// messageId: 'pm_0123456789ab',
// url: 'https://example.com/promo', // Optional, exists when clickType=open_url
// clickType: 'open_url',
// openedAt: 1760000000000,
// verified: true
// }
});
FieldDescription
verifiedtrue = url / clickType from server receipt (authoritative value); false = fallback path when server is unreachable at click time (offline / timeout): url is the original notification intent value, not verified by the server. In this case, the SDK only launches the app and does not automatically open url. If the business logic needs to navigate based on url, first check verified.

Return value: The function to cancel the listener.

🔴 Events are delivered only to WebView instances that are alive and subscribed at the time of event occurrence (exhibits BROADCAST semantics; if no listeners exist, the event is dropped directly without caching). When clicking a notification to cold-start the app, the page has not yet loaded; you must actively retrieve the status once after page load using getStatus().lastOpened. Deduplicating by messageId across these two paths covers all scenarios.

Error (In-App · Error, with code / nativeCode / retryable / detail):

err.codeTrigger conditionsretryable
NOT_SUPPORTEDPure browser (no appbridge)-
UNSUPPORTEDHost not wired (Native NOT_IMPLEMENTED) / iOS stub✗
SDK_TOO_OLDNative did not push JSB✗
INVALID_ARGUMENTInvalid parameter type (local) or out of bounds (Native INVALID_PARAM)✗
UNAVAILABLErequestPermission no foreground Activity (Native NO_ACTIVITY)✓
TIMEOUTCallback timeout (requestPermission 120s · others 15s)✓