@supersdk/jssdk 1.0.0 → 3.0.5-SNAPSHOT
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +59 -0
- package/JSBridge.md +416 -0
- package/README.md +62 -0
- package/dist/global.cjs +5 -1
- package/dist/global.js +5 -1
- package/dist/index.bundle.cjs +5 -1
- package/dist/index.d.ts +276 -9
- package/dist/index.js +5 -1
- package/dist/manifest.json +15 -8
- package/dist/mock.cjs +1 -0
- package/dist/mock.d.ts +21 -0
- package/dist/mock.js +1 -0
- package/dist/monitoring-contract.d.ts +26 -0
- package/dist/protocol.cjs +1 -0
- package/dist/protocol.d.ts +141 -0
- package/dist/protocol.js +1 -0
- package/dist/supersdk.js +5 -1
- package/package.json +27 -6
- package/protocol/experiment-v1-golden.json +2338 -0
- package/protocol/experiment-v1.json +93 -0
- package/protocol/golden-vectors.json +29 -0
- package/protocol/monitoring-v1-golden.json +16 -0
- package/protocol/monitoring-v1.json +41 -0
- package/protocol/push-v1.json +662 -0
- package/protocol/suenc-v1-golden.json +93 -0
- package/protocol/suenc-v1.json +37 -0
- package/protocol/v1.json +101 -0
|
@@ -0,0 +1,662 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schema": "supersdk.push.contract",
|
|
3
|
+
"version": 1,
|
|
4
|
+
"feature_refs": [
|
|
5
|
+
"SDK-F261008030551-Android-Push-Firebase (S2)",
|
|
6
|
+
"CA-F038 (S1)",
|
|
7
|
+
"WS-18"
|
|
8
|
+
],
|
|
9
|
+
"status": "frozen-day0",
|
|
10
|
+
"notes": [
|
|
11
|
+
"Day-0 契约单源(2026-10-21 CA-F261008030542 Round 3 F18 起唯一一份;原 services/super-server/tests/fixtures/push-contract-v1.json 副本已删除)。S1 以 include_str! 反向引用本文件(CA push/{mod,public,fcm}.rs 与 live/devices.rs、SS handler/proxy.rs 测试与 tests/push_contract.rs,照 services/super-server/src/suenc/mod.rs 先例),S2 Android 单测读 ../jssdk/protocol/push-v1.json、jssdk 测试读 protocol/push-v1.json;两侧禁止各写一份字面量(KNOWLEDGE GO-026)。改契约 = 改本文件,两侧测试同时跟随。",
|
|
12
|
+
"JSON 命名 snake_case;长度一律按 Unicode 码点(Rust chars() / Java codePointCount)计,不按字节、不按 UTF-16;JSSDK 不做第二套边界校验(透传原生,ARCH-8)。",
|
|
13
|
+
"字符集约束 'no_control' = 不含 U+0000–U+001F 与 U+007F;'trim' = 服务端与 SDK 都先 trim 再校验;SDK 本地校验失败不发请求(INVALID_ARGUMENT),服务端校验失败回 INVALID_REQUEST。",
|
|
14
|
+
"服务端 upsert 以本次登记体为准:缺省可选字段 = 清除(null / [] 与缺省同义),不保留旧值。SDK 侧恒显式带 user_id(可为 null)与 tags(可为 [])两个键,所有 register 完整请求示例(含 register_not_found)均显式写出(CR-8 / CR2-6);register_invalid_tags 只给 request_delta。",
|
|
15
|
+
"D-T6 选 C 生效:点击打开的权威目标由 opened 回执响应返回(data.click_type / data.url),SDK 只打开服务端返回的 url;伪造 message_id 在服务端不存在 → NOT_FOUND → SDK 按 open_app 只拉起主 Activity。",
|
|
16
|
+
"2026-10-21 服务端事实并入(CA-F261008030542 Round 3 F17/F18):限流数值 60/(spid,IP) + 6000/spid、PUSH_DISABLED 503 含义、token 字母表正则、两层 16 KiB 体限、opened 命中回权威 {click_type,url?}、未命中统一 NOT_FOUND(与 spid/env 未知同一信封)、fcm_message.reserved_keys;sdk_last_error 列与闭集不变(Q-7=A)。"
|
|
17
|
+
],
|
|
18
|
+
"transport": {
|
|
19
|
+
"sdk_public_base": "https://api.supersdk.com",
|
|
20
|
+
"ss_paths": {
|
|
21
|
+
"register": "/superapi/v2/push/register",
|
|
22
|
+
"opened": "/superapi/v2/push/opened"
|
|
23
|
+
},
|
|
24
|
+
"ca_upstream_paths": {
|
|
25
|
+
"register": "/api/public/v2/push/register",
|
|
26
|
+
"opened": "/api/public/v2/push/opened"
|
|
27
|
+
},
|
|
28
|
+
"method": "POST",
|
|
29
|
+
"content_type": "application/json",
|
|
30
|
+
"sdk_headers_auto": [
|
|
31
|
+
"X-Aid",
|
|
32
|
+
"X-Super-API-ENV",
|
|
33
|
+
"X-Device-Id",
|
|
34
|
+
"X-SDK-Version",
|
|
35
|
+
"X-Os-Type",
|
|
36
|
+
"X-User-Agent"
|
|
37
|
+
],
|
|
38
|
+
"header_body_consistency": "X-Aid == body.spid,X-Super-API-ENV == body.env(缺省 prod),X-Device-Id == body.device_id;不一致时服务端以 body 为准并可回 INVALID_REQUEST",
|
|
39
|
+
"envelope": {
|
|
40
|
+
"code": "string",
|
|
41
|
+
"message": "string",
|
|
42
|
+
"data": "object",
|
|
43
|
+
"extra": "object"
|
|
44
|
+
},
|
|
45
|
+
"rate_limit": "与 feedback 公开入口同纪律:fail-closed(Redis 不可用即 429);每 (spid, 客户端 IP) 60/min + 每 spid 6000/min(PRD AC-1);计数先于项目/环境解析,NOT_FOUND 的请求也计数;超限 HTTP 429 + code TOO_MANY_REQUESTS",
|
|
46
|
+
"ss_proxy_body_limit_bytes": 16384,
|
|
47
|
+
"ca_public_body_limit_bytes": 16384
|
|
48
|
+
},
|
|
49
|
+
"message_id_format": {
|
|
50
|
+
"regex": "^pm_[0-9a-f]{12}$",
|
|
51
|
+
"example": "pm_7f3a9c2e41b0",
|
|
52
|
+
"generated_by": "S1 发送时生成;SDK 只校验格式,不生成"
|
|
53
|
+
},
|
|
54
|
+
"enabled_semantics": {
|
|
55
|
+
"definition": "通知当前对用户可见:NotificationManagerCompat.areNotificationsEnabled() 为 true,且 Android 13+ 上 POST_NOTIFICATIONS 运行时权限已授予;两者皆满足才为 true。",
|
|
56
|
+
"false_means": "设备仍登记(D-4=A);控制台设备页可区分「接入成功但未授权」;发送侧按 enabled 过滤或统计由 S1 决定。",
|
|
57
|
+
"refresh": "权限 / 系统开关变化后由 SDK 在下一求值点(冷启动 / 回前台 / 权限回调)重登记刷新。"
|
|
58
|
+
},
|
|
59
|
+
"field_constraints": {
|
|
60
|
+
"spid": {
|
|
61
|
+
"type": "string",
|
|
62
|
+
"regex": "^[a-z0-9]{8}$",
|
|
63
|
+
"required": true
|
|
64
|
+
},
|
|
65
|
+
"env": {
|
|
66
|
+
"type": "string",
|
|
67
|
+
"regex": "^[a-z0-9]{1,10}$",
|
|
68
|
+
"required": false,
|
|
69
|
+
"default": "prod"
|
|
70
|
+
},
|
|
71
|
+
"device_id": {
|
|
72
|
+
"type": "string",
|
|
73
|
+
"min": 8,
|
|
74
|
+
"max": 64,
|
|
75
|
+
"charset": "no_control",
|
|
76
|
+
"required": true,
|
|
77
|
+
"source": "SDevice.getOrCreateDeviceId(),与 X-Device-Id 一致"
|
|
78
|
+
},
|
|
79
|
+
"token": {
|
|
80
|
+
"type": "string",
|
|
81
|
+
"min": 32,
|
|
82
|
+
"max": 4096,
|
|
83
|
+
"charset": "no_control",
|
|
84
|
+
"regex": "^[A-Za-z0-9_:\\-]{32,4096}$",
|
|
85
|
+
"required": true,
|
|
86
|
+
"privacy": "日志只打末 6 位",
|
|
87
|
+
"note": "regex 是服务端(CA validate_register)校验;长度按码点 32..4096。SDK 本地只做 no_control + 长度校验(1.0.0.66 已发布行为),字母表外字符由服务端回 INVALID_REQUEST(FCM 下发的 token 恒在该字母表内)"
|
|
88
|
+
},
|
|
89
|
+
"platform": {
|
|
90
|
+
"type": "string",
|
|
91
|
+
"enum": [
|
|
92
|
+
"android",
|
|
93
|
+
"ios"
|
|
94
|
+
],
|
|
95
|
+
"required": true
|
|
96
|
+
},
|
|
97
|
+
"app_version": {
|
|
98
|
+
"type": "string",
|
|
99
|
+
"min": 1,
|
|
100
|
+
"max": 32,
|
|
101
|
+
"charset": "no_control",
|
|
102
|
+
"required": true
|
|
103
|
+
},
|
|
104
|
+
"sdk_version": {
|
|
105
|
+
"type": "string",
|
|
106
|
+
"min": 1,
|
|
107
|
+
"max": 32,
|
|
108
|
+
"charset": "no_control",
|
|
109
|
+
"required": true
|
|
110
|
+
},
|
|
111
|
+
"locale": {
|
|
112
|
+
"type": "string",
|
|
113
|
+
"format": "BCP-47 language tag(Locale.getDefault().toLanguageTag())",
|
|
114
|
+
"max": 35,
|
|
115
|
+
"required": false
|
|
116
|
+
},
|
|
117
|
+
"user_id": {
|
|
118
|
+
"type": "string|null",
|
|
119
|
+
"min": 1,
|
|
120
|
+
"max": 128,
|
|
121
|
+
"charset": "no_control",
|
|
122
|
+
"trim": true,
|
|
123
|
+
"required": false,
|
|
124
|
+
"null_semantics": "null / 缺省 = 清除;空串在 SDK 侧折为 null",
|
|
125
|
+
"security": "客户端自报、无身份校验;按 user_id 定向不是身份认证"
|
|
126
|
+
},
|
|
127
|
+
"tags": {
|
|
128
|
+
"type": "array<string>|null",
|
|
129
|
+
"max_items": 10,
|
|
130
|
+
"item_min": 1,
|
|
131
|
+
"item_max": 32,
|
|
132
|
+
"item_charset": "no_control",
|
|
133
|
+
"trim": true,
|
|
134
|
+
"dedupe": true,
|
|
135
|
+
"required": false,
|
|
136
|
+
"null_semantics": "[] / null / 缺省 = 清除"
|
|
137
|
+
},
|
|
138
|
+
"enabled": {
|
|
139
|
+
"type": "boolean",
|
|
140
|
+
"required": true,
|
|
141
|
+
"see": "enabled_semantics"
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
"register": {
|
|
145
|
+
"request": {
|
|
146
|
+
"fields": [
|
|
147
|
+
"spid",
|
|
148
|
+
"env",
|
|
149
|
+
"device_id",
|
|
150
|
+
"token",
|
|
151
|
+
"platform",
|
|
152
|
+
"app_version",
|
|
153
|
+
"sdk_version",
|
|
154
|
+
"locale",
|
|
155
|
+
"user_id",
|
|
156
|
+
"tags",
|
|
157
|
+
"enabled"
|
|
158
|
+
],
|
|
159
|
+
"required": [
|
|
160
|
+
"spid",
|
|
161
|
+
"device_id",
|
|
162
|
+
"token",
|
|
163
|
+
"platform",
|
|
164
|
+
"app_version",
|
|
165
|
+
"sdk_version",
|
|
166
|
+
"enabled"
|
|
167
|
+
],
|
|
168
|
+
"optional": [
|
|
169
|
+
"env",
|
|
170
|
+
"locale",
|
|
171
|
+
"user_id",
|
|
172
|
+
"tags"
|
|
173
|
+
]
|
|
174
|
+
},
|
|
175
|
+
"response_success": {
|
|
176
|
+
"code": "SUCCESS",
|
|
177
|
+
"message": "",
|
|
178
|
+
"data": {
|
|
179
|
+
"device_id": "string · 回显请求 device_id",
|
|
180
|
+
"status": "enum active | unregistered"
|
|
181
|
+
},
|
|
182
|
+
"extra": {}
|
|
183
|
+
},
|
|
184
|
+
"sdk_behaviour": {
|
|
185
|
+
"triggers": [
|
|
186
|
+
"首次(本地无持久化指纹)取得 token",
|
|
187
|
+
"FCM token 刷新",
|
|
188
|
+
"setAPIEnvironment 切到不同环境",
|
|
189
|
+
"setTags / setUserId 改变了值",
|
|
190
|
+
"requestPermission 返回",
|
|
191
|
+
"冷启动 / 回前台时 enabled 与上次不同",
|
|
192
|
+
"指纹相同但上次成功登记超过 24h"
|
|
193
|
+
],
|
|
194
|
+
"fingerprint": [
|
|
195
|
+
"env",
|
|
196
|
+
"token",
|
|
197
|
+
"tags",
|
|
198
|
+
"user_id",
|
|
199
|
+
"enabled",
|
|
200
|
+
"locale",
|
|
201
|
+
"app_version",
|
|
202
|
+
"sdk_version"
|
|
203
|
+
],
|
|
204
|
+
"ttl_hours": 24,
|
|
205
|
+
"in_flight": "同一时刻只允许一个在途登记;在途期间触发置脏,成功后按最新值补发一次;失败不补发",
|
|
206
|
+
"env_read_at": "发送时(不在触发时快照)",
|
|
207
|
+
"retry": "不在进程内定时重试;下一求值点再试"
|
|
208
|
+
}
|
|
209
|
+
},
|
|
210
|
+
"opened": {
|
|
211
|
+
"request": {
|
|
212
|
+
"fields": [
|
|
213
|
+
"spid",
|
|
214
|
+
"env",
|
|
215
|
+
"device_id",
|
|
216
|
+
"message_id"
|
|
217
|
+
],
|
|
218
|
+
"required": [
|
|
219
|
+
"spid",
|
|
220
|
+
"device_id",
|
|
221
|
+
"message_id"
|
|
222
|
+
],
|
|
223
|
+
"optional": [
|
|
224
|
+
"env"
|
|
225
|
+
],
|
|
226
|
+
"message_id": {
|
|
227
|
+
"regex": "^pm_[0-9a-f]{12}$"
|
|
228
|
+
},
|
|
229
|
+
"note": "必须先于打开动作发出(D-T6 C):中转 Activity 等待响应 ≤ 2000ms"
|
|
230
|
+
},
|
|
231
|
+
"response_success": {
|
|
232
|
+
"code": "SUCCESS",
|
|
233
|
+
"message": "",
|
|
234
|
+
"data": {
|
|
235
|
+
"click_type": "open_app | open_url(服务端记录的发送配置 · 权威值)",
|
|
236
|
+
"url": "click_type=open_url 时存在(open_app 不带 url 键)· 服务端记录的发送配置 url · SDK 只打开此值"
|
|
237
|
+
},
|
|
238
|
+
"extra": {},
|
|
239
|
+
"note": "D-T6 选 C 生效:SDK 不信任 intent extras 里的 url,只打开 data.url;data.url 仍须通过 SDK scheme 白名单(http/https/宿主白名单)"
|
|
240
|
+
},
|
|
241
|
+
"server_semantics": "校验 message_id 属于 (spid, env, device_id) 的投递行。命中 = 该设备在该消息下有 status ∈ sending/retrying/delivered/skipped(1/2/3/6)的投递行(skipped 含取消时已交给 FCM 的行):回 SUCCESS + 服务端权威 {click_type, url?},重复回执幂等成功并同样返回 click_type/url;只有 status ∈ 1/2/3 且尚未回执过的行才落 opened_at 并 opened+1(按 (message_id, device_id) 去重,opened ≤ delivered + sending/retrying)。未命中(message 不存在 / 不属于该 spid·env / 该设备无投递行 / 投递行不可打开)→ HTTP 200 + NOT_FOUND,与 spid/env 未知同一信封、各种未命中之间不可区分。投递明细保留 7 天:超过 7 天的点击按未命中处理(只拉起 App)",
|
|
242
|
+
"sdk_behaviour": "点击通过 AC-4 本地校验后立即回执一次并等待 ≤2000ms:SUCCESS → 回调 listener / push.opened / lastOpened / $push_open(载荷 verified=true,url/click_type 取服务端值),再按 data.click_type/url 打开;NOT_FOUND → 只拉起主 Activity、不回调、不上报、SLogger.e;超时 / 网络失败 / 其他错误(回执不可达)→ 回调与 push.opened / $push_open 照做(消息本地合规,载荷 verified=false、url 为 intent 原值),但不打开 URL、只拉起主 Activity(open_app),不重试,只记 SLogger.e + SLogger.w。降级语义(D-T6 C · CR2-1):伪造防护只在服务端可达时完整;回执不可达时伪造者最多能触发一次宿主回调与事件、拿不到打开页面。",
|
|
243
|
+
"response_not_found": {
|
|
244
|
+
"code": "NOT_FOUND",
|
|
245
|
+
"message": "not found",
|
|
246
|
+
"data": {},
|
|
247
|
+
"extra": {},
|
|
248
|
+
"meaning": "message_id 不存在、或不属于该 device_id / spid / env(含伪造 intent)、或该设备投递行不可打开 / 已过 7 天保留期 → SDK 按 open_app 只拉起主 Activity,不回调、不上报;信封与 spid/env 未知的 NOT_FOUND 完全相同"
|
|
249
|
+
},
|
|
250
|
+
"degrade_semantics": "回执不可达时:回调与事件照做(verified=false)但不打开 URL(只 open_app);$push_open 照报;伪造防护在服务端可达时才完整,离线时伪造者最多触发一次回调与事件、拿不到打开页面"
|
|
251
|
+
},
|
|
252
|
+
"error_codes": [
|
|
253
|
+
{
|
|
254
|
+
"http": 200,
|
|
255
|
+
"code": "INVALID_REQUEST",
|
|
256
|
+
"meaning": "字段校验失败(长度 / 字符集 / 格式 / header-body 不一致)",
|
|
257
|
+
"sdk_last_error": "INVALID_REQUEST",
|
|
258
|
+
"retry": "不自动重试(配置或实现错误)"
|
|
259
|
+
},
|
|
260
|
+
{
|
|
261
|
+
"http": 200,
|
|
262
|
+
"code": "NOT_FOUND",
|
|
263
|
+
"meaning": "register:spid 或 env 未在控制台注册;opened:message_id 不属于该设备/项目/环境",
|
|
264
|
+
"sdk_last_error": "NOT_FOUND(register)/ opened 路径不进 lastError,按 open_app 处理",
|
|
265
|
+
"retry": "不自动重试;register 下一求值点再试"
|
|
266
|
+
},
|
|
267
|
+
{
|
|
268
|
+
"http": 200,
|
|
269
|
+
"code": "SPID_REQUIRED",
|
|
270
|
+
"meaning": "请求缺 spid",
|
|
271
|
+
"sdk_last_error": "UNAVAILABLE",
|
|
272
|
+
"retry": "闭集外 code 归一 UNAVAILABLE,原 code 只写 logcat(PRD AC-2 v1.0 · D-T1 维持)"
|
|
273
|
+
},
|
|
274
|
+
{
|
|
275
|
+
"http": 503,
|
|
276
|
+
"code": "PUSH_DISABLED",
|
|
277
|
+
"meaning": "推送模块关闭(PUSH_MODULE_ENABLED=false · 全部 push 路由与公开入口 · HTTP 503);与凭据是否配置无关(未配置是发送面的 PUSH_NOT_CONFIGURED)",
|
|
278
|
+
"sdk_last_error": "UNAVAILABLE",
|
|
279
|
+
"retry": "下一求值点再试"
|
|
280
|
+
},
|
|
281
|
+
{
|
|
282
|
+
"http": 200,
|
|
283
|
+
"code": "PUSH_DEVICE_QUOTA_EXCEEDED",
|
|
284
|
+
"meaning": "环境设备数达到上限(100,000)",
|
|
285
|
+
"sdk_last_error": "UNAVAILABLE",
|
|
286
|
+
"retry": "下一求值点再试"
|
|
287
|
+
},
|
|
288
|
+
{
|
|
289
|
+
"http": 429,
|
|
290
|
+
"code": "TOO_MANY_REQUESTS",
|
|
291
|
+
"meaning": "公开入口限流(与 CA PRD 对齐:HTTP 429 + code TOO_MANY_REQUESTS)",
|
|
292
|
+
"sdk_last_error": "RATE_LIMITED",
|
|
293
|
+
"retry": "下一求值点再试(SDK 以 HTTP 429 为判据,不依赖信封 code)"
|
|
294
|
+
},
|
|
295
|
+
{
|
|
296
|
+
"http": "5xx (非 503+PUSH_DISABLED)",
|
|
297
|
+
"code": "UNAVAILABLE",
|
|
298
|
+
"meaning": "服务端不可用",
|
|
299
|
+
"sdk_last_error": "UNAVAILABLE",
|
|
300
|
+
"retry": "下一求值点再试"
|
|
301
|
+
},
|
|
302
|
+
{
|
|
303
|
+
"http": "other non-2xx",
|
|
304
|
+
"code": "-",
|
|
305
|
+
"meaning": "如 404(代理未部署)",
|
|
306
|
+
"sdk_last_error": "UNAVAILABLE",
|
|
307
|
+
"retry": "下一求值点再试"
|
|
308
|
+
},
|
|
309
|
+
{
|
|
310
|
+
"http": "IO",
|
|
311
|
+
"code": "-",
|
|
312
|
+
"meaning": "无网络 / 超时 / 连接失败",
|
|
313
|
+
"sdk_last_error": "NETWORK_ERROR",
|
|
314
|
+
"retry": "下一求值点再试"
|
|
315
|
+
},
|
|
316
|
+
{
|
|
317
|
+
"http": 200,
|
|
318
|
+
"code": "<unknown or malformed>",
|
|
319
|
+
"meaning": "闭集外业务码、信封形状不对(PROTOCOL_MISMATCH)",
|
|
320
|
+
"sdk_last_error": "UNAVAILABLE",
|
|
321
|
+
"retry": "下一求值点再试"
|
|
322
|
+
},
|
|
323
|
+
{
|
|
324
|
+
"http": "-",
|
|
325
|
+
"code": "-",
|
|
326
|
+
"meaning": "Firebase 未配置 / 取不到 token(SDK 本地)",
|
|
327
|
+
"sdk_last_error": "TOKEN_UNAVAILABLE",
|
|
328
|
+
"retry": "下一次 token 回调"
|
|
329
|
+
}
|
|
330
|
+
],
|
|
331
|
+
"sdk_last_error_closed_set": [
|
|
332
|
+
"TOKEN_UNAVAILABLE",
|
|
333
|
+
"NOT_FOUND",
|
|
334
|
+
"INVALID_REQUEST",
|
|
335
|
+
"RATE_LIMITED",
|
|
336
|
+
"NETWORK_ERROR",
|
|
337
|
+
"UNAVAILABLE"
|
|
338
|
+
],
|
|
339
|
+
"fcm_message": {
|
|
340
|
+
"description": "S1 经 FCM HTTP v1 messages:send 发出的消息形态。App 后台 / 被杀时由 FCM SDK 按 notification 渲染,点击目标由 android.notification.click_action 决定;前台由外挂包 onMessageReceived 自渲染并把同一 data 原键放进 PendingIntent extras。",
|
|
341
|
+
"click_action": "com.supersdk.push.OPEN",
|
|
342
|
+
"data_keys": {
|
|
343
|
+
"spid": "发送项目 spid(SDK 与当前一致才处理)",
|
|
344
|
+
"env": "发送环境(SDK 与当前一致才处理)",
|
|
345
|
+
"message_id": "pm_[0-9a-f]{12}",
|
|
346
|
+
"url": "click.type=open_url 时存在;http(s) 或宿主白名单 scheme",
|
|
347
|
+
"click_type": "open_app | open_url"
|
|
348
|
+
},
|
|
349
|
+
"custom_data_passthrough": "发送方 data{} 原键透传,不得覆盖上述固定键;固定键名不加 supersdk_ 前缀,点击 intent extras 就是 data 原键名",
|
|
350
|
+
"reserved_keys": {
|
|
351
|
+
"fcm": [
|
|
352
|
+
"from",
|
|
353
|
+
"notification",
|
|
354
|
+
"message_type",
|
|
355
|
+
"collapse_key",
|
|
356
|
+
"google.*",
|
|
357
|
+
"gcm.*"
|
|
358
|
+
],
|
|
359
|
+
"platform": [
|
|
360
|
+
"spid",
|
|
361
|
+
"env",
|
|
362
|
+
"message_id",
|
|
363
|
+
"url",
|
|
364
|
+
"click_type"
|
|
365
|
+
],
|
|
366
|
+
"rule": "发送方 data 含任一保留键 → 发送面 PUSH_INVALID_ARGUMENT(CA-F261008030542 AC-3)"
|
|
367
|
+
},
|
|
368
|
+
"size_limit_bytes": 4096,
|
|
369
|
+
"example": {
|
|
370
|
+
"message": {
|
|
371
|
+
"token": "<device fcm token>",
|
|
372
|
+
"notification": {
|
|
373
|
+
"title": "双十一预热:全场 8 折",
|
|
374
|
+
"body": "11 月 1 日 0 点开抢",
|
|
375
|
+
"image": "https://cdn.example.com/promo/1111-banner.png"
|
|
376
|
+
},
|
|
377
|
+
"android": {
|
|
378
|
+
"priority": "HIGH",
|
|
379
|
+
"notification": {
|
|
380
|
+
"click_action": "com.supersdk.push.OPEN",
|
|
381
|
+
"image": "https://cdn.example.com/promo/1111-banner.png"
|
|
382
|
+
}
|
|
383
|
+
},
|
|
384
|
+
"data": {
|
|
385
|
+
"spid": "ab12cd34",
|
|
386
|
+
"env": "prod",
|
|
387
|
+
"message_id": "pm_7f3a9c2e41b0",
|
|
388
|
+
"url": "https://demo.example.com/promo/1111",
|
|
389
|
+
"click_type": "open_url",
|
|
390
|
+
"campaign": "1111"
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
},
|
|
394
|
+
"open_app_example_data": {
|
|
395
|
+
"spid": "ab12cd34",
|
|
396
|
+
"env": "staging",
|
|
397
|
+
"message_id": "pm_0a1b2c3d4e5f",
|
|
398
|
+
"click_type": "open_app"
|
|
399
|
+
}
|
|
400
|
+
},
|
|
401
|
+
"push_open_event": {
|
|
402
|
+
"event_name": "$push_open",
|
|
403
|
+
"params": {
|
|
404
|
+
"message_id": "required",
|
|
405
|
+
"url": "optional",
|
|
406
|
+
"click_type": "open_app | open_url",
|
|
407
|
+
"verified": "boolean · true=来自服务端回执 · false=回执不可达的降级路径(v0.3)"
|
|
408
|
+
},
|
|
409
|
+
"common_params_from_pipeline": [
|
|
410
|
+
"spid",
|
|
411
|
+
"env",
|
|
412
|
+
"device_id",
|
|
413
|
+
"app_version",
|
|
414
|
+
"sdk_version"
|
|
415
|
+
],
|
|
416
|
+
"condition": "仅 message_id 合规且 spid/env 与当前一致的点击;每次点击恰好一条"
|
|
417
|
+
},
|
|
418
|
+
"examples": [
|
|
419
|
+
{
|
|
420
|
+
"name": "first_register",
|
|
421
|
+
"endpoint": "register",
|
|
422
|
+
"request": {
|
|
423
|
+
"spid": "ab12cd34",
|
|
424
|
+
"env": "prod",
|
|
425
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
426
|
+
"token": "fXk9Qw2pT0a:APA91bExampleTokenExampleTokenExampleTokenExampleToken1234567890",
|
|
427
|
+
"platform": "android",
|
|
428
|
+
"app_version": "1.0.0",
|
|
429
|
+
"sdk_version": "1.0.0",
|
|
430
|
+
"locale": "zh-CN",
|
|
431
|
+
"user_id": "u_12345",
|
|
432
|
+
"tags": [
|
|
433
|
+
"vip",
|
|
434
|
+
"beta"
|
|
435
|
+
],
|
|
436
|
+
"enabled": true
|
|
437
|
+
},
|
|
438
|
+
"response": {
|
|
439
|
+
"code": "SUCCESS",
|
|
440
|
+
"message": "",
|
|
441
|
+
"data": {
|
|
442
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
443
|
+
"status": "active"
|
|
444
|
+
},
|
|
445
|
+
"extra": {}
|
|
446
|
+
}
|
|
447
|
+
},
|
|
448
|
+
{
|
|
449
|
+
"name": "clear_tags_and_user",
|
|
450
|
+
"endpoint": "register",
|
|
451
|
+
"request": {
|
|
452
|
+
"spid": "ab12cd34",
|
|
453
|
+
"env": "prod",
|
|
454
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
455
|
+
"token": "fXk9Qw2pT0a:APA91bExampleTokenExampleTokenExampleTokenExampleToken1234567890",
|
|
456
|
+
"platform": "android",
|
|
457
|
+
"app_version": "1.0.0",
|
|
458
|
+
"sdk_version": "1.0.0",
|
|
459
|
+
"locale": "zh-CN",
|
|
460
|
+
"user_id": null,
|
|
461
|
+
"tags": [],
|
|
462
|
+
"enabled": true
|
|
463
|
+
},
|
|
464
|
+
"response": {
|
|
465
|
+
"code": "SUCCESS",
|
|
466
|
+
"message": "",
|
|
467
|
+
"data": {
|
|
468
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
469
|
+
"status": "active"
|
|
470
|
+
},
|
|
471
|
+
"extra": {}
|
|
472
|
+
},
|
|
473
|
+
"expect": "服务端清空 user_id 与 tags,不保留旧值"
|
|
474
|
+
},
|
|
475
|
+
{
|
|
476
|
+
"name": "register_disabled",
|
|
477
|
+
"endpoint": "register",
|
|
478
|
+
"request": {
|
|
479
|
+
"spid": "ab12cd34",
|
|
480
|
+
"env": "staging",
|
|
481
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
482
|
+
"token": "fXk9Qw2pT0a:APA91bExampleTokenExampleTokenExampleTokenExampleToken1234567890",
|
|
483
|
+
"platform": "android",
|
|
484
|
+
"app_version": "1.0.0",
|
|
485
|
+
"sdk_version": "1.0.0",
|
|
486
|
+
"locale": "en-US",
|
|
487
|
+
"enabled": false,
|
|
488
|
+
"user_id": null,
|
|
489
|
+
"tags": []
|
|
490
|
+
},
|
|
491
|
+
"response": {
|
|
492
|
+
"code": "SUCCESS",
|
|
493
|
+
"message": "",
|
|
494
|
+
"data": {
|
|
495
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
496
|
+
"status": "active"
|
|
497
|
+
},
|
|
498
|
+
"extra": {}
|
|
499
|
+
},
|
|
500
|
+
"expect": "设备仍入库;enabled=false 可见于设备页;SDK 显式带 user_id:null 与 tags:[](无值也不省键)"
|
|
501
|
+
},
|
|
502
|
+
{
|
|
503
|
+
"name": "register_not_found",
|
|
504
|
+
"endpoint": "register",
|
|
505
|
+
"request": {
|
|
506
|
+
"spid": "zz99zz99",
|
|
507
|
+
"env": "prod",
|
|
508
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
509
|
+
"token": "fXk9Qw2pT0a:APA91bExampleTokenExampleTokenExampleTokenExampleToken1234567890",
|
|
510
|
+
"platform": "android",
|
|
511
|
+
"app_version": "1.0.0",
|
|
512
|
+
"sdk_version": "1.0.0",
|
|
513
|
+
"enabled": true,
|
|
514
|
+
"user_id": null,
|
|
515
|
+
"tags": []
|
|
516
|
+
},
|
|
517
|
+
"response": {
|
|
518
|
+
"code": "NOT_FOUND",
|
|
519
|
+
"message": "project or environment not found",
|
|
520
|
+
"data": {},
|
|
521
|
+
"extra": {}
|
|
522
|
+
},
|
|
523
|
+
"expect_sdk_last_error": "NOT_FOUND"
|
|
524
|
+
},
|
|
525
|
+
{
|
|
526
|
+
"name": "register_invalid_tags",
|
|
527
|
+
"endpoint": "register",
|
|
528
|
+
"request_delta": {
|
|
529
|
+
"tags": [
|
|
530
|
+
"a",
|
|
531
|
+
"b",
|
|
532
|
+
"c",
|
|
533
|
+
"d",
|
|
534
|
+
"e",
|
|
535
|
+
"f",
|
|
536
|
+
"g",
|
|
537
|
+
"h",
|
|
538
|
+
"i",
|
|
539
|
+
"j",
|
|
540
|
+
"k"
|
|
541
|
+
]
|
|
542
|
+
},
|
|
543
|
+
"response": {
|
|
544
|
+
"code": "INVALID_REQUEST",
|
|
545
|
+
"message": "tags exceeds 10 items",
|
|
546
|
+
"data": {},
|
|
547
|
+
"extra": {}
|
|
548
|
+
},
|
|
549
|
+
"expect_sdk": "SDK 本地先拒绝(INVALID_ARGUMENT,不发请求);本例只用于服务端侧校验测试"
|
|
550
|
+
},
|
|
551
|
+
{
|
|
552
|
+
"name": "register_invalid_token_charset",
|
|
553
|
+
"endpoint": "register",
|
|
554
|
+
"request_delta": {
|
|
555
|
+
"token": "bad token with spaces and ✓ chars that is definitely long enough to pass length"
|
|
556
|
+
},
|
|
557
|
+
"response": {
|
|
558
|
+
"code": "INVALID_REQUEST",
|
|
559
|
+
"message": "token has invalid characters",
|
|
560
|
+
"data": {},
|
|
561
|
+
"extra": {}
|
|
562
|
+
},
|
|
563
|
+
"expect_sdk": "服务端侧校验向量:SDK 本地只做 no_control + 长度校验,本例由服务端回 INVALID_REQUEST(FCM token 恒在字母表内,实际不会发生)"
|
|
564
|
+
},
|
|
565
|
+
{
|
|
566
|
+
"name": "opened_receipt",
|
|
567
|
+
"endpoint": "opened",
|
|
568
|
+
"request": {
|
|
569
|
+
"spid": "ab12cd34",
|
|
570
|
+
"env": "prod",
|
|
571
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
572
|
+
"message_id": "pm_7f3a9c2e41b0"
|
|
573
|
+
},
|
|
574
|
+
"response": {
|
|
575
|
+
"code": "SUCCESS",
|
|
576
|
+
"message": "",
|
|
577
|
+
"data": {
|
|
578
|
+
"click_type": "open_url",
|
|
579
|
+
"url": "https://demo.example.com/promo/1111"
|
|
580
|
+
},
|
|
581
|
+
"extra": {}
|
|
582
|
+
},
|
|
583
|
+
"expect": "SDK 只打开 data.url(经 scheme 白名单),忽略 intent extras 的 url"
|
|
584
|
+
},
|
|
585
|
+
{
|
|
586
|
+
"name": "opened_receipt_duplicate",
|
|
587
|
+
"endpoint": "opened",
|
|
588
|
+
"request": {
|
|
589
|
+
"spid": "ab12cd34",
|
|
590
|
+
"env": "prod",
|
|
591
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
592
|
+
"message_id": "pm_7f3a9c2e41b0"
|
|
593
|
+
},
|
|
594
|
+
"response": {
|
|
595
|
+
"code": "SUCCESS",
|
|
596
|
+
"message": "",
|
|
597
|
+
"data": {
|
|
598
|
+
"click_type": "open_url",
|
|
599
|
+
"url": "https://demo.example.com/promo/1111"
|
|
600
|
+
},
|
|
601
|
+
"extra": {}
|
|
602
|
+
},
|
|
603
|
+
"expect": "幂等成功,opened 计数不重复 +1,仍返回权威 click_type/url"
|
|
604
|
+
},
|
|
605
|
+
{
|
|
606
|
+
"name": "opened_receipt_forged",
|
|
607
|
+
"endpoint": "opened",
|
|
608
|
+
"request": {
|
|
609
|
+
"spid": "ab12cd34",
|
|
610
|
+
"env": "prod",
|
|
611
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
612
|
+
"message_id": "pm_deadbeef0000"
|
|
613
|
+
},
|
|
614
|
+
"response": {
|
|
615
|
+
"code": "NOT_FOUND",
|
|
616
|
+
"message": "not found",
|
|
617
|
+
"data": {},
|
|
618
|
+
"extra": {}
|
|
619
|
+
},
|
|
620
|
+
"expect_sdk": "只拉起主 Activity;不回调 onOpened、不投递 push.opened、不写 lastOpened、不上报 $push_open;SLogger.e 一条"
|
|
621
|
+
},
|
|
622
|
+
{
|
|
623
|
+
"name": "opened_receipt_open_app",
|
|
624
|
+
"endpoint": "opened",
|
|
625
|
+
"request": {
|
|
626
|
+
"spid": "ab12cd34",
|
|
627
|
+
"env": "staging",
|
|
628
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
629
|
+
"message_id": "pm_0a1b2c3d4e5f"
|
|
630
|
+
},
|
|
631
|
+
"response": {
|
|
632
|
+
"code": "SUCCESS",
|
|
633
|
+
"message": "",
|
|
634
|
+
"data": {
|
|
635
|
+
"click_type": "open_app"
|
|
636
|
+
},
|
|
637
|
+
"extra": {}
|
|
638
|
+
},
|
|
639
|
+
"expect_sdk": "回调/上报照做;只拉起主 Activity"
|
|
640
|
+
},
|
|
641
|
+
{
|
|
642
|
+
"name": "opened_receipt_unknown_message",
|
|
643
|
+
"endpoint": "opened",
|
|
644
|
+
"request": {
|
|
645
|
+
"spid": "ab12cd34",
|
|
646
|
+
"env": "prod",
|
|
647
|
+
"device_id": "d8f3a1c2-9b7e-4f10-a6c5-3e2d1f0b9a87",
|
|
648
|
+
"message_id": "pm_ffffffffffff"
|
|
649
|
+
},
|
|
650
|
+
"response": {
|
|
651
|
+
"code": "NOT_FOUND",
|
|
652
|
+
"message": "not found",
|
|
653
|
+
"data": {},
|
|
654
|
+
"extra": {}
|
|
655
|
+
},
|
|
656
|
+
"expect": "未命中(未知 message / 他环境 / 无投递行 / 不可打开 / 超 7 天):HTTP 200 + NOT_FOUND,与 spid/env 未知同一信封,无副作用",
|
|
657
|
+
"expect_sdk": "同 opened_receipt_forged:只拉起主 Activity;不回调、不上报"
|
|
658
|
+
}
|
|
659
|
+
],
|
|
660
|
+
"frozen_at": "2026-10-21",
|
|
661
|
+
"frozen_by": "CA-F261008030542 review R3 F18(单源收敛:SDK-F042 + CA-F038 两侧共用本文件)"
|
|
662
|
+
}
|