Skip to content

SuperPush Message Push

Status: §1 / §2 / §3 / §5 are official guidelines (Console & Server CA-F261008030542 · Android Firebase adapter SDK-F042 · 2026-10-19); §2.3 iOS (SDK-F043) and §4 SuperCLI (BL-014) remain post-planning and will be promoted to official status upon delivery. This document is the single source of truth for SuperPush; refer to Integration Overview before reading. The placeholders {spid} / {env} / {sdkVersion} are filled by the Console under “Push Settings → Copy Integration Guide” based on the current project, environment, and latest SDK version; manually replace them when reading.

SuperPush enables you to send push notifications to users of your host app and view delivery, failure, and open rates for each device in the console.

  • Channel: Firebase Cloud Messaging (FCM HTTP v1). Both Android and iOS use FCM; iOS’s APNs is hosted by Firebase (APNs key configured in the Firebase Console). The platform does not connect directly to APNs and does not support vendor-specific channels.
  • Credentials: One Firebase service account JSON per project per environment, uploaded to the console with write-only permissions.
  • Device: Once the host app with the integrated push off-line package starts, it automatically registers the device to the current project × environment; you do not need to collect and upload tokens yourself.
  • Targeting: Specify by device, by tag, by user ID, or all devices. Tags and user IDs are set by the app via the SDK.
  • Recording: A record is sent for each delivery, containing per-device delivery status, error codes, and open counts. The open count is derived from the receipt returned when the SDK is clicked (simultaneously reporting the $push_open event).
  • Entry Point: Console, sst_ API (server-side); SuperCLI post-processing. Scheduled push = SuperScheduler invokes the push API according to cron, while SuperPush itself performs no scheduling.
  • Delivery Semantics: At least once. During platform rolling releases or node failures, a very small number of devices (≤200 devices per message) may receive duplicate notifications. Notifications that have already been sent cannot be recalled when canceling a message in transit.
LimitValue
Devices per environment100,000
Single send audience50,000 devices
Send frequency20 times per minute per environment (combined console and API)
Device registration frequency60 times per minute per (project, client IP); 6,000 times per minute per project
Title / Body200 / 1000 characters
Entire message (title + body + data + platform fixed fields)4 KiB (FCM hard limit)
Custom data≤20 keys, key ^[A-Za-z0-9_.-]{1,64}$, value ≤1024 characters
Tags10 per device, each 32 characters
Data retentionDevice-level delivery for 7 days, aggregated reporting for 90 days; unregistered devices are cleared after 30 days.

Not included in the first release: Scheduled and periodic sending (using SuperScheduler), A/B testing, multi-language templates, rich media beyond image URLs, FCM topics, direct APNs connections, and Web Push.

  1. Create a project in the Firebase Console and add your Android / iOS app, then download google-services.json (Android) or GoogleService-Info.plist (iOS).
  2. Generate a service account private key JSON in Firebase “Project Settings → Service Accounts” and provide it to the console administrator for upload (see §5.1); simultaneously ensure that Firebase Cloud Messaging API (V1) is enabled in Google Cloud. The app does not require this JSON.
  3. The app has integrated SuperSDK and completed SuperSDK.init(context, spid, provider) within Application.onCreate. In non-prod environments, call SuperSDK.setAPIEnvironment(env) before or immediately after init (the SDK defers the initial registration to the next main thread tick, so setAPIEnvironment called immediately after init takes effect for the initial registration; switching environments after this point triggers a re-registration).

Dependencies and Plugins:

app/build.gradle.kts
// root build.gradle.kts
plugins { id("com.google.gms.google-services") version "4.4.2" apply false }
plugins { id("com.google.gms.google-services") }
dependencies { implementation("com.supersdk:supersdk-push-firebase:{sdkVersion}") } // Same version as com.supersdk:supersdk

Place google-services.json in app/. The optional adapter includes firebase-messaging, so do not declare a different version separately. The optional adapter depends only on the SDK’s api + base layers and will not bring Firebase into host apps that do not integrate push notifications.

Integration only requires implementing one additional getter in the SuperSDKProvider passed to SuperSDK.init:

