# Praktikus Ajándékok – Saját Analytics Hub (GA4 / MCP)

**1. verzió – 2026. november, csak olvasási jogosultság**

Kifejezetten a **praktikusajandekok.hu** számára: saját Linux szerveren futó,
**Google Analytics 4 Data API v1beta**-t közvetlenül használó MCP-kiszolgáló.
Nem használ Windsor.ai-t. Az alap GA4 property: `300252586`.

A Google Ads és a Meta Ads integráció helye már szerepel a kódban (`analytics_hub/providers/`),
de **jelenleg nincsenek bekötve**. A két modul nem kezdeményez hitelesítést és nem nyúl
hirdetési fiókhoz.

## Funkciók

| MCP eszköz | Funkció |
|---|---|
| `ga4_connection_test` | Valódi GA4 hozzáférés ellenőrzése, előző teljes nap |
| `ga4_overview` | Munkamenetek, felhasználók, vásárlási események, bevétel, átlagos kosárérték |
| `ga4_channels` | Csatornánkénti forgalom és bevétel |
| `ga4_products` | Termékenkénti megtekintések, eladott egységek, bevétel (terméknév szerint) |
| `ga4_email_campaigns` | Hírlevélkampányok GA4-alapú látogatásai és bevétele |
| `ga4_realtime` | Előző 30 perc eseményei (`purchase`, `add_to_cart`, `begin_checkout`) |
| `ga4_custom_report` | Szabad, de korlátozott GA4 dimenzió/metrika riport |
| `analytics_connections` | Az adatforrások tényleges konfigurációs állapota |

### Fontos korlátok

- **Realtime ≠ teljes rendelésnyilvántartás**: a GA4 Realtime API csak az előző 30 perc
  eseményszámait teszi elérhetővé, a vásárlási bevételt és UTM attribúciót nem.
- A **normál GA4 riport nem azonnali**: napi véglegesítés és attribúció késhet.
- A GA4 nem mutatja a tényleges Drupal Commerce rendelési státuszokat,
  visszatérítéseket és fizetési eredményeket megbízhatóan, ha nincsenek elküldve.
- A jelenlegi webshopban korábban a `view_item` és `purchase` események
  `item_id` értékei különböztek. Ezért a termékriport **`itemName` szerint** csoportosít.
  Név/variáció-átfedés ettől még előfordulhat.
- A termékszintű `itemsAddedToCart` eseménymérés korábban hiányzott;
  az API nem javítja ki a hibás vagy elmaradt eseményeket.
- A hírlevélből érkező vásárlások akkor különíthetők el a legjobban, ha minden
  linket következetesen UTM-eztek (`utm_source`, `utm_medium=email`, `utm_campaign`).
- Az API használata normál kvótákon belül díjmentes, de a szerver, külső OAuth
  identitásszolgáltató vagy ChatGPT-fiók hozzáférése külön követelmény lehet.

## I. Google Cloud / GA4 jogosultság beállítása

1. Nyisd meg a **Google Cloud Console**-t: <https://console.cloud.google.com/>.
2. Hozz létre egy új projektet (például `praktikus-analytics-hub`).
3. Az **APIs & Services → Library** alatt engedélyezd:
   **Google Analytics Data API**.
4. Az **IAM & Admin → Service Accounts** menüpontban hozz létre egy szolgáltatásfiókot,
   például `ga4-readonly`. Készíts hozzá JSON kulcsot. A kulcsot **SOHA ne másold be chatbe**.
5. A Google Analytics <https://analytics.google.com/> oldalán lépj be:
   **Adminisztrálás → Tulajdon hozzáférés-kezelése**.
6. Add hozzá a szolgáltatásfiók e-mail-címét (`...iam.gserviceaccount.com`)
   **Megtekintő / Viewer** jogosultsággal a `300252586` tulajdonhoz.

Csak a `https://www.googleapis.com/auth/analytics.readonly` scope-ot használjuk.

## II. Telepítés Linuxra, Dockerrel (javasolt)

