185 lines
5.8 KiB
Markdown
185 lines
5.8 KiB
Markdown
# Crisp Chat 功能修复总结（支持多平台）
|
||
|
||
## 问题描述
|
||
Crisp 客服聊天功能无法使用，原因是：
|
||
1. `crisp_sdk` 包被注释掉（依赖 `flutter_inappwebview` 有问题）
|
||
2. 所有 Crisp 相关代码被注释
|
||
3. 用户界面显示"客服功能暂时不可用"
|
||
4. `crisp_chat` 包只支持 iOS/Android，不支持桌面平台
|
||
|
||
## 解决方案
|
||
|
||
### 1. 依赖更新
|
||
**文件**: `pubspec.yaml`
|
||
|
||
- 移除了有问题的 `crisp_sdk` 包
|
||
- 添加了 `crisp_chat: ^2.4.1`（使用原生实现，不依赖 `flutter_inappwebview`）
|
||
|
||
```yaml
|
||
crisp_chat: ^2.4.1 # 使用原生实现的 crisp_chat，不依赖 flutter_inappwebview
|
||
```
|
||
|
||
### 2. 控制器重写（支持多平台）
|
||
**文件**: `lib/app/modules/kr_crisp_chat/controllers/kr_crisp_controller.dart`
|
||
|
||
- 完全重写了控制器以支持多平台
|
||
- **移动平台（iOS/Android）**:
|
||
- 使用 `crisp_chat` 包的原生 API
|
||
- 使用 `CrispConfig` 配置 Crisp
|
||
- 使用 `FlutterCrispChat.openCrispChat()` 打开聊天窗口
|
||
- 使用 `FlutterCrispChat.setSessionString()` 设置会话数据
|
||
- **桌面平台（macOS/Windows/Linux）**:
|
||
- 使用 WebView 加载 Crisp 官方嵌入脚本
|
||
- 动态生成包含 Crisp SDK 的 HTML 页面
|
||
- 通过 JavaScript 设置用户信息和会话数据
|
||
- 自动打开聊天窗口
|
||
|
||
**主要改进**:
|
||
- ✅ 支持所有平台（iOS、Android、macOS、Windows、Linux）
|
||
- ✅ 自动检测平台并选择合适的实现方式
|
||
- ✅ 支持用户邮箱和昵称设置
|
||
- ✅ 自动收集平台信息
|
||
- ✅ 设置语言、应用版本、设备 ID 等会话数据
|
||
|
||
### 3. 视图重写（多平台支持）
|
||
**文件**: `lib/app/modules/kr_crisp_chat/views/kr_crisp_view.dart`
|
||
|
||
- 移除了占位视图
|
||
- **移动平台**: 初始化成功后自动打开 Crisp 原生聊天窗口，窗口关闭后返回
|
||
- **桌面平台**: 使用 `webview_flutter` 在应用内显示 Crisp 聊天界面
|
||
- 添加了错误处理和重试功能
|
||
- 使用 `PopScope` 替代已弃用的 `WillPopScope`
|
||
- 移除了 `setBackgroundColor` 调用（macOS 不支持）
|
||
|
||
### 4. iOS 配置更新
|
||
**文件**: `ios/Runner/Info.plist`
|
||
|
||
添加了 Crisp 所需的权限：
|
||
```xml
|
||
<key>NSCameraUsageDescription</key>
|
||
<string>需要相机权限以支持拍照功能</string>
|
||
<key>NSMicrophoneUsageDescription</key>
|
||
<string>需要麦克风权限以支持语音消息功能</string>
|
||
<key>NSPhotoLibraryUsageDescription</key>
|
||
<string>需要相册权限以支持图片上传功能</string>
|
||
<key>NSPhotoLibraryAddUsageDescription</key>
|
||
<string>需要相册添加权限以保存图片</string>
|
||
```
|
||
|
||
### 5. Android 配置
|
||
**文件**: `android/app/build.gradle`
|
||
|
||
- ✅ `compileSdk 36` - 已满足要求（需要 35 或更高）
|
||
- ✅ 网络权限已在 `AndroidManifest.xml` 中配置
|
||
|
||
## 技术细节
|
||
|
||
### crisp_chat vs crisp_sdk
|
||
| 特性 | crisp_chat | crisp_sdk |
|
||
|------|-----------|-----------|
|
||
| 实现方式 | 原生 SDK | WebView |
|
||
| 依赖 | 无额外依赖 | 需要 flutter_inappwebview |
|
||
| 性能 | 更好 | 较慢 |
|
||
| 兼容性 | 更好 | 依赖问题 |
|
||
| 最新版本 | 2.4.1 (2025) | 1.1.0 (2024) |
|
||
|
||
### API 使用示例
|
||
|
||
```dart
|
||
// 创建配置
|
||
final config = CrispConfig(
|
||
websiteID: 'your-website-id',
|
||
enableNotifications: true,
|
||
user: User(
|
||
email: 'user@example.com',
|
||
nickName: 'User Name',
|
||
),
|
||
);
|
||
|
||
// 打开聊天窗口
|
||
await FlutterCrispChat.openCrispChat(config: config);
|
||
|
||
// 设置会话数据
|
||
FlutterCrispChat.setSessionString(key: 'platform', value: 'android');
|
||
|
||
// 重置会话
|
||
await FlutterCrispChat.resetCrispChatSession();
|
||
```
|
||
|
||
## 工作流程
|
||
|
||
1. 用户点击客服按钮
|
||
2. 进入 `KRCrispView` 页面
|
||
3. `KRCrispController` 初始化：
|
||
- 获取用户信息（邮箱/设备ID）
|
||
- 创建 `CrispConfig`
|
||
- 设置会话数据
|
||
4. 初始化完成后自动调用 `openCrispChat()`
|
||
5. 显示原生 Crisp 聊天界面
|
||
6. 用户关闭聊天后，自动返回上一页
|
||
|
||
## 测试建议
|
||
|
||
### 前置条件
|
||
1. 确保 `AppConfig.kr_website_id` 配置了有效的 Crisp Website ID
|
||
2. 在 Crisp 控制台配置网站设置
|
||
|
||
### 测试步骤
|
||
1. **基础功能测试**
|
||
- 打开应用
|
||
- 进入"我的"页面
|
||
- 点击"客服"按钮
|
||
- 验证 Crisp 聊天窗口是否正确打开
|
||
|
||
2. **用户信息测试**
|
||
- 登录用户状态下，验证用户邮箱是否正确传递
|
||
- 未登录状态下，验证设备 ID 是否正确使用
|
||
|
||
3. **会话数据测试**
|
||
- 在 Crisp 控制台查看会话数据
|
||
- 验证平台、语言、设备 ID 等信息是否正确
|
||
|
||
4. **权限测试 (iOS)**
|
||
- 测试相机权限提示
|
||
- 测试麦克风权限提示
|
||
- 测试相册权限提示
|
||
|
||
5. **跨平台测试**
|
||
- Android 设备测试
|
||
- iOS 设备测试
|
||
- Windows/macOS 桌面测试（如果支持）
|
||
|
||
## 注意事项
|
||
|
||
1. **Website ID 配置**
|
||
- 确保在 `AppConfig` 中配置了正确的 Crisp Website ID
|
||
- 可以从 Crisp 控制台获取：Settings → Website Settings → Website ID
|
||
|
||
2. **推送通知**
|
||
- 如需启用推送通知，需要额外配置 Firebase
|
||
- 参考 `crisp_chat` 包文档进行配置
|
||
|
||
3. **语言支持**
|
||
- Crisp 支持多语言
|
||
- 当前实现会根据应用语言自动设置（zh、zh-tw、en 等）
|
||
|
||
4. **隐私合规**
|
||
- 确保在隐私政策中说明使用 Crisp 客服系统
|
||
- 告知用户会话数据的收集和使用
|
||
|
||
## 相关文件
|
||
|
||
- `pubspec.yaml` - 依赖配置
|
||
- `lib/app/modules/kr_crisp_chat/controllers/kr_crisp_controller.dart` - 控制器
|
||
- `lib/app/modules/kr_crisp_chat/views/kr_crisp_view.dart` - 视图
|
||
- `lib/app/modules/kr_crisp_chat/bindings/kr_crisp_binding.dart` - 绑定
|
||
- `ios/Runner/Info.plist` - iOS 权限配置
|
||
- `android/app/build.gradle` - Android 编译配置
|
||
|
||
## 参考链接
|
||
|
||
- [crisp_chat 包文档](https://pub.dev/packages/crisp_chat)
|
||
- [Crisp 官方文档](https://docs.crisp.chat/)
|
||
- [Crisp iOS SDK](https://github.com/crisp-im/crisp-sdk-ios)
|
||
- [Crisp Android SDK](https://github.com/crisp-im/crisp-sdk-android)
|