# Braze Connection

The Braze connection lets you push player data directly into Braze using the
[/users/track](https://www.braze.com/docs/api/endpoints/user_data/post_user_track/) API. Every
trigger event sends both **user attributes** and a **custom event** to Braze, so you can build
segments, trigger campaigns, and orchestrate Canvas flows based on game activity.

---

## Prerequisites

| Requirement            | Where to find it                                                                     |
| :--------------------- | :----------------------------------------------------------------------------------- |
| **Braze REST API Key** | Braze Dashboard → **Settings** → **API Keys** (needs `users.track` permission)       |
| **REST Endpoint**      | Braze Dashboard → **Settings** → **API Keys** (e.g. `https://rest.iad-01.braze.com`) |

---

## Setting Up

1. Go to **Connections** from the main navigation
2. Click **Add Connection** and choose **Braze**
3. Enter your **API Key** and **REST Endpoint**
4. Save the connection
5. Link it to a stream and choose your trigger events

---

## User Identification

DailyPlay identifies users in Braze through URL parameters passed when a player accesses the stream.
Braze supports two identifier types:

| URL Parameter | Braze API Field | Description                               |
| :------------ | :-------------- | :---------------------------------------- |
| `braze_id`    | `braze_id`      | Braze's internal user identifier          |
| `external_id` | `external_id`   | Your system's user ID mapped into Braze   |
| `user_id`     | `external_id`   | Alias — treated the same as `external_id` |

DailyPlay checks for identifiers in priority order: `braze_id` → `external_id` → `user_id`. If none
are present in the URL parameters, the player's DailyPlay `player_uuid` is used as the
`external_id`.

### Example Stream URL

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

---

## Attributes Sent to Braze

Each trigger event updates the user profile in Braze with the following custom attributes:

### Top-Level Attributes

| Attribute     | Type   | Description                                               |
| :------------ | :----- | :-------------------------------------------------------- |
| `country`     | string | Player's country code (detected automatically)            |
| `device_type` | string | Device type used by the player (e.g. `mobile`, `desktop`) |

### Nested `dailyplay` Object

All DailyPlay-specific attributes are grouped under a `dailyplay` object on the user profile:

| Attribute                        | Type   | Description                                                                             |
| :------------------------------- | :----- | :-------------------------------------------------------------------------------------- |
| `dailyplay.last_game_id`         | string | ID of the most recently played game                                                     |
| `dailyplay.last_stream_name`     | string | Name of the stream the game belongs to                                                  |
| `dailyplay.last_stream_slug`     | string | URL slug of the stream                                                                  |
| `dailyplay.last_play_date`       | string | ISO 8601 timestamp of the last interaction                                              |
| `dailyplay.stream_<stream_slug>` | string | Event type recorded for this stream (e.g. `play_complete`) — useful for funnel tracking |
| `dailyplay.last_game_score`      | number | Player's score (only on `play_complete` events)                                         |
| `dailyplay.last_play_duration`   | number | Play duration in seconds (only on `play_complete` events)                               |

:::tip The `dailyplay.stream_<stream_slug>` attribute stores the latest event type per stream. Use
it in Braze to build journey-based segments — for example, target users where
`dailyplay.stream_welcome_stream` equals `play_complete`. :::

---

## Custom Events Sent to Braze

Each trigger fires a custom event in Braze with the naming pattern `dailyplay_<event_type>`:

| Event Name                   | Fires when…                        |
| :--------------------------- | :--------------------------------- |
| `dailyplay_stream_access`    | A player opens the stream page     |
| `dailyplay_play_start`       | A player starts a game             |
| `dailyplay_play_complete`    | A player finishes a game           |
| `dailyplay_prize_redemption` | A player claims a prize or voucher |

### Event Properties

Every custom event includes the following properties:

| Property                | Type   | Description                                           |
| :---------------------- | :----- | :---------------------------------------------------- |
| `game_id`               | string | ID of the game                                        |
| `stream_id`             | number | ID of the stream (campaign)                           |
| `stream_name`           | string | Display name of the stream                            |
| `player_uuid`           | string | DailyPlay player identifier                           |
| `score`                 | number | Player's score (only on `play_complete`)              |
| `play_duration_seconds` | number | Time to complete in seconds (only on `play_complete`) |
| `url_<param>`           | string | Any additional URL parameters prefixed with `url_`    |

:::note Identity parameters (`braze_id`, `external_id`, `user_id`) are excluded from event
properties since they are already used for user identification. :::

---

## Example Payload

Below is the full `/users/track` payload DailyPlay sends to Braze for a `play_complete` event:

```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"
      }
    }
  ]
}
```

---

## Use Cases in Braze

- **Triggered campaigns** — Send a follow-up message when `dailyplay_play_complete` fires
- **Segmentation** — Build segments based on `dailyplay.last_game_score` or
  `dailyplay.stream_<slug>` attributes
- **Canvas flows** — Use game events as entry triggers or decision splits in multi-step journeys
- **Re-engagement** — Target users who triggered `dailyplay_play_start` but not
  `dailyplay_play_complete`