4.0 KiB
外部应用入口
外部应用统一通过 /external-entry 进入本应用。当前 APP HOST：
| 环境 | APP HOST |
|---|---|
| 测试环境 | frontend-test.banlv-ai.com |
| 正式环境 | cozsweet.com |
普通模式和促销模式的可点击链接统一维护在 外部入口链接清单。
入口会先保存传入的身份数据，再使用 replace 跳转到目标页面。身份参数和入口控制参数会从地址栏中移除；目标页面自身需要的状态参数会保留，例如打赏页的 coffee_type。
如果进入时已经是 Email、Google 或 Facebook 正式登录用户，并且携带 PSID，入口会额外调用一次 Facebook Identity 绑定接口。普通启动、刷新、Guest 和未登录状态不会调用绑定接口，绑定失败也不会阻止目标页面跳转。
参数
| 参数 | 必填 | 可选值 | 说明 |
|---|---|---|---|
target |
否 | chat、tip、private-room |
最终页面，缺失或无效时进入 chat。 |
psid |
否 | string | Facebook Page-scoped User ID。 |
avatar_url |
否 | URL string | 用户头像地址。 |
coffee_type |
打赏入口可选 | small、medium、large |
target=tip 时指定咖啡档位，缺失或非法时默认为 small。 |
mode |
否 | promotion |
设置为 promotion 时尝试开启聊天促销模式。 |
promotion_type |
促销模式必填 | voice、image、private |
指定促销锁消息类型。 |
对外接入应使用表格中的公开参数及规范写法，不兼容 camelCase、旧 Facebook 字段名、redirect、next 或其他目标别名。
普通入口
进入聊天：
https://<APP_HOST>/external-entry?target=chat&psid=<PSID>
进入打赏页面（默认 Small Coffee）：
https://<APP_HOST>/external-entry?target=tip
入口会跳转到规范地址：
https://<APP_HOST>/tip?coffee_type=small
进入私密空间：
https://<APP_HOST>/external-entry?target=private-room
咖啡打赏入口
打赏入口支持三种咖啡档位：
coffee_type |
展示名称 | 价格 | 后端套餐 planId |
|---|---|---|---|
small |
Small Coffee | US$4.99 | tip_coffee_usd_4_99 |
medium |
Medium Coffee | US$9.99 | tip_coffee_usd_9_99 |
large |
Large Coffee | US$19.99 | tip_coffee_usd_19_99 |
分别进入三种咖啡打赏页面：
https://<APP_HOST>/external-entry?target=tip&coffee_type=small
https://<APP_HOST>/external-entry?target=tip&coffee_type=medium
https://<APP_HOST>/external-entry?target=tip&coffee_type=large
外部入口会将它们规范化为 /tip?coffee_type=<type>。coffee_type 会在登录、Stripe 回跳和 Ezpay 回跳期间保留，确保支付流程始终使用最初选择的咖啡档位。
实际创建订单时，前端通过 /api/payment/tip-plans 获取套餐，并只使用接口返回的对应 planId。最终支付金额以后端返回的套餐数据为准，若找不到对应套餐，页面会禁止下单，避免使用错误档位。
促销入口
促销模式只在 target=chat 时生效，并且 mode 与 promotion_type 必须同时有效。所有有效组合及其测试、正式环境链接见 外部入口链接清单。
进入聊天后，正常历史仍会加载，列表底部会额外展示一条对应类型的锁定促销消息。消息首次解锁使用前端生成的 clientLockId，真实内容、积分价格和后端 messageId 均由 /api/chat/unlock-private 返回。
促销入口只消费一次。普通刷新或主动离开聊天页后不会再次注入；登录或充值回跳会继续恢复当前解锁流程。
接入要求
- 所有参数必须使用 URL 编码，尤其是
avatar_url。 - 不要通过入口传递登录 token、Page Access Token 或 App Secret。
coffee_type仅在target=tip时生效；缺失或非法时使用small。promotion_type非法时按普通聊天入口处理，不展示促销消息。- 不支持任意 URL 跳转；无效
target固定回退到聊天页。