Előfeltétel: Docker Engine és Docker Compose plugin. A csomag állományait másold
például a `/opt/praktikus-analytics-hub` könyvtárba, és ott futtasd:

```bash
cd /opt/praktikus-analytics-hub
cp .env.example .env
mkdir -p secrets
# A kulcsot biztonságos módon a szerverre másold (scp, sftp, WinSCP).
# Végső helye: secrets/ga4-service-account.json
chmod 600 secrets/ga4-service-account.json

# Szerkeszd a .env PUID és PGID értékeit a jelenlegi Linux felhasználódhoz:
id -u
id -g

# A compose konténer ugyanazzal az UID/GID azonosítóval fut,
# és a kulcsnak ez által olvashatónak kell lennie.
docker compose up -d --build
docker compose logs --tail 60 analytics-hub
```

A hozzáférés **csak a szerver helyi címére** van publikálva:
`127.0.0.1:8765` (MCP végpont: `http://127.0.0.1:8765/mcp`).
A konténer belsejében `0.0.0.0` szükséges a Docker porttovábbításhoz;
**nem** jelenti azt, hogy a szolgáltatás a teljes internet számára nyitva van.

GA4 hozzáférés próba:

```bash
docker compose exec analytics-hub python -m analytics_hub.cli health
```

Az elvárt eredmény többek között `"source": "Google Analytics Data API (direct)"`,
`"report_type": "core"`; ha nincs jogosultság, a Google API pontos hibája jelenik meg.

### Ha nem használsz Dockert

Python 3.11+ esetén:

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env
# Itt a GOOGLE_APPLICATION_CREDENTIALS értéket a valós, helyi útra állítsd.
MCP_BIND_HOST=127.0.0.1 python -m analytics_hub.server
```

A `deploy/praktikus-analytics.service` fájl egy **systemd példa**; előbb létre kell
hoznod a megfelelő felhasználót, könyvtárat, kulcs-hozzáférést és virtuális környezetet.

## III. Lekérdezés közvetlenül SSH-ból (ChatGPT nélkül is működik)

```bash
# Elmúlt 7 teljes nap összesített GA4-adatai
docker compose exec analytics-hub python -m analytics_hub.cli overview --days 7

# Terméklista (a Google Analytics adatfeldolgozási késleltetésével)
docker compose exec analytics-hub python -m analytics_hub.cli products --from 2026-11-01 --to 2026-11-15 --limit 30

# Csatornaelemzés
docker compose exec analytics-hub python -m analytics_hub.cli channels --from 2026-11-01 --to 2026-11-15

# Hírlevél, UTM kulcsszóval
docker compose exec analytics-hub python -m analytics_hub.cli email --from 2026-11-16 --to 2026-11-16 --keyword black_friday

# Előző 30 perc eseményszámai; nincsenek benne pénzösszegek
docker compose exec analytics-hub python -m analytics_hub.cli realtime
```

Ezek a parancsok **nem módosítanak** semmit a GA4-ben.

## IV. Biztonságos ChatGPT MCP-bekötés

A ChatGPT **nem csatlakozik közvetlenül a saját géped `localhost` címéhez**.
A fenti szolgáltatást a ChatGPT felé egy **biztonságos, támogatott csatornán** kell
láthatóvá tenni. Két lehetséges modell:

**A. Secure MCP Tunnel (ajánlott):** az MCP szolgáltatás a saját szervereden marad,
  privát hálózati végponton. A támogatott ChatGPT-kliensben egy Secure MCP Tunnel
  kapcsolaton keresztül kötöd be. Ez megakadályozza, hogy a jelentések API-ja
  publikus IP-címen, jelszó nélkül elérhető legyen. Az OpenAI dokumentációja:
  <https://developers.openai.com/api/docs/guides/tools-connectors-mcp>.

**B. Publikus HTTPS végpont:** ehhez **OAuth 2.1 / megfelelő hitelesítési réteg**
  szükséges a szerver előtt vagy a szerverben. A jelenlegi csomag szándékosan
  **NEM tartalmaz publikus OAuth bejelentkeztető kiszolgálót**. A `No authentication`
  állapot nyitott, publikus végponttal **nem biztonságos**, mert az adatlekérdezések
  bárkinek elérhetők lennének. Ne nyisd ki nyersen a 8765-ös portot, és ne
  irányítsd a Cloudflare/Nginx proxy felől védtelenül a publikus internetre.

ChatGPT oldalon (ha a fiókban elérhető):
**Plugins → + → Add custom MCP server**, majd Tunnel vagy hitelesített HTTPS URL,
`/mcp` végponttal. A művelet a te aktív jóváhagyásodat igényli.

Dokumentáció: <https://developers.openai.com/api/docs/guides/custom-mcp-server>.
Az egyéni MCP-appok elérhetősége ChatGPT-csomag és jogosultság függvénye.

**A csomag elkészülte nem jelenti azt, hogy a szerver telepítve vagy a ChatGPT
már összekötve lenne.** Az adatlekérdezés a GA4-jogosultság megadása után működik.

## V. Későbbi Google Ads és Meta Ads

```text
analytics_hub/
  ga4.py                 # GA4 Data API, kész
  reports.py             # GA4 üzleti riportok, kész
  providers/base.py      # Közös hirdetési adatmodell (CampaignSummary)
  providers/google_ads.py # Google Ads adapter helye (NEM aktív)
  providers/meta_ads.py   # Meta Ads adapter helye (NEM aktív)
  server.py              # MCP eszközök, GA4 v1 kész
