跳转到内容

SuperPush 消息推送

状态:§1 / §2 / §3 / §5 为正式口径(控制台与服务端 CA-F261008030542 · Android 外挂包 SDK-F042 · 2026-10-19);§2.3 iOS(SDK-F043)与 §4 SuperCLI(BL-014)仍是后置规划,交付后转正。本文是 SuperPush 的单一信源;读本文前先看接入总览。文中 {spid} / {env} / {sdkVersion} 是占位符:控制台「推送设置 → 复制接入指南」会按当前项目 × 环境与最新 SDK 版本填好,手工阅读时自行替换。

SuperPush 让你给自己 App 的用户发推送通知,并在控制台看到每台设备的送达、失败与打开情况。

  • 通道:Firebase Cloud Messaging(FCM HTTP v1)。Android 与 iOS 都经 FCM,iOS 的 APNs 由 Firebase 托管(在 Firebase 控制台配 APNs key)。平台不做 APNs 直连,也不做厂商通道。
  • 凭据:每个项目 × 环境一份 Firebase 服务账号 JSON,在控制台上传,只写不读。
  • 设备:集成了推送外挂包的 App 启动后自动把设备登记到当前项目 × 环境;不需要你自己收集和上传 token。
  • 受众:指定设备、按标签、按用户 ID、全部设备。标签与用户 ID 由 App 端通过 SDK 设置。
  • 记录:每次发送一条记录,含逐设备投递状态、错误码与打开数。打开数来自 SDK 点击时的回执(同时上报 $push_open 事件)。
  • 入口:控制台、sst_ API(服务端);SuperCLI 后置。定时推送 = SuperScheduler 按 cron 调用推送 API,SuperPush 自身不做调度。
  • 投递语义:至少一次。平台滚动发布或节点故障期间,极少数设备(单条消息 ≤200 台)可能收到重复通知;取消一条正在发送的消息时已发出的通知不召回。
限制值
每环境设备数100,000
单次发送受众50,000 台
发送频率每环境 20 次 / 分钟(控制台与 API 合计)
设备登记频率每 (项目, 客户端 IP) 60 次 / 分钟;每项目 6,000 次 / 分钟
标题 / 正文200 / 1000 字符
整条消息(标题 + 正文 + 数据 + 平台固定字段)4 KiB(FCM 硬上限)
自定义数据≤20 个键,键 ^[A-Za-z0-9_.-]{1,64}$,值 ≤1024 字符
标签每设备 10 个,每个 32 字符
记录保留逐设备投递 7 天,发送汇总 90 天;失效(unregistered)设备 30 天后清除

首版不做:定时与周期发送(用 SuperScheduler)、A/B、多语言模板、图片 URL 之外的富媒体、FCM topic、APNs 直连、Web Push。

  1. 在 Firebase 控制台 建项目并添加你的 Android / iOS 应用,下载 google-services.json(Android)或 GoogleService-Info.plist(iOS)。
  2. 在 Firebase「项目设置 → 服务账号」生成一个服务账号私钥 JSON,交给控制台管理员上传(见 §5.1);同时确认 Google Cloud 里已启用 Firebase Cloud Messaging API (V1)。App 端不需要这份 JSON。
  3. App 已集成 SuperSDK,并在 Application.onCreate 里完成 SuperSDK.init(context, spid, provider);非 prod 环境在 init 前或紧随 init 调用 SuperSDK.setAPIEnvironment(env)(SDK 把首次登记推迟到下一个主线程 tick,所以紧随 init 的 setAPIEnvironment 对首次登记生效;晚于此再切环境会触发一次重新登记)。

依赖与插件:

app/build.gradle.kts
// 根 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}") } // 与 com.supersdk:supersdk 同版本

把 google-services.json 放到 app/。外挂包自带 firebase-messaging,不要再单独声明不同版本。外挂包只依赖 SDK 的 api + base 两层,不会把 Firebase 带进不接推送的宿主。

