Firebase 和 Google Analytics

Adapty 可以将订阅事件（购买、续订、退款、试用开始等）发送到 Firebase 和 Google Analytics，一次集成即可将数据同时传递到两个平台。

购买和退款事件会附带收入、货币和产品详情。同样的数据会同时流入 Firebase 的移动端工具（受众群体、Remote Config 等）以及 Google Analytics 的报告。

这是一个数据分析集成，而非 Google Ads 归因工具——请参阅限制条件。

通过此集成可以实现什么

Adapty 按 subscription_state（subscribed、active_trial、never_subscribed 等）对用户进行分组，并将订阅生命周期事件转发至 Firebase 和 Google Analytics。

• 目标受众：在 Firebase 和 Google Analytics 中构建订阅者目标受众，用于外部渠道——Google Ads 再营销、FCM 活动、相似受众建模。
• Google Ads 转化 （Google Analytics）：将 purchase 和 refund 用作 Google Ads 转化目标。
• Firebase Remote Config：无需更新应用即可更改使用限制、文案或功能开关，并根据订阅状态设置条件。（请勿与Adapty 远程配置混淆，后者用于配置流程/付费墙内容。）
• Cloud Messaging：在应用关闭时向流失订阅者推送通知。
• 跨设备追踪 （Google Analytics）：Adapty 将 customer_user_id 发送至 Google Analytics，使 Google Ads 能够跨设备追踪同一用户。
• 转化漏斗 （Google Analytics）：查看用户在转化或流失前在应用内的行为路径。
• 趋势预测：根据购买历史预测流失率和消费情况。
• A/B 测试：在订阅者同期群上测试应用功能——例如，向试用用户推出新的导航模式并衡量会话时长。（如需测试付费墙实验变体，请使用 Adapty A/B 测试。）

集成工作原理

1. 当用户首次打开您的应用时，Firebase SDK 会为该安装创建一个唯一标识符——Firebase App Instance ID。Firebase 和 Google Analytics 使用此 ID 来识别每个事件对应的安装来源。
2. 您的应用将 Firebase App Instance ID 传递给 Adapty SDK，Adapty 将用户的用户画像与该 Firebase 安装关联起来。
3. 当用户完成购买时，Adapty 服务器会将事件连同 Firebase App Instance ID 一起转发给 Firebase。数据通过服务器之间直接交换，不经过应用本身。
4. Firebase 将购买事件与对应的安装匹配，这样您就能在看板中看到购买行为与用户在应用内其他操作的完整关联。

Stripe 购买

Stripe 购买仅在买家首先启动移动应用后才会到达 Firebase。Firebase App Instance ID 必须在 Stripe 购买触发之前完成设置。

对于 App Store 和 Play Store 的购买，这一过程会自动完成。它们发生在移动应用内部，与 setIntegrationIdentifier 调用同步进行。因此在购买触发时，Firebase ID 已经存在。 Stripe 购买在应用外部、在你的服务器上发起。你的移动应用必须在启动时调用 setIntegrationIdentifier——在任何 Stripe 购买触发之前。否则 Adapty 没有可附加的 ID，Stripe 购买就永远不会到达 Firebase。

局限性

• 不是 Google Ads 归因工具。 此集成将 Adapty 事件发送到 Firebase 和 Google Analytics 用于数据分析，不会将应用安装归因到 Google Ads 广告系列（UAC / Universal App Campaigns），也无法区分付费流量与自然流量。如需安装归因，请使用 Adapty 内置的 Adapty 归因功能。
• 不支持历史数据回填。 Adapty 仅从启用集成之时起转发事件——过去的购买、续订和退款不会同步到 Firebase。（历史数据保存在 Adapty 的 S3 / GCS 导出中，但将其导入 Firebase 不在本集成的支持范围内。）
• 纯 Web 买家的数据不会进入 Firebase。 Adapty 通过移动应用设置的 Firebase App Instance ID 将购买事件转发至 Firebase。从未安装过应用的买家没有该 ID，其购买记录不会进入 Firebase。详见上文 Stripe 购买，也可考虑使用 FunnelFox 的 Firebase 集成或 Google Analytics Web 数据流进行 Web 端追踪。
• 不支持 Paddle 购买。 本集成目前不支持 Paddle。Paddle 购买记录保留在 Adapty Analytics 中，不会通过此路径同步到 Firebase。
• Stripe 购买受 Stripe 特有限制约束。 详见 Stripe 集成限制。

配置说明

配置 Firebase

1. 打开 Firebase 控制台，选择或新建一个项目。为了避免沙盒事件污染生产环境数据，建议为开发构建单独创建一个 Firebase 项目。

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 填入 Adapty 的 Firebase 集成配置中。

   

配置 Adapty

1. 在 Adapty 看板中打开 Integrations > Firebase。

2. 开启 Firebase integration 开关。

3. 为每个发布平台填写凭据。Adapty 需要每个平台的 Firebase App ID 和 Google Analytics secret——iOS、Android 和 Stripe 各自的值不同。

   Adapty 看板	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 下拉菜单：可选总收入、扣除商店佣金后的收入，或扣除商店佣金和税费后的收入。
  • 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 个字符，属性值最多 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，并通过 setIntegrationIdentifier 将其传递给 Adapty。每次应用启动时执行一次，且须在任何购买流程开始之前完成。

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。事件会在几秒内显示，并附带所有参数。

标准报告——实时报告、报表、目标受众——会在几分钟到 24 小时内填充，具体取决于报告类型。DebugView 是唯一能实时确认事件的地方。

在报告和目标受众中使用订阅数据

在 Adapty 看板中开启 Send user properties（配置 Adapty，第 4 步）。若未开启，Adapty 不会转发 subscription_state 或 subscription_product_id，本节其余内容将不会生效。 默认情况下，Firebase 和 Google Analytics 不会公开用户属性。需要将每个属性注册为自定义维度，这样 subscription_state 和 subscription_product_id 才能在报告、探索和受众中使用。请在 Google Analytics 管理后台配置维度。配置完成后，即可在 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，并会产生报错。
• 请确认 Firebase Console 中关联的 Google Analytics 媒体资源与数据流匹配。
• 请确认 Adapty 中设置的凭据（ID + 密钥）与平台相匹配。

access_level_updated 在事件流中显示为失败

access_level_updated 是一个仅限 webhook 的事件。Adapty 不会尝试将其推送至 Firebase——但事件流仍会将其列为推送失败。忽略该条目即可，你的集成一切正常。如需使用此事件，请配置 webhook 集成。

沙盒事件污染生产数据

Adapty 会将沙盒和生产环境的交易都转发到同一个 Firebase 项目。参见配置 Firebase——为开发构建使用独立的 Firebase 项目可以从根本上避免这一问题。

Firebase 对 StoreKit 2 应用的收入统计不足

Firebase 会为每笔 StoreKit 1 购买自动记录一个 in_app_purchase 事件，无需任何代码。而 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 项目，以便与生产数据隔离。
• 采样：Google Analytics Explorations 会对大型数据集进行采样。如需未采样的统计数据，请查看实时视图或标准报告。

自定义事件名称被 Google Analytics 拒绝

Google Analytics 对事件名称有限制：最多 40 个字符，只允许字母、数字和下划线，且必须以字母开头。请在看板中将不符合上述规则的自定义 Adapty 事件重命名。