文档

PWA 与 Web Push

PWA 落地页是一种本地落地页,Orbitra 把它渲染成完整的 Web 应用:"应用商店"式的店面页(storefront)、manifest 和 service worker。配合 Web Push 模块,你可以在店面页上自己积累订阅者并向他们发送 push — 全部自建,不依赖外部服务(FCM 只作为 Android 的传输通道,Apple 作为 iOS 的传输通道;密钥和数据库都是你自己的)。

本文涵盖:PWA 构建器、应用安装、域名绑定、漏斗埋点、订阅者名单、消息(手动与事件驱动)、发送 cron 以及故障排查。


1. PWA 落地页:是什么、怎么工作

1.1 内部原理

1.2 构建器

Landings → Add PWA(或在已有 PWA 上"Duplicate")。编辑器的主要区块:

区块配置内容
General应用名称、slug、分组、图标与截图(经 Content Gallery)、类别、开发者、语言、版本、"更新时间"
Store描述(带 {value} 宏)、标签、评分直方图、评论、"更新内容"、徽标(认证、发光、实时计数器)、亮/暗主题、配色
Screen安装后展示的应用内屏幕:类型、标题、文本、按钮、图片、自定义 HTML/JS
Actions安装按钮的动作:去 offer / 去广告系列 / 去 URL / 不动作(action_target)、自动跳转计时器
Push在应用屏幕上开启 push 订阅(push_enabled)
Domain域名绑定(见 §2)+ 直连域名使用的 offer
Readiness原生安装卡片效果的实时清单:图标、描述、截图尺寸、push 密钥、域名绑定

Preview 按钮用生产渲染器渲染配置草稿 — 无需保存即可实时预览店面页和屏幕(auto/iOS 平台)。

1.3 漏斗与埋点

店面页会发送单像素埋点,写入点击:

这些列都显示在点击详情里 — 漏斗诊断的主要工具:原因由追踪器自己报出来,不需要看浏览器日志。

1.4 push 订阅住在 service worker 里

订阅完全在生成的 sw.js(orbitraSubscribe)内部完成:页面只是给 worker 发一条消息就前往 offer。这是有意为之 — 在 iOS 上,第一次冷启动的 pushManager.subscribe 可能要花几十秒,订阅不能依赖用户在页面上停留多久。worker 还会:

sw.js 里的 {vapid_public} 占位符在文件输出时替换,而不是生成时 — 更换 VAPID 密钥无需重新生成静态文件,已安装的应用就能拿到新密钥。

1.5 RENDERER_VERSION

渲染器每次变更都会提升 RENDERER_VERSION(core/PwaLanding.php)。下次访问落地页时,追踪器会比对渲染出的静态文件中的版本标记,自动重新生成过期的文件 — 无需手动重新上传到服务器。


2. 域名 → PWA 绑定

域名可以直接绑定到 PWA:访问 https://domain.com/ 时从根路径打开店面页,无需经过广告系列和 /lander/ — 安装 URL 干净利落。


3. Web Push:订阅库、密钥与发送

3.1 VAPID 密钥与联系方式

Push Base 页面(面板 → Push):

  1. 填写 contact(联系方式)— mailto:[email protected] 或 https://…。没有真实联系方式时密钥生成会被阻止:Apple(web.push.apple.com)会校验 JWT 里的 sub 声明,对占位地址返回 403 BadJwtToken。
  2. 点击 Generate keys。密钥保存在追踪器设置里(vapid_public_key / vapid_private_key / vapid_private_pem);加密与签名是纯 PHP + openssl(RFC 8291 + RFC 8292),不依赖 composer。
  3. 更换密钥需要确认:现有订阅随之失效,但每台设备都会在下一次打开应用时悄悄重新订阅(自愈);订阅库会自行恢复。

页面上的诊断条显示:密钥是否存在、公钥、联系方式(使用默认值会警告)、worker 最后一次 ping 的时间,以及最近的发送错误码。

3.2 "Subscribers" 标签页

push_subscriptions 表:id、click、endpoint、country、language、UA、status(active / expired)、created、last shown。功能:

订阅者会因重装和重新订阅而增多(push 服务会更换 endpoint)— 旧行在发送时收到 404/410 后自动过期,无需单独清理。群发之前,请通过订阅者的点击检查其"新鲜度"(点击详情会显示落地页和安装时的 UA)。

3.3 "Messages" 标签页

消息是群发模板。分两种:

消息字段:标题(≤250)、正文(≤400)、图标(URL,建议从 Gallery 选)、横幅图片(URL — Android Chrome 会在通知上显示为大图;iOS 会静默忽略)、点击跳转链接、segment、国家和语言定向、"active" 开关。

