# Facebook Leads Integration - Perfex CRM 模块
## 项目概述
**Facebook & Instagram Leads Integration** 是一个 Perfex CRM 的模块，用于将 Facebook 和 Instagram Lead Ads 的潜在客户自动同步到 Perfex CRM 系统中。支持实时同步、多页面管理、自定义字段映射等功能。
- **版本**: v2.0.0
- **技术栈**: CodeIgniter (Perfex CRM 模块)
- **适用场景**: 数字营销、潜在客户管理、CRM 集成
---
## 技术架构
### 核心技术栈
- **框架**: CodeIgniter (作为 Perfex CRM 模块)
- **语言**: PHP
- **API**: Facebook Graph API
- **数据格式**: JSON
### 项目结构
```
facebookleadsintegration/
├── config/ # 配置文件
├── controllers/ # 控制器
│ ├── Env_ver.php # 环境验证
│ └── Facebookleadsintegration.php # 主控制器
├── core/ # 核心类
├── language/ # 语言文件
├── libraries/ # 类库
├── migrations/ # 数据库迁移
├── third_party/ # 第三方库
├── vendor/ # Composer 依赖
├── views/ # 视图模板
├── composer.json # Composer 配置
├── facebookleadsintegration.php # 模块入口
├── install.php # 安装脚本
└── lead_data.json # 示例数据
```
---
## 核心功能模块
### 1. Facebook 连接管理
- **应用连接**: 连接 Facebook 应用
- **页面授权**: 授权访问 Facebook 页面
- **多页面支持**: 管理多个 Facebook 页面
- **权限管理**: 管理 API 权限
### 2. Lead Ads 同步
- **实时同步**: Webhook 实时接收新线索
- **定时同步**: 定时任务批量同步
- **手动同步**: 手动触发同步
- **历史同步**: 同步历史线索
### 3. 字段映射 (Field Mapping)
- **默认字段**: 姓名、邮箱、电话等
- **自定义字段**: 映射 Facebook 自定义问题
- **字段转换**: 数据格式转换
- **必填字段**: 设置必填字段
### 4. 线索处理
- **自动导入**: 自动创建 Perfex CRM 线索
- **重复检测**: 检测重复线索
- **线索分配**: 自动分配给销售
- **状态设置**: 设置线索初始状态
### 5. 通知系统
- **邮件通知**: 新线索邮件通知
- **站内通知**: 系统内通知
- **管理员通知**: 通知管理员
- **销售人员通知**: 通知相关销售
### 6. 日志与报告
- **同步日志**: 记录同步操作
- **错误日志**: 记录错误信息
- **统计报告**: 同步统计报表
- **线索追踪**: 线索来源追踪
### 7. Webhook 管理
- **Webhook 配置**: 配置 Facebook Webhook
- **事件订阅**: 订阅 leads 事件
- **安全验证**: Webhook 签名验证
- **失败重试**: 失败自动重试
### 8. 后台管理
- **设置页面**: 模块配置
- **页面管理**: 管理连接的页面
- **表单管理**: 管理 Lead Ads 表单
- **同步状态**: 查看同步状态
---
## 核心业务逻辑
### 1. 首次配置流程
1. 安装模块
2. 配置 Facebook 应用
3. 授权 Facebook 页面
4. 选择要同步的页面
5. 配置字段映射
6. 启用实时同步
### 2. 线索同步流程
1. 用户在 Facebook/Instagram 提交表单
2. Facebook 发送 Webhook 通知
3. 模块接收并验证 Webhook
4. 解析线索数据
5. 检查重复性
6. 创建 Perfex CRM 线索
7. 发送通知
8. 记录日志
### 3. 手动同步流程
1. 选择页面和表单
2. 选择时间范围
3. 获取 Facebook 线索
4. 批量导入 CRM
5. 生成同步报告
---
## 技术特点
### 1. 实时同步
- Facebook Webhook 实时推送
- 即时响应新线索
- 减少线索延迟
### 2. 多页面支持
- 支持多个 Facebook 页面
- 统一管理所有页面线索
- 按页面筛选线索
### 3. 灵活映射
- 支持自定义字段映射
- 数据格式转换
- 默认值设置
### 4. 安全可靠
- Webhook 签名验证
- 数据验证和清理
- 错误处理和重试
### 5. 易于使用
- 图形化配置界面
- 一键授权
- 自动完成配置
---
## 安装要求
### 环境要求
- Perfex CRM 已安装 (v2.3+)
- PHP 7.x+
- MySQL 5.6+
- Facebook 开发者账号
### 安装步骤
1. 下载模块
2. 解压到 Perfex CRM 的 modules 目录
3. 运行安装脚本
4. 配置 Facebook 应用
5. 授权页面访问
6. 完成配置
---
## Facebook 应用配置
### 1. 创建应用
- 在 Facebook 开发者平台创建应用
- 添加 Marketing API 产品
- 配置 Webhook
### 2. 配置权限
- pages_read_engagement
- pages_manage_metadata
- leads_retrieval
### 3. 配置 Webhook
- 设置 Webhook URL
- 订阅 leads 事件
- 验证 Webhook
---
## 使用场景
### 1. 数字营销
- 收集广告线索
- 自动导入 CRM
- 快速跟进客户
### 2. 电商推广
- 收集潜在客户
- 产品咨询管理
- 促销活动报名
... (content truncated)
