# Facebook 广告上报分析文档

## 概述
这套程序实现了多平台广告追踪系统，支持 Facebook Pixel、Google Analytics、Kwai Pixel 和 Firebase Analytics。本文档重点分析 Facebook (FB) 广告上报的实现。

## 核心文件结构

### 1. 主要文件
- `src/tracking/FacebookPixel.js` - Facebook Pixel 核心实现
- `src/tracking/TrackAll.js` - 统一的事件追踪管理器
- `src/tracking/ApkPromote.js` - APK 推广渠道处理（包含 FB 初始化）
- `src/features/mainSlice.js` - 主状态管理，包含初始化逻辑
- `src/features/actions/hallClient.js` - 支付完成等事件上报

---

## Facebook Pixel 初始化流程

### 1. 初始化入口 (`src/tracking/FacebookPixel.js`)

#### `fb_setPixelID(pixelID, ex_id)` 函数
**功能**: 初始化 Facebook Pixel

**参数获取优先级**:
1. URL 参数 `pixel` 或 `rb_pixel_id`
2. localStorage 中存储的 `pixelID`
3. 函数传入的 `pixelID` 参数

**初始化步骤**:
```javascript
// 1. 动态加载 Facebook Pixel SDK
initFbq(
    window,
    document,
    "script",
    "https://connect.facebook.net/en_US/fbevents.js"
)

// 2. 初始化 Pixel ID
if (!!ex_id) {
    window.fbq("init", pixelID, {'external_id': ex_id});
} else {
    window.fbq("init", pixelID);
}

// 3. 自动上报页面浏览
window.fbq("track", "PageView");
```

**关键特性**:
- 支持 `external_id` 参数（用户外部ID，用于用户匹配）
- Pixel ID 会保存到 localStorage，便于后续使用
- 自动触发 PageView 事件

---

### 2. 事件追踪函数

#### `fb_trackEvent(eventName, params)`
**功能**: 上报自定义事件或标准事件

**事件类型判断**:
- **标准事件**: 使用 `fbq('track', eventName, params)`
  - 支持的标准事件: `PageView`, `ViewContent`, `Search`, `AddToCart`, `AddToWishlist`, `InitiateCheckout`, `AddPaymentInfo`, `Purchase`, `Lead`, `CompleteRegistration`
- **自定义事件**: 使用 `fbq('trackCustom', eventName, params)`
  - 所有非标准事件都作为自定义事件上报

**示例**:
```javascript
// 标准事件
fb_trackEvent('Purchase', { value: 100, currency: 'USD' });

// 自定义事件
fb_trackEvent('firstpayD0', { external_id: 'user123' });
```

---

## 统一事件追踪系统 (`src/tracking/TrackAll.js`)

### 1. 初始化函数

#### `initTrackAll(pf_type, pf_id, ex_id)`
**功能**: 根据平台类型初始化对应的追踪系统

**平台类型**:
- `pf_type === "fb"` → 初始化 Facebook Pixel
- `pf_type === "kw"` → 初始化 Kwai Pixel
- `pf_type === "gg"` → 初始化 Google Analytics
- `pf_type === "apk"` → 处理 APK 推广
- `pf_type === "fire"` → 初始化 Firebase Analytics

**调用位置**:
1. `src/features/mainSlice.js:280` - 从服务器配置中获取平台信息后初始化
2. `src/tracking/ApkPromote.js:51` - APK 渠道初始化

---

### 2. 事件上报函数

#### `trackEvent(eventName, params)`
**功能**: 统一的事件上报接口，根据当前平台类型自动路由到对应的追踪系统

**Facebook 平台特殊处理**:

##### 1. 支付事件 (`eventName === "pay"`)
```javascript
if (pf_type === 'fb') {
    let data = params;
    
    // 首次支付 (first === true)
    if (data.first) {
        // D0 首充（当天首次充值）
        if (!!data.isd0) {
            fb_trackEvent("firstpayD0", { external_id: data.udid });
            fb_trackEvent('AddToWishlist', {
                value: data.golds,
                currency: global.currency,
                external_id: data.udid
            });
        }
        // D1 首充（首次充值）
        fb_trackEvent("firstpayD1", { external_id: data.udid });
        fb_trackEvent('AddToCart', {
            value: data.golds,
            currency: global.currency,
            external_id: data.udid
        });
    } 
    // 复充（非首次且非D0）
    else if (!data.isd0) {
        fb_trackEvent("payagain", { external_id: data.udid });
        fb_trackEvent('InitiateCheckout', {
            value: data.golds,
            currency: global.currency,
            external_id: data.udid
        });
    }
    
    // 所有支付都会上报 Purchase 事件
    fb_trackEvent('Purchase', {
        value: data.golds,
        currency: global.currency,
        external_id: data.udid
    });
}
```

**支付事件上报逻辑**:
- **firstpayD0**: 当天首次充值（D0）
- **firstpayD1**: 首次充值（D1）
- **payagain**: 复充（非首次且非D0）
- **Purchase**: 所有支付都会上报的标准事件
- **AddToCart**: 首次支付时上报
- **AddToWishlist**: D0首充时上报
- **InitiateCheckout**: 复充时上报

**参数说明**:
- `data.golds`: 充值金额
- `data.udid`: 用户唯一标识（用于 external_id）
- `data.first`: 是否首次支付
- `data.isd0`: 是否当天首次充值
- `global.currency`: 货币类型（如 'USD', 'BRL'）

##### 2. 注册完成事件 (`eventName === "CompleteRegistration"`)
```javascript
if (eventName === "CompleteRegistration") {
    fb_trackEvent('CompleteRegistration', { external_id: params.udid });
}
```

