# 连接

Connections 将您的组织链接到外部平台。大多数提供方从您的游戏接收实时 webhook 事件。LINE connection 不同 — 它通过 LIFF 或 MINI App 在 LINE 内发布 streams。

**客户端**分析与广告 SDK（GA4、Mixpanel、PostHog、Amplitude、GTM、Meta Pixel）见
[分析提供商](/zh/connections/analytics-providers/) — 在 **Connect → Analytics** 下配置，不是 webhook 连接。

## 连接类型

| 类型 | 作用 | 提供方 |
| :--- | :----------- | :-------- |
| **Event webhooks** | 将游玩与奖品事件推送到您的技术栈 | Webhook、Custom、Zapier、Braze、HubSpot、Mailchimp、Salesforce、Segment |
| **Publishing** | 在即时通讯应用内打开 streams | [LINE (LIFF / MINI App)](/zh/connections/line) |
| **Client analytics** | 在 stream 页面加载浏览器 SDK | [分析提供商](/zh/connections/analytics-providers/) |

---

## 支持的提供方

| 提供方 | 说明 |
| :------------- | :----------------------------------- |
| **Webhook** | 任意带可选认证的 HTTP 端点 |
| **Custom** | 带可选 API key 的自定义 API URL |
| **Zapier** | Zapier webhook（需要 HTTPS） |
| **Braze** | Braze 消息平台 — 见 [Braze Connection](/zh/connections/braze) |
| **HubSpot** | HubSpot CRM |
| **Mailchimp** | Mailchimp 邮件营销 |
| **Salesforce** | Salesforce CRM |
| **Segment** | Segment 分析 |
| **LINE** | 通过 LIFF / MINI App 在 LINE 中发布 streams — 见 [LINE Connection](/zh/connections/line) |

---

## 事件 Webhooks 如何工作

1. **创建连接** — 在组织级别使用提供方凭据
2. **将连接链接**到一个或多个 streams（活动）
3. **选择触发事件**，决定何时触发 webhook
4. 触发事件发生时，DailyPlay 向您的端点发送带事件数据的 POST 请求

:::tip
关于 LINE 设置与永久链接，见 [LINE Connection](/zh/connections/line)。LINE 不链接到 stream 触发事件。
:::

---

## 触发事件

每个 stream 连接可配置为在以下一个或多个事件时触发：

| 事件 | 触发时机… |
| :----------------- | :--------------------------------- |
| `stream_access` | 玩家打开 stream 页面 |
| `play_start` | 玩家开始游戏 |
| `play_complete` | 玩家完成游戏 |
| `prize_redemption` | 玩家领取奖品或兑换码 |

---

## 设置 Webhook 连接

### 1. 创建连接

1. 从主导航前往 **Connections**
2. 点击 **Add Connection**
3. 选择提供方（例如 **Webhook**）
4. 输入所需凭据：
   - **Webhook / Custom** — 端点 URL 与可选授权头或 API key
   - **Zapier** — Webhook URL（必须为 HTTPS）
   - **其他提供方** — API key 及任何提供方特定字段
5. 保存连接

### 2. 链接到 Stream

1. 打开您要连接的 stream
2. 前往 **Connections** 标签
3. 从组织中选择可用连接
4. 选择应触发 webhook 的**触发事件**
5. 保存

---

## 载荷格式

触发事件发生时，DailyPlay 向您配置的端点发送 HTTP POST 请求。载荷为 JSON，包含事件、游戏与玩家的上下文。

### 示例：`play_complete` 事件

```json
{
  "event_type": "play_complete",
  "game_id": "163",
  "stream_id": 453,
  "stream_slug": "my-campaign-slug",
  "stream_name": "My Campaign Stream",
  "player_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "session_id": "s9k8j7h6-g5f4-d3c2-b1a0-123456789abc",
  "score": 85,
  "play_duration_seconds": 32,
  "url_params": {
    "user_id": "usr_123",
    "email": "player@example.com",
    "source": "email_campaign"
  },
  "timestamp": "2026-04-09T14:30:00.000Z"
}
```

### 载荷字段

| 字段 | 类型 | 说明 |
| :---------------------- | :----- | :------------------------------------------------------------------ |
| `event_type` | string | 触发事件名称（例如 `play_complete`） |
| `game_id` | string | 所玩游戏的 ID |
| `stream_id` | number | 游戏所属 stream（活动）的 ID |
| `stream_name` | string | Stream 的显示名称 |
| `player_uuid` | string | 玩家的唯一标识符 |
| `session_id` | string | 游玩会话的唯一标识符 |
| `score` | number | 玩家分数（用于 `play_complete`） |
| `play_duration_seconds` | number | 玩家完成游戏所用时间（秒） |
| `url_params` | object | 玩家访问 stream 时传递的任何 URL 查询参数 |
| `timestamp` | string | 事件发生时的 ISO 8601 时间戳 |

:::tip
`url_params` 字段捕获 stream URL 中的任何查询参数。这有助于从现有系统传递追踪 ID、用户标识符或活动标签 — 例如
`https://app.dailyplay.ai/stream/<org-slug>/my-stream?user_id=usr_123&source=email_campaign`。
:::

---

## 管理连接

- **Edit** — 从 Connections 页面更新凭据或重命名连接
- **Enable / Disable** — 切换连接开/关而不删除
- **Remove from stream** — 从特定 stream 取消链接连接，同时保持连接可供其他 streams 使用
- **Delete** — 从组织中永久移除连接

:::note
仅组织 **owners** 与 **admins** 可创建、编辑或删除连接。
:::