Подключение Google Analytics Data API (GA4): подробная инструкция по интеграции

  •   
  •   77456
  •   11 мин
  •   19

В современном мире данные являются ключевым активом для принятия обоснованных решений. Google Analytics 4 (GA4) предоставляет мощные инструменты для сбора и анализа информации о поведении пользователей на вашем сайте или в приложении. Однако для глубокой интеграции, автоматизации отчетов и создания кастомных дашбордов стандартного интерфейса часто бывает недостаточно.

Саммари статьи
ChatGPT ChatGPT
Google AI Google AI
Grok Grok
Perplexity Perplexity

Именно здесь на помощь приходит Google Analytics Data API. Он позволяет программно получать доступ к вашим данным GA4, открывая широкие возможности для их использования в собственных приложениях, системах аналитики или для автоматической генерации отчетов. Это руководство предоставит вам пошаговую инструкцию по подключению и работе с GA4 Data API, охватывая все этапы от начальной настройки в Google Cloud до практических примеров получения данных на PHP и Python.

Начальная настройка и подготовка в Google Cloud и GA4

Первым шагом к интеграции с Google Analytics Data API (GA4) является подготовка среды в Google Cloud Console и настройка доступа в Google Analytics 4.

Создание проекта и включение Google Analytics Data API в Google Cloud Console

  1. Откройте Google Cloud Console.

  2. Создайте новый проект или выберите существующий.

  3. Через поиск найдите "Google Analytics Data API" и включите его для вашего проекта.

Настройка сервисного аккаунта и предоставление ему прав доступа в Google Analytics 4

  1. В Google Cloud Console перейдите в "IAM и администрирование" -> "Сервисные аккаунты".

  2. Создайте новый сервисный аккаунт, присвоив ему имя.

  3. Скопируйте адрес электронной почты созданного аккаунта.

  4. В Google Analytics 4, в разделе "Администратор" -> "Управление доступом к ресурсу" для вашего ресурса GA4, добавьте этот сервисный аккаунт.

  5. Предоставьте ему роль "Читатель" (Viewer) или соответствующую вашим потребностям.

Это обеспечивает необходимую основу для дальнейшего получения учетных данных.

Создание проекта и включение Google Analytics Data API в Google Cloud Console

Для начала работы с Google Analytics Data API (GA4) необходимо подготовить среду в Google Cloud Console. Этот шаг является фундаментом для всех последующих взаимодействий с API.

  1. Перейдите в Google Cloud Console: Откройте console.cloud.google.com.

  2. Создайте новый проект или выберите существующий:

    • В верхней части страницы нажмите на выпадающее меню выбора проекта.

    • Выберите "Новый проект" и следуйте инструкциям, чтобы создать его, присвоив осмысленное имя (например, "GA4 Data API Integration").

    • Если у вас уже есть проект, который вы хотите использовать, просто выберите его из списка.

  3. Включите Google Analytics Data API:

    • После выбора или создания проекта перейдите в "Навигационное меню" (три горизонтальные линии в левом верхнем углу) > "API и сервисы" > "Библиотека API".

    • В строке поиска введите "Google Analytics Data API" и выберите его из результатов.

    • Нажмите кнопку "Включить" (Enable). Это активирует API для вашего проекта, позволяя ему обрабатывать запросы к данным GA4.

Настройка сервисного аккаунта и предоставление ему прав доступа в Google Analytics 4

Для безопасной аутентификации вашего приложения в Google Analytics 4 необходимо настроить сервисный аккаунт. Это специальный тип аккаунта Google, который используется приложениями для доступа к данным.

Шаги по настройке сервисного аккаунта:

  1. Создание сервисного аккаунта: В Google Cloud Console перейдите в раздел IAM & Admin > Service Accounts. Нажмите + CREATE SERVICE ACCOUNT, укажите имя (например, ga4-data-api-service), ID и описание. Нажмите DONE.

  2. Генерация ключа: После создания аккаунта, нажмите на него, перейдите на вкладку KEYS, затем ADD KEY > Create new key. Выберите тип ключа JSON и нажмите CREATE. Файл JSON с учетными данными будет автоматически загружен на ваш компьютер. Сохраните его в безопасном месте.

  3. Предоставление доступа в GA4: Откройте Google Analytics 4, перейдите в Администрирование > Управление доступом к ресурсу (Property Access Management). Нажмите + > Добавить пользователей. В поле Адреса электронной почты введите email вашего сервисного аккаунта (его можно найти в загруженном JSON-файле или в списке сервисных аккаунтов в GCP). Выберите роль Читатель (Viewer) и нажмите Добавить.