```

A Google Ads esetében új OAuth/Ads API jogosultság, fejlesztői token és adott
esetben MCC beállítás szükséges. Meta esetében Marketing API hozzáférés és
`ads_read` jogosultság. **Egyikhez sem használjuk a GA4 szolgáltatásfiók-kulcsát.**

Később a Google Ads / Meta adapterek `campaign_summary` felülete egységesen
visszaadhat kampánynevet, költést, kattintást, konverziót, becsült bevételt és
ROAS-t. Ez lehetővé teszi a platformadatok és GA4 attribúció eltéréseinek
összevetését, de nem szabad a kétféle attribúciót automatikusan összeadni.

## VI. Gyakori hibák

| Jelenség | Teendő |
|---|---|
| `403 User does not have sufficient permissions` | GA4 Property Access Management: service account Viewer jog ellenőrzése |
| `403 API has not been used` | Google Analytics Data API engedélyezése a Cloud projektben |
| `404` property | Azonosító: `300252586`, vagy a jogosultságot ellenőrizd |
| Ma csak néhány munkamenet látszik | Feldolgozási késés; Realtime csak eseményszámokat ad |
| Hírlevélnél nincs Email csatorna | UTM paraméterek ellenőrzése, főleg `utm_medium=email` |
| `Invalid metric / incompatible dimensions` | Csökkentsd a dimenziók/metrikák számát; GA4 API kompatibilitási korlát |
| `MCP port` nem érhető el kívülről | Szándékosan localhost-only. Tunnel vagy OAuth-tal védett HTTPS szükséges |

## Biztonsági megjegyzések

- A JSON kulcsot **nem** tesszük ZIP-be, Gitbe, e-mailbe vagy chatbe.
- A szolgáltatás kizárólag GA4 *read-only* scope-pal működik.
- Az alap MCP végpont helyi hálózati elérésű és önmagában **nem autentikál**.
  Emiatt nyilvános internet felé csak megfelelő védelmi réteg mögött használható.
- Az összes MCP eszköz `GET`/riport célú; nincs `delete`, `create campaign`, `pause ads`.
- Csomagérzékeny adatokat (pl. személyes rendelési rekordokat) GA4-ből sem
  szabad a Google adatgyűjtési szabályait megszegve gyűjteni.

## Hivatalos hivatkozások

- Google Analytics Data API: <https://developers.google.com/analytics/devguides/reporting/data/v1>
- GA4 Realtime mezők: <https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema>
- MCP Python SDK: <https://py.sdk.modelcontextprotocol.io/>
- ChatGPT egyéni MCP-kapcsolat: <https://developers.openai.com/api/docs/guides/custom-mcp-server>
