237 lines
5.6 KiB
Markdown
237 lines
5.6 KiB
Markdown
# 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.
|