feat(external-entry): define Facebook business links
This commit is contained in:
Codex
@@ -1,11 +1,11 @@
|
||||
# 外部入口接入说明
|
||||
|
||||
外部应用通过 `/external-entry` 进入本应用。
|
||||
Facebook 等外部应用统一通过 `/external-entry` 进入本应用。入口先保存外部身份和短期业务意图，再跳转到对应角色页面并清理地址栏中的入口查询参数。
|
||||
|
||||
| 环境 | APP HOST |
|
||||
| --- | --- |
|
||||
| 测试环境 | `frontend-test.banlv-ai.com` |
|
||||
| 正式环境 | `cozsweet.com` |
|
||||
| 预发环境 `pre` | `frontend-test.banlv-ai.com` |
|
||||
| 正式环境 `production` | `cozsweet.com` |
|
||||
|
||||
入口格式：
|
||||
|
||||
@@ -13,85 +13,78 @@
|
||||
https://<APP_HOST>/external-entry?<参数>
|
||||
```
|
||||
|
||||
## 可选参数
|
||||
## 当前 Facebook 业务入口
|
||||
|
||||
所有参数均为可选参数。
|
||||
当前正式投放固定为 4 类入口乘以 3 个角色，共 12 条链接。Facebook 业务名称与应用页面的对应关系如下：
|
||||
|
||||
| Facebook 入口 | 参数组合 | 落地行为 |
|
||||
| --- | --- | --- |
|
||||
| 私密空间 | `target=chat` | 进入普通聊天页，不插入任何锁定内容。 |
|
||||
| 语音 | `target=chat&mode=promotion&promotion_type=voice` | 进入聊天页，并插入一条待解锁语音。 |
|
||||
| 图片包 | `target=private-zone` | 进入角色的 `private-zone` 图片空间。 |
|
||||
| 帮忙买咖啡 | `target=tip` | 进入角色的咖啡打赏页。 |
|
||||
|
||||
每条正式链接还必须显式传入：
|
||||
|
||||
- `character=elio`、`character=maya` 或 `character=nayeli`；
|
||||
- `psid=<PSID>`，其中 `<PSID>` 必须由 Facebook 发送端替换为当前用户经过 URL 编码的 Page-scoped User ID。
|
||||
|
||||
完整的 12 条正式发送模板见 [Facebook 12 条外部入口链接清单](./links.md)。
|
||||
|
||||
## 参数说明
|
||||
|
||||
| 参数 | 可选值或格式 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `target` | `chat`、`tip`、`private-zone` | 指定进入的页面；不传或值无效时进入聊天页。历史值 `private-room` 兼容进入 `private-zone`，新链接不得继续使用。 |
|
||||
| `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。 |
|
||||
| `psid` | string | 传入 Facebook Page-scoped User ID。 |
|
||||
| `target` | `chat`、`tip`、`private-zone` | 指定进入的页面；不传或值无效时进入聊天页。 |
|
||||
| `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。正式投放链接必须显式传入。 |
|
||||
| `psid` | string | Facebook Page-scoped User ID。Facebook 正式投放链接必须动态传入。 |
|
||||
| `mode` | `promotion` | 开启聊天促销模式。 |
|
||||
| `promotion_type` | `voice`、`image`、`private` | 指定促销消息类型，仅与 `mode=promotion` 一起使用。 |
|
||||
|
||||
`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。
|
||||
`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。当前 12 条正式投放链接只使用 `promotion_type=voice`；`image` 和 `private` 保留为兼容能力，不属于本次业务清单。
|
||||
|
||||
标准私密空间参数是 `target=private-zone`。前端仅为已经发布的旧链接保留 `target=private-room` 兼容；`private_zone` 等其他拼写仍按无效目标处理并回退聊天页。
|
||||
## 四类发送模板
|
||||
|
||||
发送前必须把 `<CHARACTER>` 替换为角色值，把 `<PSID>` 替换为当前 Facebook 用户的真实 PSID；不得把占位符原样发送给用户。
|
||||
|
||||
私密空间（普通聊天）：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&psid=<PSID>
|
||||
```
|
||||
|
||||
语音：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&mode=promotion&promotion_type=voice&psid=<PSID>
|
||||
```
|
||||
|
||||
图片包：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=private-zone&character=<CHARACTER>&psid=<PSID>
|
||||
```
|
||||
|
||||
帮忙买咖啡：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=tip&character=<CHARACTER>&psid=<PSID>
|
||||
```
|
||||
|
||||
## PSID 与登录状态流程
|
||||
|
||||
PSID 保存、登录状态判断和 Facebook Identity 绑定逻辑见 [PSID 与登录状态流程图](./psid-login-flow.md)。
|
||||
`psid` 可以和任意有效入口参数组合使用。应用会先保存 PSID，再执行登录状态判断和 Facebook Identity 绑定。详细流程见 [PSID 与登录状态流程图](./psid-login-flow.md)。
|
||||
|
||||
## 使用示例
|
||||
所有参数值都必须进行 URL 编码。入口中禁止传递登录 Token、Page Access Token、App Secret 或其他秘密。
|
||||
|
||||
普通聊天：
|
||||
## 兼容说明
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat
|
||||
```
|
||||
- 历史参数 `target=private-room` 继续兼容进入 `private-zone`，但不得用于新投放链接。
|
||||
- `private_zone` 等其他拼写仍按无效目标处理并回退聊天页。
|
||||
- `promotion_type=image` 和 `promotion_type=private` 继续由现有代码支持，但不计入当前 12 条 Facebook 业务链接。
|
||||
- 无效或缺失的 `character` 继续回退 Elio；正式投放模板始终显式传入角色，不能依赖回退。
|
||||
|
||||
进入 Maya 聊天：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat&character=maya
|
||||
```
|
||||
|
||||
携带 PSID 进入聊天，示例 PSID 为 `27511427698460020`：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat&psid=27511427698460020
|
||||
```
|
||||
|
||||
语音促销聊天：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=voice
|
||||
```
|
||||
|
||||
图片促销聊天：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=image
|
||||
```
|
||||
|
||||
私密文本促销聊天：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=private
|
||||
```
|
||||
|
||||
咖啡打赏：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=tip
|
||||
```
|
||||
|
||||
私密空间：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=private-zone
|
||||
```
|
||||
|
||||
进入 Nayeli 私密空间：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=private-zone&character=nayeli
|
||||
```
|
||||
|
||||
`psid` 可以与任意 `target` 或聊天促销参数组合使用。参数值需要进行 URL 编码，不要在入口中传递登录 Token、Page Access Token 或 App Secret。
|
||||
|
||||
完整可点击示例：
|
||||
## 调试与正式清单
|
||||
|
||||
- [本地调试链接清单](./debug-links.md)
|
||||
- [测试环境和正式环境链接清单](./links.md)
|
||||
- [Facebook 12 条外部入口链接清单](./links.md)
|
||||
|
||||
Reference in New Issue
Block a user