Подключение Firebase Analytics к Delphi-приложениям

Сбор данных о поведении пользователей стал обязательной частью коммерческой разработки. Мобильные и настольные программы, созданные на Delphi с использованием FireMonkey, охватывают несколько платформ одновременно, поэтому владельцу проекта требуется единый инструмент для аналитики. Firebase от Google закрывает эту задачу благодаря бесплатному тарифу, мультиплатформенной совместимости и понятной панели отчётов.

Интеграция сервиса в проекты на Pascal требует понимания особенностей Measurement Protocol — REST-интерфейса, через который сторонние приложения передают события. Такой способ отправки не привязан к нативным SDK, что позволяет применять один и тот же исходный код для Android, iOS, Windows и macOS. Дальше разобраны ключевые этапы реализации: от регистрации проекта до валидации данных.

Регистрация проекта в консоли Firebase

Перед началом разработки необходимо завести аккаунт Google и добавить его в Firebase. В мастере выбирается пункт «Создать проект», указывается название и глобальный идентификатор, после чего активируется Google Analytics. Система связывает ресурс с существующим аккаунтом BigQuery, если требуется экспорт сырых данных для собственных отчётов.

После активации аналитики Firebase выдаёт два ключевых значения: API Secret и Firebase App ID. App ID имеет вид 1:1234567890:web:abcdef1234567890, а секрет измерений — набор из 32 символов. Эти строки потребуются программе для авторизации запросов к серверу Google.

Дополнительно стоит включить Google Signals для получения демографических срезов и активировать связь с Google Ads, если планируется рекламная аналитика. На этапе настройки полезно задать правила Data Stream: имя потока, часовой пояс и валюту, в которой будут считаться доходы. Корректно заполненные параметры исключают ошибки интерпретации данных в дальнейшем.

Архитектура Measurement Protocol

Measurement Protocol представляет собой HTTP-эндпоинт, принимающий POST-запросы с полезной нагрузкой в формате JSON. Для GA4 основной адрес — https://www.google-analytics.com/mp/collect, валидационный — https://www.google-analytics.com/debug/mp/collect. Запрос состоит из query-параметров measurement_id и api_secret плюс тело с массивом объектов событий.

Каждое событие описывается объектом с полем name и словарём params. Словарь содержит как стандартные параметры GA4 (engagement_time_msec, session_id), так и пользовательские значения. Для идентификации пользователя передаётся client_id — анонимный идентификатор, который приложение генерирует при первом запуске и сохраняет в локальных настройках.

Существенной особенностью протокола является пакетная отправка: до 25 событий объединяются в один запрос. Это снижает энергопотребление на мобильных устройствах и сглаживает задержки при нестабильной сети. В Delphi-проектах пакетирование реализуется через буфер в памяти или локальную базу SQLite, откуда рабочий поток отправляет данные каждые 60 секунд.

Программная отправка событий из кроссплатформенного кода

В стандартной библиотеке Delphi доступны решения для HTTP-запросов разной степени сложности. Каждое из них подходит для интеграции Firebase, но отличается по удобству, кроссплатформенности и поддержке асинхронных вызовов.

Компонент	Платформы	Асинхронность	TLS по умолчанию	Размер зависимостей
TNetHTTPClient	Все основные	Да (BeginExecute)	Да	Минимальный
Indy (TIdHTTP)	Все основные	Через потоки	Включается вручную	Средний
REST Client Components	Все основные	Да	Да	Минимальный
ICS (Overbyte)	Windows, macOS	Да	Включается вручную	Большой

TNetHTTPClient из System.Net.HttpClient — оптимальный выбор для проектов на FireMonkey. Он работает на всех целевых платформах, корректно взаимодействует с современными сертификатами и предоставляет удобный механизм асинхронных вызовов через OnReceiveData и BeginExecute. Для простых сценариев подходят также REST Client Components из поставки Delphi, однако их настройка JSON-сериализации менее гибкая.