接线只需在传给 SuperSDK.init 的 SuperSDKProvider 里多实现一个 getter:

private final PushService pushService = new SDKPushService.Builder()
.addProvider(new FirebasePushProvider(applicationContext))
.build();
@Override
public PushService getPushService() {
return pushService; // 默认实现返回 null = 不接推送
}

SDK 在 init 时解析一次这个 getter 并缓存;之后在首次取得 token、token 刷新、setAPIEnvironment 切换、标签 / 用户 ID 变化、权限结果返回、冷启动与回前台(通知可见性变化)时自动把设备登记到当前 spid × 环境。登记体带指纹(env + token + tags + user_id + enabled + locale + 版本),相同指纹 24 小时内不重复发送;失败不在进程内重试,到下一个触发点再试。你不需要手动获取 token 或上报。推送只在主进程初始化(多进程宿主的子进程不登记)。

可选调用(全部也可通过 SuperSDK.getPushService() 取到同一实例;init 前调用是安全的:setListener 立即生效,setTags/setUserId 排队到 init 后回放):

PushService push = SuperSDK.getPushService(); // 未接线返回 null
push.requestPermission(activity, result -> { /* result.getData(): GRANTED / DENIED / PROMPT */ }); // Android 13+ 通知权限;<13 直接回当前状态
push.getPermissionStatus(); // GRANTED / DENIED / PROMPT(PROMPT = 13+ 且还没弹过系统框)
push.setTags(Arrays.asList("vip", "beta")); // ≤10 个,每个 ≤32 个字符;传 null / 空列表 = 清除;越界抛 IllegalArgumentException
push.setUserId("u_12345"); // ≤128 个字符;传 null / 空串 = 清除
push.setListener(new PushListener() {
@Override public boolean onMessage(PushMessage m) { return false; } // 前台收到;true = 你已自行展示,SDK 不再弹系统通知
@Override public boolean onOpened(PushMessage m) { return false; } // 用户点开;true = 你整体接管,SDK 不再打开 URL
});
PushStatus s = push.getStatus(); // supported / permission / registered / lastError / lastOpened(Native 读不消费)

默认行为:

  • 后台 / 被杀:由系统按通知内容展示;前台:由外挂包自建 supersdk_push_default 通知渠道展示(标题 / 正文 / 大图),onMessage 返回 true 可接管不展示。无论是否展示,onMessage 与 H5 push.message 都会回调;用户关掉通知或未授权时 getStatus().permission 如实为 denied / prompt,设备仍登记(登记体 enabled=false,设备页可筛「通知已关闭」),但发送时会被排除、不计入受众。

  • 点击:经外挂包的中转 Activity 拉起 App 主 Activity;若推送是 click.type=open_url,SDK 先向服务端回执这次打开(≤2 秒),再按服务端返回的权威 url 经既有 NavigationService.openPage 路径打开 —— 宿主实现了 NavigationService 就走宿主路由,否则用 SDK 默认容器页。栈序 主 Activity → 容器页,返回键回首页。宿主要整体接管就在 onOpened 返回 true;只想换「怎么开页面」就实现 NavigationService,不用碰推送代码。回执不可达(离线 / 弱网 / 服务端异常)时只拉起主 Activity、不打开 URL,但 onOpened、push.opened、$push_open 照常执行,载荷带 verified=false(见下)。

  • verified 字段:PushMessage(onOpened 参数 · isVerified() / getOpenedAt())、H5 push.opened 载荷与 getStatus().lastOpened(Native PushStatus.getLastOpened() 读取不消费;JSB 一次性)都带 verified。true = url / clickType 来自服务端回执(权威);false = 回执不可达的降级路径,url 是通知 intent 的原值、未经服务端核验。宿主若在 onOpened 里自行打开 url,请先检查 message.isVerified(),否则同机恶意 App 伪造的点击 intent 可能让你打开任意页面。

  • 已有自己的 FirebaseMessagingService:宿主 build.gradle 先自行声明同版本 implementation("com.google.firebase:firebase-messaging:25.1.3")(外挂包以 runtime 依赖携带它,不进宿主编译 classpath),Service 不得声明 android:process(SDK 只在主进程 install);再在 manifest 用 tools:node="remove" 去掉外挂包的 com.supersdk.push.firebase.SuperFirebaseMessagingService,并在你的 Service 里转发:

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

    中转 Activity 不需要你处理,保留即可。

  • 加了依赖但 getPushService() 返回 null(未接线):外挂包的 Service 与中转 Activity 静默 no-op —— 不登记、不路由、不上报,点击只透传拉起主 Activity;Firebase 自身行为(取 token、系统展示)不受 SDK 干预。H5 getStatus() 返回 { supported: false },其余调用回 UNSUPPORTED。