Получение учетных данных и установка клиентских библиотек

После успешного создания сервисного аккаунта и получения JSON-ключа, следующим шагом является извлечение необходимых учетных данных и подготовка среды разработки.

Как получить GA_PROPERTY_ID, GA_CLIENT_EMAIL и GA_PRIVATE_KEY

  1. GA_PROPERTY_ID: Это числовой идентификатор вашего ресурса Google Analytics 4. Его можно найти в интерфейсе GA4 в разделе «Администратор» -> «Настройки ресурса» (например, 123456789).

  2. GA_CLIENT_EMAIL: Откройте загруженный JSON-файл ключа сервисного аккаунта. Значение client_email из этого файла будет вашим GA_CLIENT_EMAIL.

  3. GA_PRIVATE_KEY: В том же JSON-файле найдите поле private_key. Это ваш закрытый ключ. Важно: храните этот ключ в безопасности и никогда не раскрывайте его публично.

Установка клиентских библиотек Google API для PHP и Python

Для удобной работы с Google Analytics Data API рекомендуется использовать официальные клиентские библиотеки.

  • Для PHP: Используйте Composer для установки библиотеки:

    composer require google/analytics-data

  • Для Python: Используйте pip для установки библиотеки:

    pip install google-analytics-data

Эти библиотеки упрощают процесс аутентификации и выполнения запросов к API.

Как получить GA_PROPERTY_ID, GA_CLIENT_EMAIL и GA_PRIVATE_KEY

Для успешной работы с Google Analytics Data API (GA4) вам потребуются три ключевых идентификатора, которые были упомянуты ранее:

  • GA_PROPERTY_ID (Идентификатор свойства GA4): Это уникальный числовой идентификатор вашего свойства Google Analytics 4. Его можно найти в интерфейсе GA4: перейдите в раздел "Администратор" -> "Настройки свойства" -> "Идентификатор свойства". Он обычно имеет формат 123456789.

  • GA_CLIENT_EMAIL (Электронная почта сервисного аккаунта): Этот адрес электронной почты находится в JSON-файле ключа, который вы скачали при создании сервисного аккаунта в Google Cloud Console. Откройте JSON-файл и найдите поле client_email.

  • GA_PRIVATE_KEY (Приватный ключ сервисного аккаунта): Также находится в том же JSON-файле. Это длинная строка, начинающаяся с -----BEGIN PRIVATE KEY----- и заканчивающаяся -----END PRIVATE KEY-----\n. Скопируйте все содержимое поля private_key, включая заголовки и переносы строк.

Эти данные будут использоваться для аутентификации ваших запросов к API.

Установка клиентских библиотек Google API для PHP и Python

После получения всех необходимых учетных данных, следующим шагом является установка клиентских библиотек Google API. Эти библиотеки значительно упрощают взаимодействие с Google Analytics Data API (GA4), абстрагируя сложности HTTP-запросов и аутентификации.

Для PHP

Для установки клиентской библиотеки Google API для PHP рекомендуется использовать Composer – менеджер зависимостей для PHP. Если Composer не установлен, его необходимо инсталлировать в первую очередь.

Выполните следующую команду в корневой директории вашего проекта:

composer require google/apiclient

Эта команда установит последнюю версию клиентской библиотеки Google API, включая все необходимые зависимости для работы с GA4 Data API.

Для Python

Для Python установка клиентской библиотеки Google API осуществляется с помощью pip – стандартного менеджера пакетов Python. Убедитесь, что у вас установлен Python 3 и pip.

Выполните следующую команду в терминале:

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

Эта команда установит основную клиентскую библиотеку Google API, а также дополнительные пакеты для аутентификации, которые потребуются для взаимодействия с GA4 Data API.

Основы работы с Google Analytics Data API (GA4)

