GM-Match3 Integration Guide
Complete reference for the GM-Match3 Unity demo game. Covers all telemetry events wired via GameMantraMatch3Integration.cs, how to verify them on a real Android device, and what items & currencies to configure in the dashboard catalogue before testing.
ADB log filter — run this before launching the game to see all GameMantra events in real time:
adb logcat -c && adb logcat | grep -E "\[GM\]\[Match3\]|GMApiClient|FlutterBootstrap"All Wired Events
Every event fired by GameMantraMatch3Integration.cs. Telemetry events feed the analytics pipeline. Offer events trigger the Experience overlay.
Lifecycle
| event_type | trigger | offer | how to test |
|---|---|---|---|
level_start | OnPlayerInputUnlock (1st) | — | Start any level — fires once when the board is interactive. |
level_complete | OnLevelCompleted | level_complete ✅ 0.8s deferred | Complete all goals. Offer appears on victory screen after 0.8s. |
level_fail | OnNoMovesLeft / OnLevelFailed | eliminate ✅ 0.8s deferred | Burn all moves without completing goals. Offer appears on fail screen. |
first_win | OnLevelCompleted (1st ever) | — | Clear PlayerPrefs key gm_match3_first_win to retrigger. Fires once per device lifetime. |
first_loss | OnNoMovesLeft (1st ever) | — | Clear PlayerPrefs key gm_match3_first_loss to retrigger. |
Progression
| event_type | trigger | offer | how to test |
|---|---|---|---|
lives_depleted | OnMoveCountChanged (≤5 moves) | lives_depleted ✅ 1.5s deferred | Use 5+ moves without completing (level has 10 moves). Offer shows ~1.5s later. |
energy_empty | OnMoveCountChanged (≤2 moves) | energy_empty ✅ 1.5s deferred | Burn down to 2 moves. Offer shows ~1.5s later (skips if level ends first). |
objective_complete | OnGoalUIUpdate (remaining=0) | — | Clear one full goal type. Fires once per goal type. |
match_event | OnMainEventGoalMatch | — | Make any match that contributes to the main event goal bar. |
event_progress | OnMainEventGoalRemoval | — | Fires each time a main event goal item is removed from the board. |
board_shuffled | OnShuffleBoard | — | Use the JesterHat UI booster to shuffle the board. |
Boosters
| event_type | trigger | offer | how to test |
|---|---|---|---|
achievement_unlocked | OnBoosterUsed(int) | — | Create a match of 4+ items to spawn a TNT (100), Rocket (101/102), LightBall (103), or Missile (104). Activate it. |
booster_selected | OnBoosterButtonClicked(int) | — | Tap any UI booster button (Hammer, JesterHat, Bow, Cannon) before placing it. |
booster_deselected | OnBoosterRemoved(int) | — | Tap the same UI booster button again to deselect it. |
Economy
| event_type | trigger | offer | how to test |
|---|---|---|---|
coin_changed | OnCoinAmountChanged | — | Earn or spend coins in the shop or level rewards. |
heart_changed | OnHeartAmountChanged | — | Fail a level (costs 1 heart) or wait for heart regeneration. |
star_changed | OnStarAmountChanged | — | Complete a level to earn stars. |
booster_inventory_changed | OnBoosterAmountChanged | — | Buy or use a booster from the shop. |
powerup_inventory_changed | OnPowerUpAmountChanged | — | Buy or use a power-up (Hammer, Bow, Cannon, JesterHat) from the shop. |
Booster ID Reference
Internal IDs from the MatchType enum used in achievement_unlocked payloads. Add custom IDs via the Booster Name Map field on the[GameMantraMatch3] GameObject.
| ID | Booster | Type | How to Spawn |
|---|---|---|---|
| 100 | tnt | In-game | Match T/L/cross shape (5+ items) |
| 101 | horizontal_rocket | In-game | Match 4 items in a horizontal row |
| 102 | vertical_rocket | In-game | Match 4 items in a vertical column |
| 103 | lightball | In-game | Match 5+ items in a straight line |
| 104 | missile | In-game | Match cross shape (L+I) |
| — | hammer | UI Booster | Tap Hammer icon in booster bar |
| — | jester_hat | UI Booster | Tap JesterHat icon → board shuffles |
| — | bow | UI Booster | Tap Bow icon → select a row |
| — | cannon | UI Booster | Tap Cannon icon → select a column |
Catalogue Setup
Go to Dashboard → Catalogue and add the currencies and items below before testing offers. The AI engine uses these to build offer bundles (e.g. "10 000 Coins for $0.49").
Currencies
Add all three — they map directly to in-game balances.
Primary earn currency — gained from level rewards, daily bonus, events.
Currency ID: coins
One consumed per failed level. Regenerates over time. Cap = 5.
Currency ID: hearts
Awarded on level completion. Used for event milestones.
Currency ID: stars
Items (IAP Catalogue)
Add these as purchasable items for offer bundles.
Entry-level coin pack — highest conversion for new/never-purchased segment.
Product ID: com.gm.sweetcrush.tenkCategory: Coins
Mid-tier pack — target active + paying segment.
Product ID: com.gm.sweetcrush.50kCategory: Coins
High-value pack — target top-spender (whale) segment.
Product ID: com.gm.sweetcrush.200kCategory: Coins
Lives refill — peak CVR at level_fail event.
Product ID: com.gm.sweetcrush.heart5Category: Lives
5× TNT + 5× Rocket + 3× LightBall — target stuck segment.
Product ID: com.gm.sweetcrush.boost5Category: Boosters
One-time first-purchase offer: 5000 Coins + 3 Hearts + 2 Boosters.
Product ID: com.gm.sweetcrush.starterCategory: Bundle
Offer Flow
Level ends (win or lose)
OnLevelCompleted / OnNoMovesLeft fires
0.8s real-time wait
Victory/fail panel animation finishes
Time.timeScale = 0
Game freezes — no competing GL draw calls
GetNextOffer (HTTP ~80ms)
Backend selects offer from L1–L5 fallback chain
http=200 — Experience overlay shows
Offer appears on top of the level screen
Player taps Buy / Close
Bootstrap.HandleOfferDismissed: timeScale=1 restored
Player taps Continue
SceneManager.LoadScene(1) — main menu loads
Testing on Device
Test level_complete offer
- 1.Open level 1 (goals set to [5,5] for fast testing)
- 2.Make 3 matches — both goal types should clear
- 3.Look for: ✅ level_complete → → Offer coroutine started → GMApiClient: POST /offers/next → http=200
- 4.Wait 0.8s — Experience offer overlay should appear on the victory screen
- 5.Dismiss offer → tap Continue → main menu loads
Test level_fail offer
- 1.Open any level, intentionally waste all 10 moves
- 2.Look for: ❌ level_fail → → Offer coroutine started → http=200
- 3.Wait 0.8s — offer appears on fail screen
Test lives_depleted / energy_empty offers
- 1.Open a level and use moves without making goal progress
- 2.At 5 moves remaining: ⚠ lives_depleted fires, 1.5s deferred offer starts
- 3.At 2 moves remaining: 🔴 energy_empty fires
- 4.If level ends before 1.5s: offer skipped (level boundary offer takes priority)
Test booster events
- 1.Create a 4-in-a-row match → Rocket spawns
- 2.Match the Rocket with other items → achievement_unlocked fires with booster_type=horizontal_rocket
- 3.Tap a UI booster button → booster_selected fires
- 4.Tap again to deselect → booster_deselected fires
Test economy events
- 1.Complete a level → star_changed and coin_changed fire
- 2.Fail a level → heart_changed fires (hearts decrease by 1)
- 3.Buy a booster from shop → booster_inventory_changed fires
Verify offer http=204 (no offer)
- 1.If the offer returns 204 (no offer), the overlay won't show
- 2.This happens if: kill switch is NONE, player is in holdout group, spend_score < 0.10, or fatigue limit reached
- 3.Check: redis-cli GET kill_switch:<game_id>
- 4.Check: redis-cli HGETALL "player:features:<game_id>:<player_id>"