# 🎯 SGK Analytics Integration Guide

## 1. Initialization

All analytics modules are imported from the shared SGK package:

```ts
import {Locator, LogAnalytics, AmplitudeAnalytics } from '@popiplay/slot-game-kit';

// Development / test logging
Locator.provide(new LogAnalytics());

// Production (sends data to Amplitude)
Locator.provide(new AmplitudeAnalytics(__AMPLITUDE_API_KEY));
```

> `__AMPLITUDE_API_KEY` is injected automatically by Webpack during the build.

---

## 2. Adding Activities in GameController

Add analytics-related activities inside your game controller:

```ts
import { GatherClientSessionEnvironmentInfo } from "@popiplay/slot-game-kit";
import { TrackOrientationActivity } from "@popiplay/slot-game-kit";

start() {
  console.log("Game Controller: Starting the game");

  this.activityRunner.addActivity(new GatherClientSessionEnvironmentInfo());
  this.activityRunner.addActivity(new TrackOrientationActivity());

  this.activityRunner.addActivity(new Init());
  this.activityRunner.addActivity(new LoadSystemAssets());
  this.activityRunner.addActivity(new Loading());
  this.activityRunner.addActivity(new ShowStartScene(this.model));
  this.activityRunner.addActivity(new InitModel(this.model));
  this.activityRunner.addActivity(new RunGameplay(this.model));
}
```

These activities automatically track:
- `SESSION_ENVIRONMENT_INFO` — browser, OS, and platform info.
- `ORIENTATION_LANDSCAPE` / `ORIENTATION_PORTRAIT` — device orientation at start and on change.

---

## 3. Analytics Architecture

### Core Classes

| Class | Description |
|-------|--------------|
| `BaseAnalytics` | Common interface for all analytics services. |
| `LogAnalytics` | Writes analytics events to the console (for dev/debug). |
| `AmplitudeAnalytics` | Sends analytics events to Amplitude. |
| `NullAnalytics` | Empty stub (used when analytics is disabled). |

All analytics go through:
```ts
Locator.analytics.track(eventName, payload);
```

Each event is automatically extended with a `ts` (timestamp since session start).

---

## 4. Event Map

File: `ANALYTICS_EVENTS.ts`

| Icon | Meaning |
|------|----------|
| ✅ | Implemented in the framework |
| ❌ | Not implemented yet |
| 🎮 | Must be implemented on the game side (inside scenes or activities) |

Each event is documented with a JSDoc comment describing its payload and where it should be triggered.

Example:
```ts
/**
 * 🎮 Player closed Bonus Buy popup without making a purchase
 * (implemented on the game side, inside the BonusBuy scene/UI)
 * Payload: none
 */
BONUS_BUY_CLOSED_NO_PURCHASE: 'bonus_buy_closed_no_purchase',
```

---

## 5. Manual Event Tracking

To manually track analytics from any game-side script:

```ts
import {Locator, ANALYTICS_EVENTS } from '@popiplay/slot-game-kit';

Locator.analytics.track(ANALYTICS_EVENTS.BONUS_BUY_PURCHASED, {
  bonusLevel: 'SuperBonus',
  cost: 1000,
  balanceBefore: 5000,
});
```

Each call automatically attaches the event name, timestamp, and payload to the active analytics provider.

---

## 6. Debugging and Testing

If `LogAnalytics` is used, all events appear in the browser console:
```
[Analytics] { name: "spin_button_double_click", ts: 123456, data: { intervalMs: 250 } }
```

To inspect all collected events:
```ts
Locator.analytics.flush();
```

---

## 7. Summary

✅ Framework-integrated analytics system  
✅ Unified `Locator.analytics.track()` interface  
✅ Built-in Amplitude support  
✅ Auto-collected session and orientation data  
🎮 Extendable with custom game-side events  

---

_This document should be included in the project at:_  
`docs/analytics.md`