private final PushService pushService = new SDKPushService.Builder()
.addProvider(new FirebasePushProvider(applicationContext))
.build();
@Override
public PushService getPushService() {
return pushService; // The default implementation returns null = no push notifications received.
}

The SDK parses this getter once during init and caches it. Subsequently, the device is automatically registered to the current spid × environment upon first token acquisition, token refresh, setAPIEnvironment switch, tag/user ID change, permission result return, cold start, and background-to-foreground transition (notification visibility change). The registration payload includes the fingerprint (env + token + tags + user_id + enabled + locale + version); identical fingerprints are not sent again within 24 hours. Failures do not trigger retries within the process but are retried at the next trigger point. You do not need to manually acquire tokens or report data. Push registration occurs only during main process initialization (sub-processes of multi-process host apps do not register).

Optional to call (the same instance can also be obtained via SuperSDK.getPushService(); calling before init is safe: setListener takes effect immediately, setTags/setUserId is queued and replayed after init):

PushService push = SuperSDK.getPushService(); // Returns null if not connected.
push.requestPermission(activity, result -> { /* result.getData(): GRANTED / DENIED / PROMPT */ }); // Android 13+ notification permission; <13 directly returns the current status
push.getPermissionStatus(); // GRANTED / DENIED / PROMPT (PROMPT = 13+ and system dialog has not been shown yet)
push.setTags(Arrays.asList("vip", "beta")); // ≤10 items, each ≤32 characters; pass null / empty list to clear; throw IllegalArgumentException if out of bounds
push.setUserId("u_12345"); // ≤128 characters; pass null / empty string = clear
push.setListener(new PushListener() {
@Override public boolean onMessage(PushMessage m) { return false; } // Front-end receives: true = you have displayed it yourself; the SDK will no longer trigger system notifications.
@Override public boolean onOpened(PushMessage m) { return false; } // User clicks; true = you take full control, and the SDK will no longer open the URL.
});
PushStatus s = push.getStatus(); // supported / permission / registered / lastError / lastOpened (Native read does not consume)

Default Behavior:

  • Background / Killed: Displayed by the system based on the notification content; Foreground: Displayed by the host app’s custom supersdk_push_default notification channel (title / body / large image). Returning true from onMessage allows the host app to intercept and prevent display. Regardless of whether the notification is displayed, both onMessage and the H5 push.message will be triggered. If the user disables notifications or has not granted permission, getStatus().permission will correctly return denied or prompt. The device remains registered (with enabled=false in the registration payload), and the device list supports filtering by “Notifications Disabled”. However, when the server selects recipients, such devices are excluded and not counted in the target audience.

  • Click: The host app’s main Activity is launched via the optional adapter’s intermediary Activity. If the notification is click.type=open_url, the SDK first sends a receipt to the server for this open event (≤2 seconds), then opens the page via the authoritative url returned by the server through the existing NavigationService.openPage path — if the host app implements NavigationService, it uses the host’s routing; otherwise, it uses the SDK’s default container page. The stack order is main Activity → container page, and the back button returns to the home page. If the host app wants to fully take over, return true from onOpened; if it only wants to change “how to open the page,” implement NavigationService without touching the notification code. When the receipt is unreachable (offline / weak network / server exception), only the main Activity is launched, and the URL is not opened, but onOpened, push.opened, and $push_open execute normally, with the payload containing verified=false (see below).

  • verified field: PushMessage (onOpened parameter · isVerified() / getOpenedAt()), H5 push.opened payload and getStatus().lastOpened (Native PushStatus.getLastOpened() read does not consume; JSB one-time) both include verified. true = url / clickType from server receipt (authoritative); false = fallback path when receipt is unreachable, url is the original value of the notification intent, unverified by the server. If the host app opens url within onOpened, check message.isVerified() first; otherwise, click intents forged by malicious apps on the same device may cause you to open arbitrary pages.

  • Already have your own FirebaseMessagingService: The host build.gradle should first declare the same version implementation("com.google.firebase:firebase-messaging:25.1.3") (the external package carries it as a runtime dependency, not included in the host’s compile classpath). The Service must not declare android:process (the SDK installs only in the main process). Then, use tools:node="remove" in the manifest to remove the external package’s com.supersdk.push.firebase.SuperFirebaseMessagingService, and forward messages within your Service:

    @Override public void onNewToken(String token) { FirebasePushProvider.handleNewToken(token); }
    @Override public void onMessageReceived(RemoteMessage m) { FirebasePushProvider.handleMessage(m); }

    The transit Activity does not require your handling; keep it as is.

  • Added dependency but getPushService() returns null (not wired): The external package’s Service and transit Activity perform a silent no-op — no registration, no routing, no reporting; clicks only forward to launch the host app; Firebase’s native behavior (token retrieval, system display) remains unaffected by the SDK. H5 getStatus() returns { supported: false }, and all other calls return UNSUPPORTED.

