diff --git a/app/main.py b/app/main.py index 8a7d60b..aec9a7e 100644 --- a/app/main.py +++ b/app/main.py @@ -24,13 +24,76 @@ ROOT_PATH = os.getenv("ROOT_PATH", "") DESCRIPTION = """ Stateless proxy exposing **Google Analytics 4** and **Sklik** (Seznam) APIs. -All credentials are passed per request as `X-` headers (never stored): +Veškeré přihlašovací údaje se posílají v každém requestu jako `X-` hlavičky – +služba si nic neukládá. Vyplníte je v Swaggeru po kliknutí na **Try it out**. -* **Google Analytics** — `X-GA-Access-Token` (preferred) or `X-GA-Credentials` - (base64 service-account JSON). Optional `X-GA-Quota-Project`. -* **Sklik** — `X-Sklik-Token`. Optional `X-Sklik-User-Id` for managed accounts. +| Služba | Hlavička | Povinné | +| --- | --- | --- | +| Google Analytics | `X-GA-Access-Token` **nebo** `X-GA-Credentials` | jedna z nich | +| Google Analytics | `X-GA-Quota-Project` | ne | +| Sklik | `X-Sklik-Token` | ano | +| Sklik | `X-Sklik-User-Id` | ne (jen pro agenturní/MCC přístup) | -See `documentation/` in the repository for details. +--- + +## Kde vzít přihlašovací údaje + +### 🔹 Google Analytics 4 + +Potřebujete dvě věci: **přístup k API** a **ID property** (číslo, na které se +ptáte). + +**ID property** (`property_id` v URL): v GA4 vpravo dole **Administrace → +Nastavení property** – nahoře je *ID property*, např. `123456789`. + +Pro přístup máte dvě možnosti (stačí jedna): + +**A) Service account – doporučeno pro automatizaci (`X-GA-Credentials`)** + +1. [Google Cloud Console](https://console.cloud.google.com/) → vytvořte nebo + vyberte projekt. +2. **APIs & Services → Library** → povolte **Google Analytics Data API** + a **Google Analytics Admin API**. +3. **IAM & Admin → Service Accounts → Create service account**. +4. U vytvořeného účtu **Keys → Add key → Create new key → JSON** – stáhne se + soubor s klíčem. +5. Z JSON souboru zkopírujte `client_email` a v GA4 ho přidejte k property: + **Administrace → Správa přístupu k property → +** , role **Viewer** + (Čtenář). +6. Celý JSON soubor zakódujte do **base64** a vložte do hlavičky + `X-GA-Credentials`: + - Windows PowerShell: + `[Convert]::ToBase64String([IO.File]::ReadAllBytes("klic.json"))` + - Linux/macOS: `base64 -w0 klic.json` + +**B) Hotový OAuth2 token – pro rychlý test (`X-GA-Access-Token`)** + +1. [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/). +2. Vlevo zadejte scope `https://www.googleapis.com/auth/analytics.readonly` + a klikněte **Authorize APIs** (přihlaste se Google účtem, který má přístup + k property). +3. **Exchange authorization code for tokens** → zkopírujte *Access token* do + hlavičky `X-GA-Access-Token`. Pozor: platí jen ~1 hodinu. + +### 🔹 Sklik + +Potřebujete **API token (klíč)** z účtu, jehož data chcete číst. + +1. Přihlaste se na [sklik.cz](https://www.sklik.cz/). +2. Vpravo nahoře klikněte na **své uživatelské jméno → Nastavení**. +3. V nastavení účtu otevřete sekci **Přístup k API Drak**. +4. Klikněte na **Zobrazit token** a token zkopírujte do hlavičky + `X-Sklik-Token`. + +> ⚠️ Každé vygenerování nového tokenu **zneplatní ten předchozí**. Token je +> vázaný na účet, pod kterým jste přihlášeni. +> +> Spravujete-li cizí účty (agentura/MCC), vložte cílové `userId` do hlavičky +> `X-Sklik-User-Id`. + +--- + +Podrobnosti k jednotlivým endpointům jsou v `documentation/` v repozitáři. """.strip() app = FastAPI( diff --git a/documentation/google-analytics.md b/documentation/google-analytics.md index f15786e..6f1cf40 100644 --- a/documentation/google-analytics.md +++ b/documentation/google-analytics.md @@ -23,6 +23,30 @@ The service account (or token) must have access to the GA4 property — add its > `[Convert]::ToBase64String([IO.File]::ReadAllBytes("service-account.json"))` > (PowerShell). +## Kde získat údaje (návod pro klienta) + +**ID property** (`property_id` v URL): GA4 → **Administrace → Nastavení +property** → *ID property* (např. `123456789`). + +**A) Service account – doporučeno (`X-GA-Credentials`)** + +1. [Google Cloud Console](https://console.cloud.google.com/) → projekt. +2. **APIs & Services → Library** → povolit **Google Analytics Data API** a + **Google Analytics Admin API**. +3. **IAM & Admin → Service Accounts → Create service account**. +4. U účtu **Keys → Add key → JSON** → stáhne se klíč. +5. `client_email` z JSON přidat v GA4 **Administrace → Správa přístupu k + property** jako **Viewer**. +6. JSON zakódovat do base64 (viz výše) → hlavička `X-GA-Credentials`. + +**B) Hotový OAuth2 token – rychlý test (`X-GA-Access-Token`)** + +1. [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/). +2. Scope `https://www.googleapis.com/auth/analytics.readonly` → **Authorize + APIs** (Google účet s přístupem k property). +3. **Exchange authorization code for tokens** → *Access token* → hlavička + `X-GA-Access-Token` (platí ~1 h). + ## Data API endpoints `property_id` may be the bare number (`123456789`) or `properties/123456789`. diff --git a/documentation/sklik.md b/documentation/sklik.md index 0c193d0..93334c5 100644 --- a/documentation/sklik.md +++ b/documentation/sklik.md @@ -25,6 +25,16 @@ injects the session — callers never handle the session. | `X-Sklik-Token` | yes | API token from Sklik → account settings → API. | | `X-Sklik-User-Id` | no | Managed account `userId` (agency/MCC access). | +### Kde získat token (návod pro klienta) + +1. Přihlaste se na [sklik.cz](https://www.sklik.cz/). +2. Vpravo nahoře **uživatelské jméno → Nastavení**. +3. Sekce **Přístup k API Drak** → **Zobrazit token**. +4. Token → hlavička `X-Sklik-Token`. + +> Nový token zneplatní ten předchozí. Token je vázaný na účet, pod kterým jste +> přihlášeni. Pro správu cizích účtů (agentura/MCC) použijte `X-Sklik-User-Id`. + Missing token → `401 missing_credentials`. Sklik business errors (invalid token, access denied, bad arguments) are surfaced as `upstream_error` with the Sklik `status` and full body.