安全边界:user_id 与 tags 由 App 端自述,服务端不做身份校验;按用户 ID 定向不是身份认证,不要用它投递敏感内容(账户变动、验证码等)。推送 data 会原样出现在设备上,不要放密钥。

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

在 SuperSDKProvider 里实现 getPushService() 返回 SDKPushService(providers: [FirebasePushProvider()]),GoogleService-Info.plist 放进 App target,并在 Firebase 控制台上传 APNs key。权限申请走 requestPermission,其余 API 与 Android 对称。交付前,iOS 对共享 JSB SuperSDK.push.* 一律返回 NOT_SUPPORTED(当前 SDK 已内置该 stub,不会报「方法不存在」)。

const s = await SuperSDK.push.getStatus();
// { supported, permission: 'granted'|'denied'|'prompt', registered, lastError?, lastOpened? }
await SuperSDK.push.requestPermission(); // → { permission };Android 13+ 弹系统框,用户不操作最多等 120 秒
await SuperSDK.push.setTags(['vip']); // [] 或 null = 清除;越界由 Native 判定 → INVALID_ARGUMENT
await SuperSDK.push.setUserId('u_12345'); // '' 或 null = 清除
const offMessage = SuperSDK.push.onMessage((m) => { /* 前台收到:m.messageId / title / body / imageUrl / url / clickType / data */ });
const offOpened = SuperSDK.push.onOpened((m) => { /* 用户点开:m.url / m.messageId / m.verified */ });
offMessage(); offOpened(); // 返回值即 unsubscribe
  • registered 的语义是「存在上一次成功登记且其后没有失败」,不是「当前快照已登记」:setTags / 切环境后到新登记成功前的瞬态仍为 true。
  • lastError 是闭集 TOKEN_UNAVAILABLE / NOT_FOUND / INVALID_REQUEST / RATE_LIMITED / NETWORK_ERROR / UNAVAILABLE 之一,登记成功后清空;TOKEN_UNAVAILABLE = Firebase 未配置或取不到 token,NOT_FOUND = spid / 环境未在控制台注册。
  • lastOpened 是一次性的:{ messageId, url?, clickType, openedAt, verified },任一 WebView 任一次 getStatus() 取走后即清空。它是给「用户点开通知时 WebView 还没加载、push.opened 事件没人接」的兜底 —— 页面加载后先调一次 getStatus() 读 lastOpened,之后用 onOpened 监听;两者按 messageId 去重,不要轮询 getStatus()(会把别的页面该拿到的 lastOpened 抢先消费掉)。
  • push.message / push.opened 只投递给已订阅的存活 WebView;只能经 SuperSDK.push.onMessage/onOpened 订阅,新运行时 bridge.on('push.message') 不投递。
  • 浏览器模式下 getStatus() 返回 { supported: false },其余方法 reject NOT_SUPPORTED;宿主未接线时端内同样 supported: false,其余回 UNSUPPORTED;Native 版本太老时 reject SDK_TOO_OLD。iOS 当前一律 NOT_SUPPORTED(§2.3)。
  1. 启动 App,adb logcat -s ss-SuperPush,应看到 register ok device_id=… env=… token=…(末 6 位)(所有推送日志共用 SuperPush TAG,SLogger 加 ss- 前缀;日志不含完整 token、user_id 与 tags 值)。
  2. 控制台「推送 → 设备」切到对应环境,出现该设备,token 尾号与日志一致。
  3. 「发送推送」选中该设备发一条:手机收到(前台由外挂包展示、后台 / 被杀由系统展示),「推送记录」显示 completed、delivered=1。
  4. 点击通知后记录详情「已打开」+1(点击时同步回执,数秒内可见),并打开通知里指定的页面。

