docs(external-entry): add detailed documentation for external entry integration and PSID flow
This commit is contained in:
@@ -0,0 +1,79 @@
|
||||
# 外部入口接入说明
|
||||
|
||||
外部应用通过 `/external-entry` 进入本应用。
|
||||
|
||||
| 环境 | APP HOST |
|
||||
| --- | --- |
|
||||
| 测试环境 | `frontend-test.banlv-ai.com` |
|
||||
| 正式环境 | `cozsweet.com` |
|
||||
|
||||
入口格式：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?<参数>
|
||||
```
|
||||
|
||||
## 可选参数
|
||||
|
||||
所有参数均为可选参数。
|
||||
|
||||
| 参数 | 可选值或格式 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `target` | `chat`、`tip`、`private-room` | 指定进入的页面；不传或值无效时进入聊天页。 |
|
||||
| `psid` | string | 传入 Facebook Page-scoped User ID。 |
|
||||
| `mode` | `promotion` | 开启聊天促销模式。 |
|
||||
| `promotion_type` | `voice`、`image`、`private` | 指定促销消息类型，仅与 `mode=promotion` 一起使用。 |
|
||||
|
||||
`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。
|
||||
|
||||
## PSID 与登录状态流程
|
||||
|
||||
PSID 保存、登录状态判断和 Facebook Identity 绑定逻辑见 [PSID 与登录状态流程图](./psid-login-flow.md)。
|
||||
|
||||
## 使用示例
|
||||
|
||||
普通聊天：
|
||||
|
||||
```text
|
||||
https://<APP_HOST>/external-entry?target=chat
|
||||
```
|
||||
|
||||
携带 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-room
|
||||
```
|
||||
|
||||
`psid` 可以与任意 `target` 或聊天促销参数组合使用。参数值需要进行 URL 编码，不要在入口中传递登录 Token、Page Access Token 或 App Secret。
|
||||
|
||||
测试环境和正式环境的完整可点击示例见 [外部入口链接清单](./links.md)。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 外部入口链接清单
|
||||
|
||||
[返回外部入口接入说明](./README.md)
|
||||
|
||||
以下链接可以直接点击打开。PSID 示例统一使用 `27511427698460020`。
|
||||
|
||||
## 测试环境
|
||||
|
||||
| 入口 | 链接 |
|
||||
| --- | --- |
|
||||
| 普通聊天 | [打开普通聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat) |
|
||||
| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://frontend-test.banlv-ai.com/external-entry?target=chat&psid=27511427698460020) |
|
||||
| 语音促销 | [打开语音促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
|
||||
| 图片促销 | [打开图片促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
|
||||
| 私密文本促销 | [打开私密文本促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
|
||||
| 咖啡打赏 | [打开咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip) |
|
||||
| 私密空间 | [打开私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room) |
|
||||
|
||||
## 正式环境
|
||||
|
||||
| 入口 | 链接 |
|
||||
| --- | --- |
|
||||
| 普通聊天 | [打开普通聊天](https://cozsweet.com/external-entry?target=chat) |
|
||||
| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://cozsweet.com/external-entry?target=chat&psid=27511427698460020) |
|
||||
| 语音促销 | [打开语音促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
|
||||
| 图片促销 | [打开图片促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
|
||||
| 私密文本促销 | [打开私密文本促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
|
||||
| 咖啡打赏 | [打开咖啡打赏](https://cozsweet.com/external-entry?target=tip) |
|
||||
| 私密空间 | [打开私密空间](https://cozsweet.com/external-entry?target=private-room) |
|
||||
|
||||
如需在其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。
|
||||
@@ -0,0 +1,29 @@
|
||||
# PSID 与登录状态流程
|
||||
|
||||
[返回外部入口接入说明](./README.md)
|
||||
|
||||
通过 `/external-entry` 携带 PSID 进入应用时，按照以下流程保存身份信息并决定是否调用 Facebook Identity 绑定接口。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["外部链接进入 /external-entry"] --> B{"是否携带有效 PSID？"}
|
||||
B -- "是" --> C["将 PSID 保存到本地存储"]
|
||||
B -- "否" --> D["跳过 PSID 保存"]
|
||||
C --> E["等待 Auth 状态初始化完成"]
|
||||
D --> E
|
||||
E --> F{"是否为正式登录用户？"}
|
||||
F -- "否：Guest 或未登录" --> G["不调用绑定接口"]
|
||||
F -- "是：Email / Google / Facebook" --> H{"是否存在有效 PSID？"}
|
||||
H -- "否" --> G
|
||||
H -- "是" --> I["派发 Facebook Identity 绑定请求"]
|
||||
I --> J["调用绑定接口"]
|
||||
I --> K["立即跳转到 target 页面"]
|
||||
J --> L{"绑定结果"}
|
||||
L -- "成功" --> M["绑定完成"]
|
||||
L -- "失败" --> N["记录警告并保留原登录状态"]
|
||||
G --> K
|
||||
M --> O["不影响当前页面"]
|
||||
N --> O
|
||||
```
|
||||
|
||||
绑定请求不会阻塞目标页面跳转。通过外部入口进入时如果是 Guest 或未登录状态，本次入口不会调用绑定接口，之后登录也不会自动补调本次绑定。
|
||||
Reference in New Issue
Block a user