Security Boundary: user_id and tags are self-declared by the host app; the server performs no identity verification. User ID-based targeting is not identity authentication; do not use it to deliver sensitive content (e.g., account changes, verification codes). Pushing data will appear as-is on the device; do not include secrets.

Package.swift
.package(url: "https://github.com/supersdks/ios-sdk-push-firebase.git", from: "{sdkVersion}")

Implement getPushService() in SuperSDKProvider to return SDKPushService(providers: [FirebasePushProvider()]), place GoogleService-Info.plist in the App target, and upload the APNs key in the Firebase console. Permission requests use requestPermission, and all other APIs are symmetric with Android. Before delivery, iOS returns NOT_SUPPORTED for all shared JSB SuperSDK.push.* calls (the current SDK already includes this stub, so no “method not found” errors will occur).

const s = await SuperSDK.push.getStatus();
// { supported, permission: 'granted'|'denied'|'prompt', registered, lastError?, lastOpened? }
await SuperSDK.push.requestPermission(); // → { permission }; Android 13+ displays a system dialog; if the user does not interact, the wait time is up to 120 seconds.
await SuperSDK.push.setTags(['vip']); // [] or null = clear; out-of-bounds is determined by Native → INVALID_ARGUMENT
await SuperSDK.push.setUserId('u_12345'); // '' or null = clear
const offMessage = SuperSDK.push.onMessage((m) => { /* Frontend receives: m.messageId / title / body / imageUrl / url / clickType / data */ });
const offOpened = SuperSDK.push.onOpened((m) => { /* User clicks: m.url / m.messageId / m.verified */ });
offMessage(); offOpened(); // The return value is unsubscribe.
  • The semantics of registered are “there exists a previous successful registration with no subsequent failure,” not “the current snapshot is registered.” The state remains true during the transient period after setTags or switching environments until the new registration succeeds.
  • lastError is one of the closed set TOKEN_UNAVAILABLE / NOT_FOUND / INVALID_REQUEST / RATE_LIMITED / NETWORK_ERROR / UNAVAILABLE, and is cleared after successful registration; TOKEN_UNAVAILABLE = Firebase not configured or token unavailable, NOT_FOUND = spid / environment not registered in the console.
  • lastOpened is one-time: { messageId, url?, clickType, openedAt, verified }. It is cleared immediately after being retrieved by any WebView via a single getStatus() call. It serves as a fallback for scenarios where the WebView hasn’t loaded when the user clicks a notification and no one handles the push.opened event. After page load, call getStatus() once to read lastOpened, then use onOpened for subsequent monitoring. Deduplicate by messageId across both methods; do not pollute getStatus() (as this would allow other pages to prematurely consume lastOpened intended for them).
  • push.message / push.opened are delivered only to active WebViews that are subscribed; subscription must be done via SuperSDK.push.onMessage/onOpened. bridge.on('push.message') in a new runtime will not receive these events.
  • In browser mode, getStatus() returns { supported: false }, while other methods reject with NOT_SUPPORTED. When the host app is not connected, the in-app status is also supported: false, and other methods return UNSUPPORTED. If the Native version is too old, it rejects with SDK_TOO_OLD. On iOS, all methods currently return NOT_SUPPORTED (§2.3).
  1. Launch the app, adb logcat -s ss-SuperPush, and you should see register ok device_id=… env=… token=…(last 6 characters) (all push logs share the SuperPush TAG, with SLogger added to the ss- prefix; logs do not contain complete token, user_id, or tags values).
  2. In the console, navigate to “Push” → “Device”, select the corresponding environment, and verify that the device appears with the token suffix matching the logs.
  3. “Send Push”: Select this device to send a push notification. The mobile device receives it (displayed by the external package when in the foreground; displayed by the system when in the background or killed). “Push Records” shows completed, delivered=1.
  4. Record details upon clicking the notification: “Opened” +1 (synchronous receipt at click time, visible within seconds), and open the page specified in the notification.