常见错误:

  • SENDER_ID_MISMATCH(发送侧)= App 内的 google-services.json 与控制台上传的服务账号不是同一个 Firebase 项目。
  • UNREGISTERED(发送侧)= token 已失效(卸载、清数据、换 token),App 重启后自动重新登记。
  • 设备不出现 = getPushService() 返回了 null(看 logcat 有没有 register 行),或 spid / 环境与控制台不一致(getStatus().lastError == NOT_FOUND)。
  • lastError == TOKEN_UNAVAILABLE = google-services.json 缺失 / 包名不匹配 / google-services 插件未应用,Firebase 取不到 token;补齐后下次冷启动自愈。
  • 切环境期间 token 刷新:设备从 prod 切到 staging 后,若 FCM 恰好刷新了 token,prod 侧保留的仍是旧 token,下次向 prod 该设备发送会把它标为 unregistered;切回 prod 后 SDK 自动重新登记恢复。这是预期现象,不是接入问题。
  • 按用户 ID 定向发出去但「不该收到的人收到了」= user_id 由 App 端自述、未经验证(§2.2 安全边界),请在业务侧保证同一设备登出时调用 setUserId(null)。

2.6 SDK 自动调用的公开接口(register / opened)

Section titled “2.6 SDK 自动调用的公开接口(register / opened)”

外挂包替你调用,这里只为排查与自研客户端留契约。两条都是 POST、JSON、≤16 KiB、经 https://api.supersdk.com:

