# Ads Event Reference

## Ad Types

| ad_type | Description |
|---------|-------------|
| `reward` | Rewarded video ad |
| `interstitial` | Interstitial ad |

## Placement Values

| Value | Enum | Description |
|-------|------|-------------|
| `None` | 0 | - |
| `Shop` | 1 | Shop |
| `Turntable` | 2 | Turntable |
| `Showdown` | 3 | Showdown |
| `FishingFail` | 4 | Fishing fail |
| `Chest` | 5 | Chest |
| `Aquarium` | 6 | Aquarium |
| `AdWheel` | 7 | Ad wheel |
| `LuckyMission` | 8 | Lucky mission |
| `Cycle2` | 9 | Cycle2 |
| `SignInAdvert` | 10 | Sign-in ad |

## Ad Unit IDs

| Platform | Reward | Interstitial |
|----------|--------|-------------|
| iOS | `ec3c8fd688cdb5e2` | `00442f7962682a80` |
| Android | `c6c49a100de8496c` | `0dcd37fa0885aa1f` |

---

## Event List

### Load Lifecycle

#### `ads_{ad_type}_load_start`

Ad load request initiated.

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| trigger_source | string | What triggered the load. See below |

**trigger_source values:**

| Value | Description |
|-------|-------------|
| `init` | App startup / re-login |
| `level_up` | Player reached level 40+ |
| `fish_exchange` | Player exchanged 17+ fish |
| `internal` | Interstitial internal trigger |

---

#### `ads_{ad_type}_load_success`

Ad loaded and ready to show.

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| placement | string | Placement from previous load (may be empty) |

---

#### `ads_{ad_type}_load_fail`

Ad load failed, will retry automatically. Retry uses exponential backoff: `min(retryCount, 6) * 2s`.

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| retry_count | int | Current retry attempt number (starts at 1) |
| error_code | string | MaxSdk error code |
| error_message | string | MaxSdk error message |

**Note:** If `retry_count > 5` and no subsequent `load_success`, the ad is stuck in a retry loop. Check `error_code` for root cause.

---

### Display Lifecycle

#### `ads_{ad_type}_display`

Ad successfully displayed on screen.

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| placement | string | AdvertPopupType value |

---

#### `ads_{ad_type}_display_fail`

Ad failed to display.

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| placement | string | AdvertPopupType value |
| error_code | string | MaxSdk error code |
| error_message | string | MaxSdk error message |

---

#### `ads_{ad_type}_hidden`

Ad was closed/hidden by user.

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| placement | string | AdvertPopupType value |

---

### User Actions

#### `ads_{ad_type}_click`

User clicked the "show ad" button (before ad actually displays).

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| placement | string | AdvertPopupType value |

---

#### `ads_{ad_type}_not_ready`

User clicked "show ad" but no cached ad available.

| Field | Type | Description |
|-------|------|-------------|
| placement | string | AdvertPopupType value |

---

### Reward

#### `ads_reward_rewarded`

User watched the full rewarded ad and earned the reward.

| Field | Type | Description |
|-------|------|-------------|
| ad_unit_id | string | Ad unit ID |
| placement | string | AdvertPopupType value |

---

### Crash Detection

#### `ads_app_crash`

Detected on next app launch: the previous session crashed during an ad operation.

| Field | Type | Description |
|-------|------|-------------|
| crash_flag | string | Full flag: `{ad_type}_{operation}_{unix_timestamp}` |
| ad_type | string | `reward` or `interstitial` |
| operation | string | `load` or `display` |

Use `crash_flag` timestamp to determine crash time.

---

## Typical Event Sequences

### Normal rewarded ad flow
```
ads_reward_click          → user taps watch button
ads_reward_load_start     → (if not already loaded)
ads_reward_load_success   → ad cached
ads_reward_display        → ad shows
ads_reward_rewarded       → user earned reward
ads_reward_hidden         → user closes ad
```

### Normal interstitial ad flow
```
ads_interstitial_load_start    → triggered by level_up / fish_exchange / init
ads_interstitial_load_success  → cached
ads_interstitial_display       → auto-shown
ads_interstitial_hidden        → user closes
```

### Load failure + retry
```
ads_reward_load_fail     (retry_count=1, error_code=...)
ads_reward_load_fail     (retry_count=2, error_code=...)
ads_reward_load_success  → eventually succeeds
```

### App crashed during ad display
```
[current session]
ads_reward_display       → ad showed, then app crashed

[next session]
ads_app_crash            (crash_flag="reward_display_1712995200", operation="display")
```

---

## Common Analysis Queries

**Ad load success rate:**
```
ads_{ad_type}_load_success / ads_{ad_type}_load_start
```

**Ad display rate (of loaded ads):**
```
ads_{ad_type}_display / ads_{ad_type}_load_success
```

**Reward completion rate (of displayed ads):**
```
ads_reward_rewarded / ads_reward_display
```

**Load stuck detection:**
Find `ads_{ad_type}_load_fail` with `retry_count >= 5` and no subsequent `load_success` within 10 minutes.

**Crash correlation:**
Join `ads_app_crash.operation = "display"` with session crash reports to identify ad-related crashes.

**Not-ready rate by placement:**
Group `ads_{ad_type}_not_ready` by `placement` to find which ad placements have the worst cache miss rates.