Firebase и Google Analytics

Adapty может передавать события подписок — покупки, продления, возвраты, запуски пробных периодов — в Firebase и Google Analytics, так что одна интеграция доставляет данные сразу в оба сервиса.

События покупки и возврата приходят вместе с данными о выручке, валюте и продукте. Те же данные используются в инструментах Firebase для мобильных приложений (Audiences, Remote Config и т. д.) и в отчётах Google Analytics.

Это интеграция для аналитики, а не инструмент атрибуции через Google Ads — см. Ограничения.

Что даёт эта интеграция

Adapty группирует пользователей по subscription_state (subscribed, active_trial, never_subscribed и т. д.) и передаёт события жизненного цикла подписки в Firebase и Google Analytics.

• Audiences: Создавайте аудитории подписчиков в Firebase и Google Analytics для внешних каналов — ретаргетинга в Google Ads, FCM-кампаний, построения похожих аудиторий.
• Конверсии Google Ads (Google Analytics): Используйте purchase и refund как цели конверсии в Google Ads.
• Firebase Remote Config: Меняйте лимиты использования, тексты или флаги функций без обновления приложения — задавайте условия на основе статуса подписки. (Не путайте с Adapty Remote Config, который настраивает содержимое флоу и пейволов.)
• Cloud Messaging: Push-уведомления отписавшимся пользователям, когда приложение закрыто.
• Кросс-девайсное отслеживание (Google Analytics): Adapty передаёт customer_user_id в Google Analytics, чтобы Google Ads мог отслеживать одного и того же пользователя на разных устройствах.
• Воронки конверсий (Google Analytics): Смотрите, что пользователи делали в приложении перед конверсией или оттоком.
• Прогнозы: Прогнозируйте отток и расходы на основе истории покупок.
• A/B-тестирование: Тестируйте функции приложения на когортах подписчиков — например, выкатывайте новый паттерн навигации пользователям в триале и измеряйте продолжительность сессий. (Для тестирования вариантов пейволов используйте A/B-тесты Adapty.)

Как работает интеграция

1. Когда пользователь впервые открывает ваше приложение, Firebase SDK создаёт уникальный идентификатор для этой установки — Firebase App Instance ID. Firebase и Google Analytics используют его, чтобы определить, с какой установки пришло то или иное событие.
2. Ваше приложение передаёт Firebase App Instance ID в SDK Adapty. Adapty связывает профиль пользователя с этой установкой Firebase.
3. Когда пользователь совершает покупку, серверы Adapty пересылают событие в Firebase, прикрепляя Firebase App Instance ID. Данные передаются между серверами, минуя приложение.
4. Firebase сопоставляет покупку с установкой, и вы видите покупки рядом со всеми остальными действиями пользователя в приложении.

Покупки через Stripe

Покупка через Stripe попадает в Firebase только если покупатель сначала открыл ваше мобильное приложение. Firebase App Instance ID должен быть установлен до того, как произойдёт покупка через Stripe.

Для покупок через App Store и Play Store это происходит автоматически. Они совершаются внутри мобильного приложения вместе с вызовом setIntegrationIdentifier. Firebase ID уже присутствует в момент покупки. Покупки Stripe инициируются за пределами приложения — на вашем сервере. Мобильное приложение должно вызывать setIntegrationIdentifier при запуске — до того, как произойдёт любая покупка через Stripe. Иначе у Adapty не будет идентификатора для привязки, и покупка через Stripe никогда не попадёт в Firebase.

Ограничения

• Это не инструмент атрибуции Google Ads. Интеграция отправляет события Adapty в Firebase и Google Analytics для аналитики. Она не атрибутирует установки приложения к кампаниям Google Ads (UAC / Universal App Campaigns) и не разделяет платный и органический трафик. Для атрибуции установок используйте встроенную атрибуцию Adapty.
• Нет ретроактивной загрузки данных. Adapty передаёт события с момента включения интеграции — прошлые покупки, продления и возвраты в Firebase не попадают. (Исторические данные хранятся в экспортах Adapty S3 / GCS, но их импорт в Firebase этой интеграцией не предусмотрен.)
• Покупатели только через веб не попадают в Firebase. Adapty передаёт покупки в Firebase через Firebase App Instance ID, который устанавливает ваше мобильное приложение. У покупателей, которые никогда не устанавливали приложение, нет этого ID — их покупки в Firebase не поступают. Подробнее — в разделе Покупки через Stripe выше. Рассмотрите интеграцию FunnelFox с Firebase или веб-поток данных Google Analytics для отслеживания веб-покупок.
• Покупки через Paddle не поддерживаются. Интеграция пока не работает с Paddle. Покупки через Paddle остаются в Adapty Analytics и через этот путь в Firebase не передаются.
• Покупки через Stripe наследуют ограничения Stripe. См. ограничения интеграции со Stripe.

Инструкция по настройке

Настройка Firebase

1. Откройте Firebase Console и выберите или создайте проект. Чтобы производственная аналитика не смешивалась с событиями из песочницы, используйте отдельный проект Firebase для dev-сборок.