Segment 在入队时刻按订阅者的转化计数计算:

Segment谁会收到
all所有活跃订阅者
reg0尚未注册的人
reg1dep0已注册但未入金
reg1dep1已注册且已入金

定向(migration 60)在入队时进一步收窄任意 segment:countries — 逗号分隔的 ISO 代码列表,与订阅者的 geo 比对(US, DE);languages — 两位浏览器语言代码,按主子标签匹配(en 能匹配存为 en-US 的订阅者)。空列表 = 不限制。垃圾条目在保存时即被丢弃,绝不入库。

正文支持发送时展开的宏:{variant1|variant2}(随机选择,嵌套 ≤10 层)、{Random=(X,Y)}、{subid} 及其他点击宏 — 一条消息让每个收件人拿到自己的文本。

3.3.1 Push 点击与消息 CTR

SW 展示的每条通知都在其 data 里带有送达 ID(subid、message_id、sid)。点按通知会在导航之前发出一个埋点(/pixel.gif?action=pwa&kind=pushclick),因此即使浏览器立即离开前往 offer,这次点击也会被计数:

3.3.2 退订

通知本身带一个 Unsubscribe(退订)动作按钮(本地化,内置于落地页的 SW;iOS 忽略动作按钮 — 在那里点按通知仍会打开)。按下后,浏览器的 endpoint 会 POST 到公开的 /push_unsubscribe 入口,把 is_active 置为 0(幂等;密钥保留,面板可以重新激活)。另有独立的公开页面 /push-unsubscribe?endpoint=<urlencoded> — 它渲染一个确认按钮(退订是按钮背后的 POST,所以预取的链接绝不会退订任何人),可以从任何地方链接过去。

生成的 SW 还为导航失败提供专门的离线页(本地化,带 Retry 按钮),而不是陈旧的缓存店面页 — 缓存的商店页会发出过期点击 ID 的埋点,其 CTA 在离线状态下也无法工作。

3.4 发送:队列与 cron

面板本身不发送任何东西。消息行上的 "Send now" 按钮把 segment 内每个活跃订阅者各入队一条(push_queue),带去重保护,并返回"Queued: N"。

实际送达由 cron worker cli/push_cron.php 完成 — 每分钟运行:

* * * * * www-data php /var/www/orbitra/cli/push_cron.php --quiet >> /var/www/orbitra/var/logs/push.log 2>&1

