> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brama.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Analytics 4

> Web analytics та поведінка аудиторії через AI-агента – GA4 Data API, OAuth, read-only.

<Note>
  **Status: live.** 6 read-only MCP tools на GA4 Data API.
</Note>

## Як це працює

Google Analytics 4 інтеграція використовує **OAuth** модель: ти просто натискаєш Connect – Brama тримає власний OAuth-застосунок, нічого створювати самостійно не треба. Після стандартного Google consent твоя інтеграція переходить у статус **Active**.

Токени зберігаються **зашифрованими** (ключі поза базою), ізольовано per-tenant. Brama персистить ротовані refresh-токени автоматично – повторний consent при звичайній роботі не потрібен.

Brama надає AI-агенту **read-only** доступ до GA4-даних через єдиний MCP endpoint. Жодних записів у Google Analytics не виконується.

## Підключення

### 1. Connect

[`app.brama.work`](https://app.brama.work) → **Integrations → Google Analytics** → натисни **Connect**.

Brama редіректить тебе на Google OAuth consent screen. Надай доступ із scope **"View your Google Analytics data"** і повернешся у Brama – інтеграція стане `active`.

<Note>
  **"Google hasn't verified this app"** – під час consent screen Google може показати попередження «Google hasn't verified this app». Це очікувано: застосунок проходить процес верифікації. Натисни **Advanced → Continue** щоб продовжити. Це безпечно.
</Note>

На акаунті повинна бути принаймні одна GA4 property – без властивостей tools повернуть порожній список.

### 2. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI – див. [Connect a client](/connect)):

> Скільки користувачів я отримав за останні 30 днів і з яких каналів?

Агент викличе `brama_ga4_traffic_by_channel` і поверне розбивку users / sessions / ключових подій по каналах трафіку.

## MCP tools (live)

Усі 6 tools – **read-only**, на GA4 Data API. Нічого не змінюють у Google Analytics.

<Card title="brama_ga4_list_properties" icon="list">
  Список GA4 properties до яких tenant має доступ: назва, ID властивості, часовий пояс, валюта.

  **Параметри:** немає.

  Use: дізнатися доступні властивості перед першим звітом.
</Card>

<Card title="brama_ga4_get_metadata" icon="database">
  Доступні dimensions та metrics для конкретної GA4 property – включно з кастомними визначеннями.

  **Параметри:** `property_id` *(required)*.

  Use: дізнатися які виміри та показники доступні, перш ніж будувати гнучкий звіт.
</Card>

<Card title="brama_ga4_run_report" icon="chart-bar">
  Гнучкий звіт: будь-яка комбінація metrics × dimensions × date range × фільтри.

  **Параметри:**

  * `property_id` *(required)*
  * `metrics` *(required)* – напр. `["activeUsers", "sessions"]`
  * `dimensions` *(optional)* – напр. `["date", "country"]`
  * `date_ranges` *(required)* – масив `{ start_date, end_date }` (напр. `"30daysAgo"`, `"today"`)
  * `dimension_filter` *(optional)* – фільтр по dimensions
  * `limit` *(optional)* – default 10, max 250

  Use: "скільки конверсій по країнах за Q2", "порівняти трафік цього місяця vs минулого".
</Card>

<Card title="brama_ga4_top_pages" icon="file-text">
  Найпереглядувані сторінки за вказаний період: page path, screen name, кількість переглядів.

  **Параметри:**

  * `property_id` *(required)*
  * `start_date` *(required)* – напр. `"30daysAgo"` або `"2025-01-01"`
  * `end_date` *(required)* – напр. `"today"`
  * `limit` *(optional)* – default 10, max 50

  Use: "які сторінки найпопулярніші цього місяця?".
</Card>

<Card title="brama_ga4_traffic_by_channel" icon="signal">
  Users, sessions та ключові події по каналах трафіку (Organic Search, Direct, Referral, Paid Search тощо) за вказаний період.

  **Параметри:**

  * `property_id` *(required)*
  * `start_date` *(required)*
  * `end_date` *(required)*

  Use: "звідки йде трафік цього місяця?", "як змінився канал Organic за 3 місяці?".
</Card>

<Card title="brama_ga4_realtime" icon="activity">
  Активні користувачі та топ-події / сторінки за останні 30 хвилин.

  **Параметри:** `property_id` *(required)*.

  Use: "скільки людей на сайті зараз?", "які події відбуваються прямо зараз?".
</Card>

## Приклади запитів агенту

* "Скільки користувачів я отримав за останні 30 днів і з яких каналів?"
* "Які мої топ-сторінки цього місяця?"
* "Покажи активних користувачів прямо зараз."
* "Порівняй органічний трафік цього місяця з минулим."
* "Які країни дають найбільше сесій за останній квартал?"

## Безпека

* **Shared App** – Brama тримає єдиний OAuth-застосунок; tenant'у НЕ потрібно нічого створювати у Google Cloud.
* Scope – **read-only** (`analytics.readonly`). Brama не може змінювати дані, цілі або налаштування GA4.
* Токени зашифровані at rest (envelope encryption), ключі поза базою; на диск не пишуться, у пам'яті лише на час запиту; у логи не потрапляють.
* Brama персистить ротовані refresh-токени автоматично – повторний consent при звичайній роботі не потрібен.
* Кожен tenant ізольований – твої GA4-дані недосяжні іншим tenant'ам.

## Питання

Питання? Напиши `viktor@brama.work`.