接口作用请求体成功 data
/superapi/v2/push/register登记 / 更新当前设备(以本次请求体为准,缺省的 user_id / tags 视为清除)spid(必填 ^[a-z0-9]{8}$)、env(缺省 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(通知当前是否对用户可见){device_id, status:"active"}
/superapi/v2/push/opened点击回执:把这条消息在该设备的投递行记为已打开spid、env?、device_id、message_id(^pm_[0-9a-f]{12}$)命中:{click_type, url?}(服务端权威值,SDK 据此决定是否打开 URL;open_app 不带 url);重复回执幂等(打开数只计一次,仍回同样的 data)。未命中(消息不存在、不属于该项目 / 环境 / 设备,或该设备没有可打开的投递记录)回 HTTP 200 + NOT_FOUND(与 spid / env 不存在同一信封)、无副作用,SDK 只拉起 App、不回调、不上报。逐设备投递明细保留 7 天,超过 7 天的点击按未命中处理,只拉起 App

公开面错误码(HTTP + 信封 code):

情形HTTPcodeSDK 侧表现
字段校验失败 / 缺必填 / 非 JSON200INVALID_REQUEST不自动重试(实现或配置错误)
缺 spid200SPID_REQUIRED归一 UNAVAILABLE
spid / env 不存在或语法非法;opened 未命中投递记录200NOT_FOUNDregister:下一求值点再试;opened:只拉起 App,不回调、不上报
设备配额满(新设备)200PUSH_DEVICE_QUOTA_EXCEEDED归一 UNAVAILABLE;既有设备更新不受影响
限流(60/min per (spid, IP) · 6000/min per spid · 平台限流存储不可用时也拒绝)429TOO_MANY_REQUESTS归一 RATE_LIMITED,24 小时内会补登记
推送模块关闭503PUSH_DISABLED归一 UNAVAILABLE

user_id 与 tags 由客户端自报、平台不校验身份:按用户 ID 定向只是「App 自称是谁」,不是身份认证。

业务后端用控制台签发的 sst_ API Token 调推送 API,不经过 App。权限等于签发者在组织内的角色,发送需要 admin。一个 Token 绑定组织而不是项目,所以请求体必须带 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": "双十一预热:全场 8 折",
"body": "11 月 1 日 0 点开抢",
"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:目标项目(必填);X-Super-API-ENV:目标环境(必填,缺省不回落 prod)。
  • audience.type:device(device_ids[] ≤1000)、tag(tags[] ≤10,命中任一)、user(user_ids[] ≤1000,按设备自报的 user_id 匹配,不是身份认证)、all。
  • click.type:open_app 或 open_url(SDK 容器打开该 URL)。data 是扁平的字符串键值,不得使用保留键 from / notification / message_type / collapse_key / google.* / gcm.* / spid / env / message_id / url / click_type。
  • 响应:{"code":"SUCCESS","data":{"message_id":"pm_...","audience_estimate":1596}}。发送是异步的,进度看 GET /api/console/machine/push/messages/{message_id}(同 Token + X-Super-API-ENV,返回状态、六项计数与时间戳)或控制台记录页。
  • 幂等键(两种来源,二选一必填):Idempotency-Key(1..255 字节,建议 uuid),或由 SuperScheduler 每次执行自动注入的 X-SuperSDK-Execution-Id(同一次执行的多次重试共享同一个值)。同键同内容 24 小时内重复提交返回同一条记录、不会重发;同键不同内容返回 409 PUSH_IDEMPOTENCY_CONFLICT;两种头都缺返回 422 INVALID_REQUEST。
  • HTTP 状态:这条机器面接口对业务拒绝回非 2xx(与控制台 / CLI 面的「业务码一律 200」不同),这样 Scheduler 或你的 HTTP 客户端不解析响应体也能知道失败。响应体仍是统一信封 {code, message, data, extra}。
业务码含义机器面 HTTP控制台 / cli_ 面 HTTP可重试
SUCCESS已受理200200—
PUSH_NOT_CONFIGURED该环境未上传凭据422200否
PUSH_CREDENTIAL_INVALID凭据已失效(设置页红灯,需重新上传或「测试连接」)422200否
PUSH_AUDIENCE_EMPTY受众为 0(无匹配、全部通知关闭或已失效)422200否
PUSH_AUDIENCE_TOO_LARGE受众 > 50,000422200否
PUSH_INVALID_ARGUMENT字段级错误(extra.field 指出字段):标题 / 正文 / URL / data 形状或保留键 / 整条 > 4 KiB / device_ids 不属本环境422200否
INVALID_REQUEST缺 X-Super-API-ENV / 两种幂等键都缺 / 键超长 / 非法 JSON422200否
PUSH_IDEMPOTENCY_CONFLICT同幂等键、不同内容409—(控制台面无幂等键)否
PUSH_RATE_LIMITED该环境 20 次 / 分钟,extra.retry_after_secs 给出恢复秒数429200是
NOT_FOUNDspid 不属于 Token 所在组织 / message_id 不存在(两者不可区分)404200否
FORBIDDENToken 签发者不是 admin403403否
(无 code)Token 无效 / 过期 / 不是 sst_401401否
PUSH_DISABLED平台推送模块关闭503503是
  • 记录里的失败码(不是响应码):FCM 原生码原样保留(UNREGISTERED 设备已失效、QUOTA_EXCEEDED、UNAVAILABLE / INTERNAL 退避重试后仍失败、SENDER_ID_MISMATCH 凭据与 App 的 Firebase 项目不一致、THIRD_PARTY_AUTH_ERROR);平台自定义两枚:CREDENTIAL_INVALID(整条消息因凭据失效终止,详情页链接到推送设置)与 PUSH_INVALID_PAYLOAD(FCM 以消息级 INVALID_ARGUMENT 拒绝,详情页给出字段路径)。
  • 定时推送:在 SuperScheduler 建一条 cron 任务,目标就是上面这条接口,Header 里放 sst_ Token(信封加密保存)与 X-Super-API-ENV,body 带 spid;不用自己填幂等键,Scheduler 每次执行恒带 X-SuperSDK-Job 与 X-SuperSDK-Execution-Id,同一次执行的重试不会重复广播。Scheduler 执行历史中的失败 = 推送被拒绝(422/409/429/503),响应体里的 code 就是原因;若执行历史是 403 / 503 而响应体不是上面的 JSON 信封(例如 HTML),说明请求被 Cloudflare 挡在平台之外,联系平台方处理,不要改 Job。
  • 投递语义:至少一次。平台滚动发布或节点故障时最多重发一个批次(≤200 台);取消正在发送的消息时已发出的通知不召回,记录里这些设备显示为 skipped。

4. SuperCLI 使用方式(BL-014 · 后置)

Section titled “4. SuperCLI 使用方式(BL-014 · 后置)”

薄封装上面的控制台 API,SPID 从 super.json 读,--env 必填:

Terminal window
supercli push devices --env prod --tag vip --output json --no-input
supercli push send --env prod --title "标题" --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 # 只显示 project_id / client_email / 最近验证,不回显私钥

凭据上传只在控制台做,CLI 不提供上传服务账号的命令。

路径:控制台 → 业务运营 → 推送。四个页面都跟随顶栏的环境选择器;平台推送模块关闭时四页统一显示「推送功能未启用」。

上传 Firebase 服务账号 JSON,平台立即做一次连接验证(换取访问令牌 + 向 FCM 发一条 validate_only 的测试请求)并只保存密文;页面只显示 firebase_project_id、client_email、上传人与时间、最近验证结果(成功 / 凭据无效 / FCM API 未启用 / 网络暂时不可达)。可以随时「测试连接」(成功会把失效态恢复为已配置)或「移除」;替换成另一个 Firebase 项目的凭据或移除时,该环境排队中 / 发送中的消息会被终止为 CREDENTIAL_INVALID,确认框会显示条数。页面上的「复制接入指南」会把 §2 与 §3 连同当前 spid、环境与 SDK 版本一起复制,可直接交给 Agent。

当前环境已登记的设备:device_id、平台、App / SDK 版本、token 尾号、用户 ID、标签、状态(active / unregistered)、通知是否开启、最近活跃;页头显示配额水位与「已失效 / 通知已关闭」数。可按平台、标签、用户 ID、状态、通知开关筛选,行内「发送测试推送」直接跳到发送页并选中该设备,admin 可移除设备。空列表时页面给出三步接入引导。

选受众(指定设备 / 按标签 / 按用户 ID / 全部),填标题、正文、图片、点击动作与自定义数据,右侧实时显示预计受众数、被排除的「通知已关闭 / 已失效」数、整条消息字节数与通知预览。未上传凭据时整页引导到推送设置。提交后进入记录详情。

每条发送的状态(queued / processing / completed / failed / cancelled)与总数 / 已送达 / 失败 / 无效 token / 已跳过 / 已打开,总数 = 已送达 + 失败 + 无效 + 已跳过;进行中的记录可取消(已发出的不召回)。详情页有错误分布(每个错误码的含义与建议)和逐设备投递表,可按 device_id 搜索、按状态筛选;逐设备明细保留 7 天。CREDENTIAL_INVALID 的记录会链接到推送设置。member 可查看全部页面,但不能发送、取消、上传、移除。