# Koneksyon sa Braze

Pinapayagan ka ng Braze connection na itulak ang player data nang direkta sa Braze gamit ang
[/users/track](https://www.braze.com/docs/api/endpoints/user_data/post_user_track/) API. Ang bawat
trigger event ay nagpapadala ng parehong **user attributes** at **custom event** sa Braze, para makagawa ka ng
segments, mag-trigger ng campaigns, at mag-orchestrate ng Canvas flows base sa game activity.

---

## Mga Kinakailangan

| Requirement            | Saan ito makikita                                                                     |
| :--------------------- | :----------------------------------------------------------------------------------- |
| **Braze REST API Key** | Braze Dashboard → **Settings** → **API Keys** (kailangan ng `users.track` permission)       |
| **REST Endpoint**      | Braze Dashboard → **Settings** → **API Keys** (hal. `https://rest.iad-01.braze.com`) |

---

## Pag-set Up

1. Pumunta sa **Connections** mula sa main navigation
2. I-click ang **Add Connection** at piliin ang **Braze**
3. Ilagay ang iyong **API Key** at **REST Endpoint**
4. I-save ang connection
5. I-link ito sa stream at piliin ang iyong trigger events

---

## User Identification

Kinikilala ng DailyPlay ang users sa Braze sa pamamagitan ng URL parameters na naipasa kapag na-access ng manlalaro ang stream.
Sumusuporta ang Braze ng dalawang uri ng identifier:

| URL Parameter | Braze API Field | Paglalarawan                               |
| :------------ | :-------------- | :---------------------------------------- |
| `braze_id`    | `braze_id`      | Internal user identifier ng Braze          |
| `external_id` | `external_id`   | User ID ng iyong sistema na naka-map sa Braze   |
| `user_id`     | `external_id`   | Alias — itinuturing na pareho ng `external_id` |

Sinusuri ng DailyPlay ang identifiers sa priority order: `braze_id` → `external_id` → `user_id`. Kung wala
sa URL parameters, ginagamit ang DailyPlay `player_uuid` ng manlalaro bilang
`external_id`.

### Halimbawang Stream URL

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

---

## Attributes na Ipinapadala sa Braze

Ang bawat trigger event ay nag-u-update ng user profile sa Braze gamit ang mga sumusunod na custom attributes:

### Top-Level Attributes

| Attribute     | Type   | Paglalarawan                                               |
| :------------ | :----- | :-------------------------------------------------------- |
| `country`     | string | Country code ng manlalaro (awtomatikong nadedetect)            |
| `device_type` | string | Uri ng device na ginamit ng manlalaro (hal. `mobile`, `desktop`) |

### Nested `dailyplay` Object

Ang lahat ng DailyPlay-specific attributes ay naka-group sa ilalim ng `dailyplay` object sa user profile:

| Attribute                        | Type   | Paglalarawan                                                                             |
| :------------------------------- | :----- | :-------------------------------------------------------------------------------------- |
| `dailyplay.last_game_id`         | string | ID ng pinakahuling nilalarong laro                                                     |
| `dailyplay.last_stream_name`     | string | Pangalan ng stream kung saan kabilang ang laro                                                  |
| `dailyplay.last_stream_slug`     | string | URL slug ng stream                                                                  |
| `dailyplay.last_play_date`       | string | ISO 8601 timestamp ng huling interaction                                              |
| `dailyplay.stream_<stream_slug>` | string | Event type na naitala para sa stream na ito (hal. `play_complete`) — kapaki-pakinabang para sa funnel tracking |
| `dailyplay.last_game_score`      | number | Score ng manlalaro (sa `play_complete` events lang)                                         |
| `dailyplay.last_play_duration`   | number | Play duration sa segundo (sa `play_complete` events lang)                               |

:::tip Nagtatago ang `dailyplay.stream_<stream_slug>` attribute ng latest event type bawat stream. Gamitin
ito sa Braze para gumawa ng journey-based segments — halimbawa, i-target ang users kung saan
`dailyplay.stream_welcome_stream` ay pantay sa `play_complete`. :::

---

## Custom Events na Ipinapadala sa Braze

Ang bawat trigger ay nagfa-fire ng custom event sa Braze na may naming pattern na `dailyplay_<event_type>`:

| Event Name                   | Nagfa-fire kapag…                        |
| :--------------------------- | :--------------------------------- |
| `dailyplay_stream_access`    | Binubuksan ng manlalaro ang stream page     |
| `dailyplay_play_start`       | Nagsisimula ang manlalaro ng laro             |
| `dailyplay_play_complete`    | Tinatapos ng manlalaro ang laro           |
| `dailyplay_prize_redemption` | Kino-claim ng manlalaro ang premyo o voucher |

### Event Properties

Kasama sa bawat custom event ang mga sumusunod na properties:

| Property                | Type   | Paglalarawan                                           |
| :---------------------- | :----- | :---------------------------------------------------- |
| `game_id`               | string | ID ng laro                                        |
| `stream_id`             | number | ID ng stream (campaign)                           |
| `stream_name`           | string | Display name ng stream                            |
| `player_uuid`           | string | DailyPlay player identifier                           |
| `score`                 | number | Score ng manlalaro (sa `play_complete` lang)              |
| `play_duration_seconds` | number | Oras para matapos sa segundo (sa `play_complete` lang) |
| `url_<param>`           | string | Anumang karagdagang URL parameters na may prefix na `url_`    |

:::note Hindi kasama ang identity parameters (`braze_id`, `external_id`, `user_id`) sa event
properties dahil ginagamit na ang mga ito para sa user identification. :::

---

## Halimbawang Payload

Narito ang buong `/users/track` payload na ipinapadala ng DailyPlay sa Braze para sa `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"
      }
    }
  ]
}
```

---

## Mga Use Case sa Braze

- **Triggered campaigns** — Magpadala ng follow-up message kapag nag-fire ang `dailyplay_play_complete`
- **Segmentation** — Gumawa ng segments base sa `dailyplay.last_game_score` o
  `dailyplay.stream_<slug>` attributes
- **Canvas flows** — Gamitin ang game events bilang entry triggers o decision splits sa multi-step journeys
- **Re-engagement** — I-target ang users na nag-trigger ng `dailyplay_play_start` pero hindi
  `dailyplay_play_complete`