##### 3. 其他事件
直接透传给 `fb_trackEvent`

---

## 事件触发位置

### 1. 支付完成事件 (`src/features/actions/hallClient.js`)
```javascript
// 在 handlePayFinish 函数中
case "pay_finish": {
    let { data } = message;
    if (!!data && !!data.event) {
        trackEvent("pay", data.params);
    }
    break;
}
```

**触发时机**: 服务器通过 WebSocket 发送 `pay_finish` 消息时

**数据来源**: 服务器返回的 `data.params` 包含:
- `golds`: 充值金额
- `udid`: 用户ID
- `first`: 是否首次支付
- `isd0`: 是否当天首次充值
- `order_sn`: 订单号

---

### 2. 注册完成事件 (`src/features/mainSlice.js`)
```javascript
// 在 parseLogin 函数中
if (!!data.reg) {
    // 新注册的用户
    trackEvent("CompleteRegistration", { external_id: data.UserID })
}
```

**触发时机**: 用户登录时，如果 `data.reg` 为真，表示是新注册用户

---

### 3. 服务器主动触发事件 (`src/features/actions/hallClient.js`)
```javascript
case "call_client": {
    if (!!message.data && !!message.data.type) {
        let { data } = message;
        switch (message.data.type) {
            case "track": {
                trackEvent(data.event, data.params)
                break;
            }
        }
    }
    break;
}
```

**触发时机**: 服务器通过 WebSocket 主动调用客户端接口，类型为 `track` 时

---

## 平台配置获取

### 配置来源 (`src/features/mainSlice.js`)
```javascript
// 从服务器返回的配置中获取
let conf = json.conf;
if (!!conf.pf && !!conf.pf.id) {
    let { type, id } = conf.pf;
    initTrackAll(type, id, isLogin ? userInfo.UserID : null)
}
```

**配置结构**:
```javascript
conf.pf = {
    type: "fb",  // 平台类型
    id: "123456789"  // Pixel ID
}
```

**external_id**: 如果用户已登录，使用 `userInfo.UserID` 作为 `external_id`

---

## APK 推广渠道处理 (`src/tracking/ApkPromote.js`)

### `loadInfoNew(us, userid)` 函数
**功能**: 处理 APK 推广渠道，从服务器获取用户信息和 Pixel 配置

**流程**:
1. 调用 API 获取用户信息
2. 设置 Cookie（如果服务器返回）
3. 判断用户类型（`user.isfb()`）
4. 如果是 Facebook 渠道，初始化 Facebook Pixel

```javascript
if(user.isfb()){
    global.pf.type="fb"
    initTrackAll('fb', user.params.pixel, userid)
}
```

---

## 关键配置和存储

### 1. Pixel ID 存储
- **位置**: `localStorage.getItem("pixelID")`
- **设置**: `localStorage.setItem("pixelID", pixelID)`

### 2. 平台类型存储
- **位置**: `global.pf.type`
- **用途**: 判断当前使用的追踪平台

### 3. 用户信息存储
- **位置**: `localStorage.getItem("user")`
- **包含**: `params.pixel`, `params.fbclid`, `params.gclid` 等

---

## 标准事件列表

Facebook Pixel 支持的标准事件（在 `FacebookPixel.js` 中定义）:
1. `PageView` - 页面浏览（自动触发）
2. `ViewContent` - 查看内容
3. `Search` - 搜索
4. `AddToCart` - 加入购物车
5. `AddToWishlist` - 加入愿望清单
6. `InitiateCheckout` - 发起结账
7. `AddPaymentInfo` - 添加支付信息
8. `Purchase` - 购买
9. `Lead` - 潜在客户
10. `CompleteRegistration` - 完成注册

---

## 自定义事件

程序中使用的自定义事件:
1. `firstpayD0` - 当天首次充值
2. `firstpayD1` - 首次充值
3. `payagain` - 复充
4. `InstallPWA` - 安装 PWA（通过 `installready` 事件触发）

---

## 数据上报参数说明

### 通用参数
- `external_id`: 用户外部ID，用于用户匹配（通常是 `UserID` 或 `udid`）
- `value`: 金额数值
- `currency`: 货币类型（如 'USD', 'BRL'）

### 支付事件参数
```javascript
{
    golds: 100,           // 充值金额
    udid: "user123",      // 用户唯一标识
    first: true,          // 是否首次支付
    isd0: false,          // 是否当天首次充值
    order_sn: "ORD123"    // 订单号
}
```

---

## 注意事项

1. **Pixel ID 优先级**: URL 参数 > localStorage > 函数参数
2. **external_id**: 用于用户匹配，建议使用用户唯一标识
3. **事件上报**: 所有事件都会检查 `window.fbq` 是否存在，避免未初始化时报错
4. **平台切换**: 通过 `global.pf.type` 判断当前平台，支持多平台切换
5. **错误处理**: `initTrackAll` 使用 try-catch 包裹，避免初始化失败影响主流程

---

## 总结

这套 Facebook 广告上报系统实现了:
1. ? 灵活的 Pixel ID 配置（URL参数、localStorage、服务器配置）
2. ? 标准事件和自定义事件支持
3. ? 支付流程的完整追踪（首充、复充、D0/D1）
4. ? 用户注册完成追踪
5. ? 服务器主动触发事件支持
6. ? 多平台支持（FB、Google、Kwai、Firebase）
7. ? 用户ID匹配（external_id）

整个系统设计合理，支持多渠道推广和精细化事件追踪。