Common Errors:

  • SENDER_ID_MISMATCH (sender side) = The google-services.json within the app does not belong to the same Firebase project as the service account uploaded to the console.
  • UNREGISTERED (sender side) = token has expired (uninstall, clear data, or token change); the host app automatically re-registers after restart.
  • Device not appearing = getPushService() returns null (check logcat for register lines), or spid / environment is inconsistent with the console (getStatus().lastError == NOT_FOUND).
  • lastError == TOKEN_UNAVAILABLE = google-services.json missing / package name mismatch / google-services plugin not applied, Firebase cannot retrieve token; self-heals on next cold start after correction.
  • Token refresh during environment switching: After switching the device from prod to staging, if FCM refreshes the token, the prod side retains the old token. The next attempt to send to this device in prod will mark it as unregistered. Upon switching back to prod, the SDK automatically re-registers to restore functionality. This is expected behavior, not an integration issue.
  • A notification targeted by user ID reached an unintended recipient = user_id is self-reported by the app side and unverified (§2.2 Security Boundaries). Ensure that setUserId(null) is called on the business side when the same device logs out.

2.6 Public interfaces automatically invoked by the SDK (register / opened)

Section titled “2.6 Public interfaces automatically invoked by the SDK (register / opened)”

The wrapper package invokes on your behalf; this section exists solely to establish contracts for troubleshooting and self-developed clients. Both are POST requests, JSON format, ≤16 KiB, routed via https://api.supersdk.com:

InterfaceFunctionRequest bodySuccess data
/superapi/v2/push/registerRegister/Update the current device (based on the request body; default user_id/tags are treated as clearing).spid (required, ^[a-z0-9]{8}$), env (default prod), device_id (8..64), token (32..4096, [A-Za-z0-9_:-]), platform (android / ios), app_version / sdk_version (1..32), locale?, user_id? (1..128), tags? (≤10 × ≤32), enabled (indicates whether notifications can currently be shown to the user).{device_id, status:"active"}
/superapi/v2/push/openedClick receipt: Mark the delivery record of this message on this device as opened.spid、env?、device_id、message_id(^pm_[0-9a-f]{12}$)Hit: {click_type, url?} (server authoritative value; the SDK uses this to decide whether to open the URL; open_app does not include url). Idempotent duplicate receipt (the open count is counted only once, and the same data is returned). Miss (message does not exist, does not belong to the project/environment/device, or the device has no deliverable records to open) returns HTTP 200 + NOT_FOUND (same envelope as spid/env does not exist), with no side effects; the SDK only launches the app without callbacks or reporting. Per-device delivery details are retained for 7 days; clicks older than 7 days are treated as misses and only launch the app.

Public error codes (HTTP + envelope code):

ScenarioHTTPcodeSDK-side behavior
Field validation failed / Missing required field / Not JSON200INVALID_REQUESTNo automatic retry (implementation or configuration error)
Missing spid.200SPID_REQUIREDNormalize UNAVAILABLE
spid / env missing or invalid syntax; opened did not match delivery record200NOT_FOUNDregister: retry at the next evaluation point; opened: launch the app only, without callbacks or reporting
Device quota exceeded (new device)200PUSH_DEVICE_QUOTA_EXCEEDEDNormalize to UNAVAILABLE; existing device updates remain unaffected.
Rate limiting (60/min per (spid, IP) · 6000/min per spid · also reject when platform rate-limiting storage is unavailable)429TOO_MANY_REQUESTSNormalized to RATE_LIMITED; registration will be replenished within 24 hours.
Push module disabled503PUSH_DISABLEDNormalize UNAVAILABLE