Начав работу с Google Analytics Data API (GA4), важно понимать его основные строительные блоки:

  • Метрики (Metrics) — это количественные измерения данных, такие как activeUsers (активные пользователи) или screenPageViews (просмотры страниц). Они показывают «сколько» или «как много».

  • Параметры (Dimensions) — это атрибуты данных, описывающие их, например, pagePath (путь страницы) или country (страна). Они отвечают на вопросы «что», «где» или «кто».

  • Фильтры (Filters) позволяют сужать или расширять выборку данных, например, показывать данные только для определенной страницы или страны.

  • Диапазоны дат (Date Ranges) определяют временной интервал, за который запрашиваются данные.

Ключевое отличие GA4 Data API от устаревшего Universal Analytics Reporting API заключается в его архитектуре и модели данных. GA4 API ориентирован на события, предлагая более гибкую и унифицированную модель для сбора и анализа данных о взаимодействии пользователей. Он также предоставляет более широкий набор метрик и параметров, специфичных для GA4, и поддерживает более сложные запросы, включая когортный анализ и воронки.

Ключевые концепции: метрики, параметры, фильтры и диапазоны дат

Для эффективной работы с Google Analytics Data API (GA4) критически важно понимать его основные строительные блоки, которые определяют структуру и содержание ваших запросов:

  • Метрики (Metrics) — это количественные показатели ваших данных, которые вы хотите измерить. Они представляют собой числовые значения, такие как activeUsers (активные пользователи), screenPageViews (просмотры страниц/экранов) или totalRevenue (общий доход).

    Реклама

  • Параметры (Dimensions) — это качественные атрибуты данных, которые позволяют сегментировать метрики. Например, вы можете просматривать screenPageViews по pagePath (путь страницы), eventName (название события) или country (страна).

  • Фильтры (Filters) используются для уточнения данных, возвращаемых запросом. Вы можете применять фильтры к метрикам или параметрам, чтобы включить или исключить определенные значения, например, показывать данные только для конкретного pagePath или события.

  • Диапазоны дат (Date Ranges) определяют временной период, за который вы запрашиваете данные. API позволяет указывать как абсолютные даты (например, ‘2023-01-01’ по ‘2023-01-31’), так и относительные (например, ‘today’, ‘yesterday’, ‘7daysAgo’).

Различия между GA4 Data API и устаревшим Universal Analytics Reporting API

Переход от Universal Analytics к Google Analytics 4 принес фундаментальные изменения в модель данных, что, в свою очередь, отразилось на API. В то время как Universal Analytics Reporting API оперировал сессиями и просмотрами страниц, GA4 Data API построен на событийно-ориентированной модели. Это означает, что все взаимодействия пользователя (просмотры страниц, клики, покупки) теперь являются событиями.

Ключевые различия включают:

  • Модель данных: UA основан на сессиях и хитах; GA4 — на событиях.

  • Метрики и параметры: Названия и доступность метрик и параметров значительно изменились. Например, pageviews в UA соответствует screenPageViews в GA4, а users в UA теперь activeUsers или totalUsers в GA4.

  • Структура запросов: GA4 Data API предлагает более гибкую структуру запросов с акцентом на события и их параметры, что требует переосмысления подходов к получению данных.

Практические примеры получения данных из GA4 API

Опираясь на полученные учетные данные и установленные клиентские библиотеки, рассмотрим, как выполнять запросы к GA4 Data API для извлечения ключевых метрик и параметров. Примеры ниже демонстрируют базовые сценарии получения данных.

Пример 1: Запрос общих просмотров страницы и активных пользователей

Этот пример показывает, как получить общее количество просмотров страниц и активных пользователей за последние 7 дней.

PHP:

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Metric;

$client = new BetaAnalyticsDataClient(['credentials' => 'path/to/your/credentials.json']);
$response = $client->runReport([
    'property' => 'properties/' . GA_PROPERTY_ID,
    'dateRanges' => [new DateRange(['startDate' => '7daysAgo', 'endDate' => 'today'])],
    'metrics' => [new Metric(['name' => 'screenPageViews']), new Metric(['name' => 'activeUsers'])],
]);
// Обработка $response

Python:

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Metric