2. Привяжите проект к свойству Google Analytics. Firebase предложит это при создании проекта, или добавьте позже через Project settings > Integrations > Google Analytics.

   

3. В разделе Project settings > General > Your apps добавьте запись для каждой платформы, на которой работает ваше приложение (iOS / Android / Web). Для Stripe добавьте запись для Web-приложения — отдельного типа для Stripe нет. Каждая запись генерирует уникальный Firebase App ID и соответствующий поток данных в Google Analytics. Этот ID нужно будет вставить в настройки интеграции Firebase в Adapty во время настройки.

   

Настройка Adapty

1. Откройте Integrations > Firebase в дашборде Adapty.

2. Включите переключатель Firebase integration.

3. Введите учётные данные для каждой платформы, на которой работает ваше приложение. Adapty требует Firebase App ID и Google Analytics secret для каждой платформы — значения отличаются для iOS, Android и Stripe.

   Adapty Dashboard	Google Analytics	Где найти
   Firebase App ID	App ID	Firebase Console > Project settings > General > Your apps
   Google Analytics secret	Measurement Protocol API secret	Google Analytics > Admin > Data streams > Measurement Protocol API secrets > Create

   

4. Настройте, как Adapty передаёт данные о доходах и пользователях. Четыре параметра расположены в одной строке на дашборде:

• Выпадающий список Revenue definition: Gross revenue, Proceeds after store commission или Proceeds after store commission and taxes.
  • Переключатель Send user properties: когда включён, события содержат subscription_state и subscription_product_id. Чтобы использовать их в отчётах или аудиториях, см. Использование данных о подписке в отчётах.
  • Переключатель Report user’s currency: когда включён, Adapty конвертирует локальную валюту каждой транзакции в валюту отчётности вашего аккаунта перед отправкой в Google Analytics.
  • Переключатель Send trial price: старты триала ценны — большинство платящих пользователей начинают именно с триала. Но оптимизация ставок в Google Ads учитывает только события с выручкой. Включите этот переключатель, чтобы присвоить каждому триалу условную цену — тогда Google будет воспринимать их как конверсии и оптимизировать расходы на рекламу в пользу привлечения пользователей, запускающих триал. При включении появляется поле Trial price percentage. Укажите долю от полной цены подписки, которую Google должен засчитывать за каждый триал — например, 50% означает, что в период триала будет передаваться половина стоимости подписки.

5. Сопоставьте события Adapty с названиями событий Firebase/Google Analytics. Adapty предоставляет отдельные таблицы соответствия событий для iOS и Android, поэтому вы можете использовать разные названия для каждой платформы. Покупки через Stripe используют таблицу событий iOS — отдельной таблицы для Stripe нет. Google Analytics накладывает жёсткие ограничения протокола Measurement Protocol: не более 40 символов в названии события, 24 символов в названии user-свойства и 36 символов в значении. Если лимит превышен, Google Analytics молча удаляет такие события.

6. Нажмите Save. Adapty начнёт отправлять события в Firebase в течение нескольких минут.

Настройте код вашего приложения

Adapty необходимо передавать Firebase App Instance ID с каждым событием — иначе ничего не попадёт в Firebase (MISSING_INTEGRATION_ID).

После вызовов FirebaseApp.configure() и Adapty.activate() запросите у Firebase SDK App Instance ID и передайте его в Adapty через setIntegrationIdentifier. Выполняйте это один раз при каждом запуске приложения, до начала любого флоу покупки.

FirebaseApp.configure()

if let appInstanceId = Analytics.appInstanceID() {
    do {
        try await Adapty.setIntegrationIdentifier(.firebaseAppInstanceId(appInstanceId))
    } catch {
        // handle the error
    }
}

FirebaseApp.configure()

if let appInstanceId = Analytics.appInstanceID() {
    do {
        try await Adapty.setIntegrationIdentifier(
            key: "firebase_app_instance_id",
            value: appInstanceId
        )
    } catch {
        // handle the error
    }
}

// after Adapty.activate()

FirebaseAnalytics.getInstance(context).appInstanceId.addOnSuccessListener { appInstanceId ->
    Adapty.setIntegrationIdentifier("firebase_app_instance_id", appInstanceId) { error ->
        if (error != null) {
            // handle the error
        }
    }
}

// after Adapty.activate()

FirebaseAnalytics.getInstance(context).getAppInstanceId().addOnSuccessListener(appInstanceId -> {
    Adapty.setIntegrationIdentifier("firebase_app_instance_id", appInstanceId, error -> {
        if (error != null) {
            // handle the error
        }
    });
});

final appInstanceId = await FirebaseAnalytics.instance.appInstanceId;

if (appInstanceId != null) {
    try {
        await Adapty().setIntegrationIdentifier(
            key: "firebase_app_instance_id",
            value: appInstanceId,
        );
    } on AdaptyError catch (adaptyError) {
        // handle the error
    } catch (e) {
        // handle the error
    }
}

using AdaptySDK;
using Firebase.Analytics;