user_id and tags are reported by the client; the platform does not verify identity. Targeting by user ID is merely “what the app claims to be,” not identity authentication.

The business backend calls the push API using an sst_ API Token issued by the console, without going through the app. The permissions equal the issuer’s role within the organization, and sending requires admin. A token is bound to an organization rather than a project, so the request body must include spid.

POST https://console.superplatform.ai/api/console/machine/push/messages
Authorization: Bearer sst_...
X-Super-API-ENV: {env}
Idempotency-Key: <uuid>
Content-Type: application/json
{
"spid": "{spid}",
"title": "Singles’ Day preview: 20% off storewide",
"body": "Starts at midnight on November 1",
"image_url": "https://cdn.example.com/promo/1111-banner.png",
"click": { "type": "open_url", "url": "https://demo.example.com/promo/1111" },
"data": { "campaign": "1111" },
"audience": { "type": "tag", "tags": ["vip"] }
}
  • spid: Target project (required); X-Super-API-ENV: Target environment (required, defaults to prod if not provided).
  • audience.type: device (device_ids[] ≤1000), tag (tags[] ≤10, matches if any tag hits), user (user_ids[] ≤1000, matches based on the device-reported user_id, not identity authentication), all.
  • click.type: open_app or open_url (the SDK container opens the URL). data is a flat string key-value pair; the reserved keys from, notification, message_type, collapse_key, google.*, gcm.*, spid, env, message_id, url, and click_type must not be used.
  • Response: {"code":"SUCCESS","data":{"message_id":"pm_...","audience_estimate":1596}}. The send operation is asynchronous; check progress via GET /api/console/machine/push/messages/{message_id} (using the same Token + X-Super-API-ENV, returning status, six counts, and timestamp) or the console records page.
  • Idempotency Key (Two Sources, One of Which is Required): Idempotency-Key (1..255 bytes, UUID recommended), or X-SuperSDK-Execution-Id automatically injected by SuperScheduler for each execution (multiple retries within the same execution share the same value). Identical key and content submitted within 24 hours return the same record without re-sending; identical key with different content returns 409 PUSH_IDEMPOTENCY_CONFLICT; missing both headers returns 422 INVALID_REQUEST.
  • HTTP Status: This server-side interface rejects business requests with non-2xx status codes (unlike the console/CLI interface where the business code is always 200), allowing the Scheduler or your HTTP client to detect failure without parsing the response body. The response body remains the unified envelope {code, message, data, extra}.