client = BetaAnalyticsDataClient(credentials_json='path/to/your/credentials.json')
response = client.run_report(
    property=f"properties/{GA_PROPERTY_ID}",
    date_ranges=[DateRange(start_date="7daysAgo", end_date="today")],
    metrics=[Metric(name="screenPageViews"), Metric(name="activeUsers")],
)
# Обработка response

Пример 2: Получение списка самых популярных страниц за период

Этот пример демонстрирует, как получить список 10 самых популярных страниц (по просмотрам) за последние 30 дней.

PHP:

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;

$client = new BetaAnalyticsDataClient(['credentials' => 'path/to/your/credentials.json']);
$response = $client->runReport([
    'property' => 'properties/' . GA_PROPERTY_ID,
    'dateRanges' => [new DateRange(['startDate' => '30daysAgo', 'endDate' => 'today'])],
    'dimensions' => [new Dimension(['name' => 'pagePath'])],
    'metrics' => [new Metric(['name' => 'screenPageViews'])],
    'orderBys' => [new OrderBy(['metric' => ['metricName' => 'screenPageViews'], 'desc' => true])],
    'limit' => 10,
]);
// Обработка $response

Python:

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, OrderBy

client = BetaAnalyticsDataClient(credentials_json='path/to/your/credentials.json')
response = client.run_report(
    property=f"properties/{GA_PROPERTY_ID}",
    date_ranges=[DateRange(start_date="30daysAgo", end_date="today")],
    dimensions=[Dimension(name="pagePath")],
    metrics=[Metric(name="screenPageViews")],
    order_bys=[OrderBy(metric=OrderBy.MetricOrderBy(metric_name="screenPageViews"), desc=True)],
    limit=10,
)
# Обработка response

Пример 1: Запрос общих просмотров страницы и активных пользователей (PHP/Python)

Для получения базовых метрик, таких как общее количество просмотров страниц (screenPageViews) и активных пользователей (activeUsers), можно использовать следующий код. Предполагается, что клиентская библиотека инициализирована с учетными данными сервисного аккаунта, как описано ранее.

PHP Пример:

use Google\Analytics\Data\V1beta\RunReportRequest;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\DateRange;

// ... $client инициализирован

$request = (new RunReportRequest())
    ->setProperty('properties/' . GA_PROPERTY_ID)
    ->setDateRanges([
        new DateRange(['start_date' => '2026-03-01', 'end_date' => '2026-03-24'])
    ])
    ->setMetrics([
        new Metric(['name' => 'screenPageViews']),
        new Metric(['name' => 'activeUsers'])
    ]);

$response = $client->runReport($request);

foreach ($response->getRows() as $row) {
    echo 'Просмотры страниц: ' . $row->getMetricValues()[0]->getValue() . "\n";
    echo 'Активные пользователи: ' . $row->getMetricValues()[1]->getValue() . "\n";
}

Python Пример:

from google.analytics.data_v1beta.types import DateRange, Metric, RunReportRequest

# ... client инициализирован

request = RunReportRequest(
    property=f"properties/{GA_PROPERTY_ID}",
    date_ranges=[DateRange(start_date="2026-03-01", end_date="2026-03-24")],
    metrics=[Metric(name="screenPageViews"), Metric(name="activeUsers")],
)

response = client.run_report(request)

for row in response.rows:
    print(f"Просмотры страниц: {row.metric_values[0].value}")
    print(f"Активные пользователи: {row.metric_values[1].value}")

В обоих примерах мы запрашиваем данные за указанный период, получая общее количество просмотров страниц и активных пользователей.

Пример 2: Получение списка самых популярных страниц за период (PHP/Python)

Для получения списка самых популярных страниц за определенный период, мы расширим наш запрос, добавив параметр pagePath и отсортировав результаты по метрике screenPageViews в убывающем порядке. Это позволит идентифицировать наиболее просматриваемые страницы вашего ресурса GA4.

Пример на PHP:

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\RunReportRequest;

// ... (инициализация клиента, как в предыдущем примере)

$request = (new RunReportRequest())
    ->setProperty('properties/' . GA_PROPERTY_ID)
    ->setDateRanges([
        (new DateRange())
            ->setStartDate('2026-03-01')
            ->setEndDate('today')
    ])
    ->setDimensions([
        (new Dimension())->setName('pagePath')
    ])
    ->setMetrics([
        (new Metric())->setName('screenPageViews')
    ])
    ->setOrderBys([
        (new OrderBy())
            ->setMetric((new MetricOrderBy())->setMetricName('screenPageViews'))
            ->setDesc(true)
    ]);

