# Braze 连接

Braze connection 让您使用 [/users/track](https://www.braze.com/docs/api/endpoints/user_data/post_user_track/) API 将玩家数据直接推送到 Braze。每个触发事件都会向 Braze 发送**用户属性**与**自定义事件**，以便您根据游戏活动构建细分、触发活动并编排 Canvas 流程。

---

## 前提条件

| 要求 | 在哪里找到 |
| :--------------------- | :----------------------------------------------------------------------------------- |
| **Braze REST API Key** | Braze Dashboard → **Settings** → **API Keys**（需要 `users.track` 权限） |
| **REST Endpoint** | Braze Dashboard → **Settings** → **API Keys**（例如 `https://rest.iad-01.braze.com`） |

---

## 设置

1. 从主导航前往 **Connections**
2. 点击 **Add Connection** 并选择 **Braze**
3. 输入您的 **API Key** 与 **REST Endpoint**
4. 保存连接
5. 将其链接到 stream 并选择触发事件

---

## 用户识别

DailyPlay 通过玩家访问 stream 时传递的 URL 参数在 Braze 中识别用户。Braze 支持两种标识符类型：

| URL 参数 | Braze API 字段 | 说明 |
| :------------ | :-------------- | :---------------------------------------- |
| `braze_id` | `braze_id` | Braze 的内部用户标识符 |
| `external_id` | `external_id` | 映射到 Braze 的您系统中的用户 ID |
| `user_id` | `external_id` | 别名 — 与 `external_id` 同等对待 |

DailyPlay 按优先级检查标识符：`braze_id` → `external_id` → `user_id`。若 URL 参数中都不存在，则使用玩家的 DailyPlay `player_uuid` 作为 `external_id`。

### 示例 Stream URL

```
https://app.dailyplay.ai/stream/my-org/my-stream?external_id=usr_123
```

---

## 发送到 Braze 的属性

每个触发事件都会用以下自定义属性更新 Braze 中的用户资料：

### 顶级属性

| 属性 | 类型 | 说明 |
| :------------ | :----- | :-------------------------------------------------------- |
| `country` | string | 玩家的国家代码（自动检测） |
| `device_type` | string | 玩家使用的设备类型（例如 `mobile`、`desktop`） |

### 嵌套的 `dailyplay` 对象

所有 DailyPlay 特定属性都分组在用户资料的 `dailyplay` 对象下：

| 属性 | 类型 | 说明 |
| :------------------------------- | :----- | :-------------------------------------------------------------------------------------- |
| `dailyplay.last_game_id` | string | 最近游玩的游戏 ID |
| `dailyplay.last_stream_name` | string | 游戏所属 stream 的名称 |
| `dailyplay.last_stream_slug` | string | Stream 的 URL slug |
| `dailyplay.last_play_date` | string | 上次互动的 ISO 8601 时间戳 |
| `dailyplay.stream_<stream_slug>` | string | 为此 stream 记录的事件类型（例如 `play_complete`）— 适用于漏斗追踪 |
| `dailyplay.last_game_score` | number | 玩家分数（仅在 `play_complete` 事件上） |
| `dailyplay.last_play_duration` | number | 游玩时长（秒）（仅在 `play_complete` 事件上） |

:::tip `dailyplay.stream_<stream_slug>` 属性存储每个 stream 的最新事件类型。在 Braze 中用它构建基于旅程的细分 — 例如，定位 `dailyplay.stream_welcome_stream` 等于 `play_complete` 的用户。 :::

---

## 发送到 Braze 的自定义事件

每个触发在 Braze 中以命名模式 `dailyplay_<event_type>` 触发自定义事件：

| 事件名称 | 触发时机… |
| :--------------------------- | :--------------------------------- |
| `dailyplay_stream_access` | 玩家打开 stream 页面 |
| `dailyplay_play_start` | 玩家开始游戏 |
| `dailyplay_play_complete` | 玩家完成游戏 |
| `dailyplay_prize_redemption` | 玩家领取奖品或兑换码 |

### 事件属性

每个自定义事件包含以下属性：

| 属性 | 类型 | 说明 |
| :---------------------- | :----- | :---------------------------------------------------- |
| `game_id` | string | 游戏 ID |
| `stream_id` | number | Stream（活动）的 ID |
| `stream_name` | string | Stream 的显示名称 |
| `player_uuid` | string | DailyPlay 玩家标识符 |
| `score` | number | 玩家分数（仅在 `play_complete` 上） |
| `play_duration_seconds` | number | 完成时间（秒）（仅在 `play_complete` 上） |
| `url_<param>` | string | 任何以 `url_` 为前缀的额外 URL 参数 |

:::note 身份参数（`braze_id`、`external_id`、`user_id`）从事件属性中排除，因为它们已用于用户识别。 :::

---

## 示例载荷

以下是 DailyPlay 为 `play_complete` 事件向 Braze 发送的完整 `/users/track` 载荷：

```json
{
  "attributes": [
    {
      "external_id": "usr_123",
      "country": "US",
      "device_type": "mobile",
      "dailyplay": {
        "last_game_id": "163",
        "last_stream_name": "Summer Campaign",
        "last_stream_slug": "summer-campaign",
        "last_play_date": "2026-04-09T14:30:00.000Z",
        "stream_summer-campaign": "play_complete",
        "last_game_score": 85,
        "last_play_duration": 32
      }
    }
  ],
  "events": [
    {
      "external_id": "usr_123",
      "name": "dailyplay_play_complete",
      "time": "2026-04-09T14:30:00.000Z",
      "properties": {
        "game_id": "163",
        "stream_id": 453,
        "stream_name": "Summer Campaign",
        "player_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "score": 85,
        "play_duration_seconds": 32,
        "url_source": "email_campaign"
      }
    }
  ]
}
```

---

## 在 Braze 中的用例

- **触发式活动** — 当 `dailyplay_play_complete` 触发时发送跟进消息
- **细分** — 基于 `dailyplay.last_game_score` 或 `dailyplay.stream_<slug>` 属性构建细分
- **Canvas 流程** — 将游戏事件用作多步骤旅程中的入口触发或决策分支
- **再互动** — 定位触发了 `dailyplay_play_start` 但未触发 `dailyplay_play_complete` 的用户