business codeMeaningMachine-side HTTPConsole / cli_ HTTPRetryable
SUCCESSAccepted200200—
PUSH_NOT_CONFIGUREDCredentials have not been uploaded in this environment.422200No
PUSH_CREDENTIAL_INVALIDCredentials have expired (red light in Settings page; re-upload or click “Test Connection”).422200No
PUSH_AUDIENCE_EMPTYAudience is 0 (no match, all notifications disabled, or expired)422200No
PUSH_AUDIENCE_TOO_LARGEAudience > 50,000422200No
PUSH_INVALID_ARGUMENTField-level errors (extra.field indicates the field): title / body / URL / data schema or reserved keys / entire payload > 4 KiB / device_ids not belonging to this environment.422200No
INVALID_REQUESTMissing X-Super-API-ENV / Both idempotency keys missing / Key too long / Invalid JSON422200No
PUSH_IDEMPOTENCY_CONFLICTSame idempotent key, different content409— (Console page has no idempotency key)No
PUSH_RATE_LIMITEDThis environment has a limit of 20 times per minute, and extra.retry_after_secs provides the recovery seconds.429200Yes
NOT_FOUNDspid does not belong to the organization of the Token / message_id does not exist (the two are indistinguishable)404200No
FORBIDDENToken issuer is not admin403403No
(no code)Token invalid / expired / not sst_401401No
PUSH_DISABLEDPlatform push module disabled503503Yes
  • Failure codes in the record (not response codes): FCM native codes are preserved as-is (UNREGISTERED device invalid, QUOTA_EXCEEDED, UNAVAILABLE / INTERNAL still failing after backoff retry, SENDER_ID_MISMATCH credentials mismatch with the App’s Firebase project, THIRD_PARTY_AUTH_ERROR); two platform-specific custom codes: CREDENTIAL_INVALID (entire message terminated due to invalid credentials, details page links to push settings) and PUSH_INVALID_PAYLOAD (FCM rejects at message level with INVALID_ARGUMENT, details page provides field path).
  • Scheduled Push: Create a cron task in SuperScheduler targeting the aforementioned interface. Include sst_ Token (stored via envelope encryption) and X-Super-API-ENV in the Header, and pass spid in the body. You do not need to manually fill in the idempotency key; the Scheduler automatically includes X-SuperSDK-Job and X-SuperSDK-Execution-Id with every execution, ensuring that retries within the same execution do not result in duplicate broadcasts. A failure in the Scheduler execution history indicates the push was rejected (422/409/429/503), where the code in the response body specifies the reason. If the execution history shows 403 or 503 and the response body is not the expected JSON envelope (e.g., it is HTML), the request was blocked by Cloudflare before reaching the platform; contact the platform provider for resolution and do not modify the Job.
  • Delivery Semantics: At least once. The platform may retry a batch (≤200 devices) at most once during rolling releases or node failures. When canceling a message in transit, notifications already sent are not recalled; devices in the log for these notifications are marked as skipped.

Console API on the thin wrapper, SPID is read from super.json, --env is required:

Terminal window
supercli push devices --env prod --tag vip --output json --no-input
supercli push send --env prod --title "Title" --body "Body" --audience tag --tags vip,beta --url https://... --output json --no-input
supercli push records --env prod --limit 20
supercli push show pm_7f3a9c2e41b0 --env prod
supercli push settings --env prod # Display only project_id / client_email / last verified, do not echo the private key.

Credential upload is performed only in the console; the CLI does not provide commands to upload service accounts.

Path: Console → Business Operations → Push. All four pages follow the environment selector in the top bar; when the platform push module is disabled, all four pages uniformly display “Push function not enabled”.

Upload the Firebase service account JSON file; the platform immediately performs a connection validation (exchanging for an access token and sending a validate_only test request to FCM) and stores only the ciphertext. The page displays only the firebase_project_id, client_email, uploader, timestamp, and the latest validation result (success / invalid credentials / FCM API not enabled / network temporarily unreachable). You can “Test Connection” at any time (success restores the invalid state to configured) or “Remove” it. When switching to credentials for another Firebase project or removing them, queued or sending messages in that environment are terminated as CREDENTIAL_INVALID, and the confirmation dialog displays the message count. The “Copy Integration Guide” button on the page copies §2 and §3 along with the current spid, environment, and SDK version, ready to be handed directly to the Agent.

Current registered devices: device_id, platform, App/SDK version, token suffix, user ID, tags, status (active/unregistered), notification enabled, last active; header displays quota usage and counts of “expired” or “notifications disabled”. Filter by platform, tags, user ID, status, or notification toggle. Inline “Send Test Push” directly navigates to the send page and selects the device; admins can remove devices. An empty list displays a three-step integration guide.

Select audience (by device / by tag / by user ID / all), fill in title, body, image, click action, and custom data. The right side displays real-time estimated audience count, excluded counts for “notifications disabled / invalid”, total message byte size, and notification preview. If credentials are not uploaded, the entire page redirects to push settings. After submission, proceed to record details.

Status of each sent message (queued / processing / completed / failed / cancelled) and totals / delivered / failed / invalid token / skipped / opened, total = delivered + failed + invalid + skipped; in-progress records can be cancelled (sent records cannot be recalled). The detail page includes error distribution (meaning and suggestions for each error code) and a per-device delivery table, which supports searching by device_id and filtering by status; per-device details are retained for 7 days. CREDENTIAL_INVALID records link to push settings. members can view all pages but cannot send, cancel, upload, or remove.