$response = $client->runReport($request);

foreach ($response->getRows() as $row) {
    printf("%s: %s\n", $row->getDimensionValues()[0]->getValue(), $row->getMetricValues()[0]->getValue());
}

Пример на Python:

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest, OrderBy, MetricOrderBy

# ... (инициализация клиента, как в предыдущем примере)

request = RunReportRequest(
    property=f"properties/{GA_PROPERTY_ID}",
    date_ranges=[
        DateRange(start_date="2026-03-01", end_date="today")
    ],
    dimensions=[
        Dimension(name="pagePath")
    ],
    metrics=[
        Metric(name="screenPageViews")
    ],
    order_bys=[
        OrderBy(metric=MetricOrderBy(metric_name="screenPageViews"), desc=True)
    ]
)

response = client.run_report(request)

for row in response.rows:
    print(f"{row.dimension_values[0].value}: {row.metric_values[0].value}")

Распространенные проблемы и лучшие практики интеграции

При работе с GA4 Data API важно учитывать потенциальные проблемы. Эффективная обработка ошибок, таких как превышение квот или неверные запросы, критична для стабильности. Регулярно проверяйте квоты в Google Cloud Console. Для безопасности всегда храните учетные данные (GA_CLIENT_EMAIL, GA_PRIVATE_KEY) в переменных окружения или защищенных хранилищах, избегая их прямого включения в код. Оптимизируйте запросы, запрашивая только необходимые метрики и параметры, чтобы минимизировать нагрузку и количество вызовов API.

Обработка ошибок и управление квотами API

При работе с GA4 Data API важно предусмотреть обработку ошибок. Используйте try-catch блоки для перехвата исключений и анализируйте коды ошибок (например, 400 для неверного запроса, 401 для аутентификации, 403 для превышения квоты). Управление квотами API критически важно для стабильной работы. Отслеживайте их в Google Cloud Console. Для предотвращения превышения квот применяйте кэширование данных, объединяйте запросы и используйте экспоненциальную задержку при повторных попытках.

Безопасное хранение учетных данных и оптимизация запросов

Для безопасного хранения учетных данных сервисного аккаунта (GA_CLIENT_EMAIL, GA_PRIVATE_KEY) категорически не рекомендуется жесткое кодирование в коде. Используйте переменные окружения, файлы конфигурации, не включенные в систему контроля версий, или специализированные сервисы управления секретами, такие как Google Secret Manager. Это минимизирует риски утечки.

Оптимизация запросов к API включает в себя:

  • Запрашивайте только необходимые метрики и параметры.

  • Используйте кэширование данных для часто запрашиваемых отчетов, чтобы уменьшить количество вызовов API и избежать превышения квот.

Заключение

Мы подробно рассмотрели процесс подключения к Google Analytics Data API (GA4), начиная с начальной настройки в Google Cloud и GA4, получения учетных данных и установки клиентских библиотек. Вы освоили ключевые концепции API, научились выполнять запросы для получения ценных данных и ознакомились с лучшими практиками интеграции. Использование GA4 Data API открывает широкие возможности для автоматизации сбора аналитики, создания кастомных отчетов и интеграции данных в ваши приложения, позволяя принимать более обоснованные решения на основе актуальной информации.

Метки:

Добавить комментарий

Реклама
Полное руководство: Как удалить NaN из Pandas DataFrame на Python с помощью dropna()
NaN (Not a Number) — это не просто «пустое место» в таблице; это стандартизированный маркер, который Pandas и NumPy используют для обозначения отсутствующих, неизвестных или некорректных числовых данных.
  •  2
  •   2026
NumPy: Как изменить форму массива данных в Python – Подробное руководство по reshape
В мире анализа данных и машинного обучения работа с числовыми данными почти всегда подразумевает использование массивов.
  •  2
  •   2026
Pandas DataFrame: Как эффективно проверить существование индекса строки или столбца
В мире анализа данных с использованием Python и библиотеки Pandas, работа с табличными структурами данных — это ежедневная рутина.
  •  2
  •   2026