Пример отправки события login:

var
  LClient: TNetHTTPClient;
  LResponse: IHTTPResponse;
  LJSON: TJSONObject;
  LEvents: TJSONArray;
  LEvent: TJSONObject;
begin
  LClient := TNetHTTPClient.Create(nil);
  try
    LJSON := TJSONObject.Create;
    try
      LEvents := TJSONArray.Create;
      LEvent := TJSONObject.Create;
      LEvent.AddPair('name', 'login');
      LEvent.AddPair('params', TJSONObject.Create.AddPair('method', 'email'));
      LEvents.Add(LEvent);
      LJSON.AddPair('client_id', GetClientID);
      LJSON.AddPair('events', LEvents);

      LClient.ContentType := 'application/json';
      LResponse := LClient.Post(
        'https://www.google-analytics.com/mp/collect?measurement_id=G-XXXX&api_secret=Y',
        LJSON.ToJSON,
        nil,
        TStringStream.Create('')
      );
    finally
      LJSON.Free;
    end;
  finally
    LClient.Free;
  end;
end;

Для повышения надёжности в рабочем коде добавляется обработка исключений, повторные попытки при сетевых сбоях и сохранение событий в очередь при отсутствии соединения.

Типы событий и работа с пользовательскими параметрами

GA4 различает автоматически собираемые события (first_open, session_start, app_remove) и пользовательские, которые разработчик определяет самостоятельно. Стандартный набор рекомендуемых событий описан в справке Google и покрывает типовые сценарии: вход в систему, прохождение уровня, совершение покупки. Применение рекомендуемых имён улучшает совместимость с будущими отчётами и упрощает сегментацию аудитории.

Пользовательские параметры позволяют передавать до 25 пар ключ-значение на одно событие. Имена параметров должны соответствовать правилам Google: латиница, цифры, подчёркивание, длина до 40 символов. Значения ограничены 100 символами для строк и 40 байтами для чисел. В Delphi удобно создать справочник констант с именами событий и параметров, что снижает количество опечаток и упрощает рефакторинг.

Для расширения возможностей сегментации применяются свойства пользователя (user_properties). Через них передаются статичные характеристики: тип подписки, уровень приложения, выбранный язык интерфейса. Эти сведения обновляются реже, чем события, и применяются для построения аудиторий в рекламных кампаниях и персонализации контента.

Валидация, обработка ошибок и оптимизация

Перед выходом на реальных пользователей полезно проверять запросы через валидационный эндпоинт https://www.google-analytics.com/debug/mp/collect. Этот адрес возвращает расширенный JSON со списком найденных проблем: неверные имена параметров, превышение допустимого размера, ошибки формата. Интеграция валидации в процесс разработки экономит часы отладки в консоли Firebase.

Типичные ошибки связаны с пропуском обязательных полей, использованием зарезервированных имён и неправильной кодировкой строк. Последняя проблема часто проявляется при ручном формировании JSON: Delphi по умолчанию отдаёт строки в UTF-8, но некоторые HTTP-компоненты перекодируют тело запроса в ISO-8859-1. Решением служит принудительная установка заголовка Content-Type: application/json; charset=utf-8 и проверка содержимого перед отправкой.

Для мобильных платформ важна фоновая отправка. На Android события накапливаются в локальной базе, поток отправки запускается через WorkManager или Foreground Service. На iOS применяется BGTaskScheduler с идентификатором задачи. Такая схема снижает расход батареи и работает при закрытом приложении. При этом соблюдаются ограничения Firebase на одного пользователя: не более 500 событий в день на client_id, что на практике достигается редко.

Дополнительно стоит заранее спроектировать стратегию согласия пользователя. В соответствии с GDPR и аналогичными регламентами аналитика должна отключаться до получения разрешения. В Delphi реализуется флаг в настройках приложения, блокирующий формирование событий и отправку данных. После получения согласия флаг снимается, и накопленные сведения синхронизируются с сервером.