这一行由 install.sh 自动安装(标记 # orbitra-push);检查:crontab -u www-data -l | grep orbitra-push。worker 的行为:用 flock 防止并行运行,每批 ≤300,300 秒后重试,429 遵守 Retry-After,401/403 — 用新 JWT 重试一次,404/410 — 订阅过期,5xx/网络错误 — 重新入队。事件消息也由同一个 worker 通过设置里的游标触发。

队列健康状况显示在消息列表上方的条带里:pending/done/failed 数量和 worker 最后一次 ping 的时间。如果 ping 不再跳动 — 说明 cron 没装或没在运行,发送就不会发生。

3.5 "已发送"意味着什么

push 服务返回 201 的含义是"信封已接收",不是已送达。 push 服务无法破解加密(端到端):它返回 201,如果设备从不读取,消息就被静默丢弃。最终的裁判只有手机。一条可监测的验证链:

  1. Push Base → Subscribers → 行上的 Send → "已接收"横幅;
  2. 设备上:下拉通知栏(应用开着的时候,横幅通知可能已静默滑过);
  3. 如果 201 却毫无动静 — 见 §4。

4. 故障排查与常见问题

完全没有订阅 — 看点击详情:push_fail_reason 会报出原因(unsupported = 没有 Push API — iOS 上的 Telegram/Chrome webview;insecure = 没有 HTTPS;nokey = 未配置 VAPID;denied = 用户拒绝;timeout = 网络慢 — 下次打开应用时会通过自愈补上订阅)。

iOS — 只支持 Safari,且只能从主屏幕。 iOS 上的 Web push 需要满足:iOS ≥ 16.4、应用专门从 Safari 添加到主屏幕(普通 Safari 里没有 Notification 对象 — 订阅永远不会创建)、域名持有正规的公网证书。从 Chrome (CriOS) 添加到主屏幕的应用没有 push 保证:在点击详情里通过 UA 检查安装时的浏览器(CriOS/… = Chrome,Version/… = Safari)。不工作的话 — 从 Safari 重新添加图标。

发送时 403 BadJwtToken — VAPID 联系方式无效:Apple 拒绝占位地址(mailto:orbitra@localhost)。请填写真实的 mailto:。

返回 201 但所有人都收不到 — 检查服务器是否为最新版本(用 sudo -u www-data 执行 git log --oneline -1):早期构建存在加密信封缺陷(头部缺 keyid、密钥调度不符合 RFC 8291),服务仍会以 201 接受。然后做一个对照实验:桌面 Chrome → 安装 PWA → Allow → 发送:如果桌面能收到而 iPhone 收不到 — 问题在设备/通道(VPN 会破坏 APNs 持久连接;Chrome 的安装);如果桌面也收不到 — 带上诊断条里的错误码联系支持。

面板更新后"按钮点不动" — 几乎都是浏览器缓存了旧的 index.html:强制刷新(Cmd+Shift+R)或开个隐私标签页。

cron 静默 — push_cron_last_ping_at 不再跳动:cron 没有安装。crontab -u www-data -l | grep orbitra-push;日志在 var/logs/push.log。


5. 测试

离开应用内浏览器(renderer v19+)

PWA 无法在 FB/IG/TikTok 的 webview 里安装 — webview 里的每次访问都是注定的漏斗流失。开启 Auto-open in browser(默认开启)后,落地页立即离开:Android 经 intent:// 进入 Chrome(以当前 URL 兜底),iOS 17+ 经 x-safari-https://;更老的 iOS 保留指引卡片。逃逸 URL 带着点击 ID,外部浏览器延续同一次点击 — 没有第二次点击,漏斗不被拆散。PWA 漏斗卡片显示尝试次数和成功率(成功回到真实浏览器)。只有盈利侧才会逃逸:安全页继续输出安全内容。

送达与转化归因

push 文本中的 offer 宏

{offer.value} / {offer.value1} / {offer.value2} 从 offer 的分国家表格(国家 → 奖金 / freespins / 币种;国家留空 = 通用兜底)按订阅者所在国家解析,经由订阅点击所去的那个 offer。消息编辑器支持对所选国家 + offer 的实时预览。缺少上下文时宏保持原样可见 — 绝不会静默变成空白。

按订阅者的当地时间发送

订阅保存设备的 IANA 时区(旧行:从 geo 国家推导)。勾选 Send at subscriber's local time 的消息会避开免打扰时段 — 默认为当地 23:00–08:00(push_quiet_hours)— 并在第一个允许的分钟发送。重新入队会让该行保持 pending(last_code=quiet),它绝不会失败。

运营者自己的 push 通知(面板 PWA)

以上讲的都是发给落地页订阅者的 push。面板本身也是一个 PWA(可从浏览器安装),Users & Profile → Profile → Push notifications 让运营者在自己的设备上接收 web push — 转化提醒和日/周/月摘要 — 无需 Telegram。

Telegram 周/月摘要(migration 70)

管理员机器人的每日摘要在 Notifications 页面 → Telegram 里多了两个兄弟:每周(上一个完整自然周,周一发送)和每月(上一个完整自然月,1 日发送);只有发送时间可配置。所有 Telegram 时间 — 包括每日 — 都按第一位管理员资料的时区读取,而不是服务器时间。按聊天的开关对应机器人的 /weekly on|off 和 /monthly on|off 命令;每个周期只发一次由 tg_digest_log(唯一的聊天 × 周期 × 时间窗)锁定。合计数字来自与 push 摘要相同的 AdminPushNotify::digestWindow()/windowStats() 辅助函数,因此 Telegram 和 push 的数字永远不会打架。

← 上一篇
落地页(参考文档)
下一篇 →
PWA 漏斗
在 GitHub 上查看源码: github.com/fenjo26/Orbitra.link/wiki
全部教程
文档

快速上手

从裸机服务器到第一条转化的九个步骤:安装、首次登录、域名、联盟与 offer、流量来源、广告系列、验证、消耗与统计。

阅读教程 →
文档

安装与更新

系统要求、一条命令的安装器、PHP 更新与安全公告、按 IP 访问后台、更新完整性校验,以及本地开发环境。

阅读教程 →
文档

从 Keitaro 迁移

通过 SQL dump 把设置从 Keitaro 迁到 Orbitra:迁移内容清单、导出脚本、导入步骤,以及导入后要检查的事项。

阅读教程 →
文档

从 Binom 迁移

通过 Binom v2 Public API 直接导入广告系列、offer、流等设置 — 无需 dump 文件,附字段映射说明。

阅读教程 →
文档

功能总览

所有功能一览:流量与方案、postback 与消耗、数据分析、基础设施与管理 — 每项都链接到详细页面,并附各版本的新增内容。

阅读教程 →
文档

广告系列与流

广告系列编辑器详解:设置标签页、计费模式、流类型与全部过滤器、方案、自动优化轮询、测试链接与重复点击防护。

阅读教程 →
文档

斗篷(参考文档)

斗篷完整参考:流设置、检测层、灵敏度、定向过滤器、JavaScript 验证、全局设置、判定结果与原因代码及诊断方法。

阅读教程 →
文档

浏览器检查

通过浏览器自报矛盾识别机器人、审核员虚拟机、模拟器和反检测浏览器:四种模式、特征清单、结果查看与安全启用步骤。

阅读教程 →
文档

落地页(参考文档)

落地页完整参考:本地、跳转、Preload 与 Action 四种类型,{offer} 宏、subid 传递、停留时长、JS adapter、PHP 落地页与故障排查。

阅读教程 →
文档

PWA 与 Web Push

PWA 落地页与自建 Web Push:构建器、域名绑定、VAPID 密钥、订阅者、消息与发送 cron、转化归因和故障排查。

阅读教程 →
文档

PWA 漏斗

PWA 落地页内的可配置漏斗:store/screen/instructions/push 步骤类型、逐屏追踪、统计维度与编辑器用法。

阅读教程 →
文档

转化弹窗(Conversion Popups)

在落地页上展示带 offer 按钮的弹窗:适用场景、Popup 标签页设置、触发条件与统计指标。

阅读教程 →
文档

会话录制与热力图

像视频一样回放真实访问,配合点击热力图与滚动图;含整站录制、Cookie 同意、存储上限与隐私说明。

阅读教程 →
文档

素材库完整参考

Gallery 页面、上传与软删除、MediaPicker 的尺寸契约(sizeContract)、格式与大小限制,以及视频支持。

阅读教程 →
文档

创意库

平台同步的创意与手动上传的草稿统一存放,自动绑定花费/收入/ROI,找出真正赚钱的创意。

阅读教程 →
文档

外部 PWA 与 Telegram 频道

把第三方 PWA 构建器接入流做 A/B,并把 Telegram 频道当作可归因的 offer 目的地。

阅读教程 →
文档

Postback 与转化

入站 postback 参数与状态映射、转化类型、出站 S2S postback、投递队列与测试器、转化导入和 Conversions API。

阅读教程 →
文档

花费(Costs)

从 Facebook、TikTok、Google Ads 和 push/pop 联盟导入花费并分摊到点击;含收入聚合器、代理佣金与排错。

阅读教程 →
文档

Push 与 Pop 联盟

接入 push/pop 联盟的花费导入与 zone 级优化:支持联盟列表、匹配规则与 Zone Killer 屏蔽烧钱 zone。

阅读教程 →
文档

Facebook / Meta

两套独立集成:从 Meta 导入广告花费,以及用 Conversions API 服务端发送转化事件,含浏览器匹配与排错。

阅读教程 →
文档

Dolphin / Fbtool

通过 Dolphin(Fbtool)API 实时接收 Facebook 消耗:兼容 Keitaro 的入站端点、API 密钥与活动参数配置、消耗分摊与验证。

阅读教程 →
文档

FB 评论清理器

按计划批量审核 Facebook 广告贴下的评论:停用词、正则、链接与联系方式规则,默认 dry-run、默认隐藏、操作可恢复。

阅读教程 →
文档

流量来源与联盟

配置漏斗两端的两个目录:约 200 个流量来源模板与约 440 个联盟模板,参数三元组、postback URL 与 offer 参数宏。

阅读教程 →
文档

报表、日志与指标

仪表盘、报表生成器、趋势与群组、流量日志与点击卡片,以及每个指标的计算方式。

阅读教程 →
文档

域名与 SSL

添加域名、把 DNS 指向服务器、自动签发 Let's Encrypt 证书,以及 Domains 页面上每个开关的作用。

阅读教程 →
文档

Cloudflare

通过 API 接入 Cloudflare:域名自动停放 A 记录、多账号、代理(橙色云朵)与 Flexible / Full / Strict SSL 模式。

阅读教程 →
文档

管理

用户、角色与按资源授权、两步验证、API 密钥、安全设置、geo 数据库、面板更新与系统状态。

阅读教程 →
文档

Telegram 机器人

在 Telegram 里管理追踪器:转化通知、每日摘要、统计命令,以及发到频道/群组的转化提醒。

阅读教程 →
文档

MCP:追踪器里的 AI 助手

把 Claude 或任何 MCP 客户端连上 Orbitra,用大白话管理广告系列:41 个工具、远程与本地两种连接方式、API 密钥安全。

阅读教程 →