FirebaseAnalytics
    .GetAnalyticsInstanceIdAsync()
    .ContinueWithOnMainThread((task) => {
        if (!task.IsCompletedSuccessfully) {
            // handle the error
            return;
        }

        Adapty.SetIntegrationIdentifier(
            "firebase_app_instance_id",
            task.Result,
            (error) => {
                // handle the error
            }
        );
    });

try {
    const appInstanceId = await analytics().getAppInstanceId();
    if (appInstanceId) {
        await adapty.setIntegrationIdentifier("firebase_app_instance_id", appInstanceId);
    }
} catch (error) {
    // handle `AdaptyError`
}

Проверка интеграции

Самый быстрый способ убедиться, что события поступают — Firebase DebugView:

1. На тестовом устройстве запустите приложение с включённым режимом отладки Firebase.
2. Совершите покупку в песочнице или вызовите любое событие, которое вы включили в дашборде Adapty.
3. Откройте Firebase Console > Analytics > DebugView. События появляются в течение нескольких секунд вместе со всеми параметрами.

Стандартные отчёты — Realtime, Reports, аудитории — заполняются в течение нескольких минут до 24 часов в зависимости от типа отчёта. DebugView — единственное место, где можно подтвердить это в реальном времени.

Используйте данные о подписках в отчётах и аудиториях

Включите Send user properties в дашборде Adapty (Настройте Adapty, шаг 4). Без этого Adapty не будет передавать subscription_state и subscription_product_id — и всё описанное в этом разделе работать не будет. По умолчанию Firebase и Google Analytics не раскрывают пользовательские свойства. Зарегистрируйте каждое из них как пользовательское измерение — тогда subscription_state и subscription_product_id станут доступны в отчётах, Explorations и аудиториях. Настройте измерения в Google Analytics Admin. После этого их можно запрашивать как в Firebase, так и в Google Analytics — они используют общий бэкенд.

Это удобно для создания аудиторий Google Ads из платящих пользователей или для обучения прогностических моделей.

После завершения настройки Adapty будет заполнять эти свойства для новых событий. Существующие события обновлены не будут.

1. В Google Analytics откройте Admin > Custom definitions.
   
2. Нажмите Create custom dimensions.
3. Для каждого свойства задайте:
   • Dimension name: любое понятное название, например «Subscription state».
   • Scope: User.
   • User property: subscription_state или subscription_product_id. Название должно совпадать точь-в-точь — Google Analytics чувствителен к регистру.

Устранение неполадок

События не появляются в Firebase

• Убедитесь, что Firebase App Instance ID задан до первой покупки. События без Firebase ID не попадают в Firebase и возвращают ошибку.
• Убедитесь, что свойство Google Analytics, привязанное в Firebase Console, соответствует потоку данных.
• Убедитесь, что набор учётных данных (ID + секрет) в Adapty соответствует платформе.

access_level_updated отображается как сбой в Event Feed

access_level_updated — это событие только для вебхуков. Adapty никогда не пытается отправить его в Firebase — но Event Feed всё равно отображает его как неудачную доставку. Игнорируйте эту строку. Ваша интеграция работает корректно. Чтобы использовать это событие, настройте интеграцию с вебхуком.

События из песочницы загрязняют продакшен-данные

Adapty пересылает транзакции из песочницы и продакшена в один и тот же проект Firebase. См. раздел Настройка Firebase — использование отдельного проекта Firebase для сборок разработки полностью решает эту проблему.

Firebase недосчитывает доходы в приложениях на StoreKit 2

Firebase автоматически логирует событие in_app_purchase для каждой покупки через StoreKit 1 — без какого-либо кода. StoreKit 2 использует другой API. Firebase просто не видит эти транзакции.

Последствия: приложения, активно использующие SK2 и не имеющие отдельного пайплайна для учёта доходов, занижают показатели вдвое и более — в Firebase, в Google Analytics и во всех последующих кампаниях Google Ads. Оптимизация ставок работает с неверными данными. Отчёты о доходах показывают лишь половину картины. Исправление: передайте firebase_app_instance_id в Adapty (см. Настройте код приложения). Adapty передаёт каждую покупку через Measurement Protocol — с информацией о доходе, валюте и продукте.

Расхождение данных между Adapty Analytics и Firebase

• StoreKit 2: Самая частая причина. См. Firebase занижает доходы для приложений на StoreKit 2.
• Охват SDK: Firebase считает только события от пользователей, чьё приложение передаёт Firebase App Instance ID. Старые версии приложения этого не делают. Adapty учитывает таких пользователей, Firebase — нет.
• События песочницы: Adapty также пересылает транзакции песочницы в Firebase. Чтобы не смешивать данные, используйте отдельный проект Firebase для dev-сборок.
• Семплирование: Google Analytics Explorations применяет семплирование к большим наборам данных. Для точных цифр без семплирования проверяйте данные в режиме реального времени или в стандартных отчётах.

Пользовательские названия событий отклоняются Google Analytics

Google Analytics ограничивает названия событий 40 символами: допустимы только буквы, цифры и символы подчёркивания, причём название должно начинаться с буквы. Переименуйте пользовательские события Adapty в дашборде, которые не соответствуют этим требованиям.