企业官网建设流程全解析

• 示例工程

本指南以仓库中的 analytics/README.md 为骨架，结合 analytics 模块的完整源码，系统讲解如何在 Android 应用中接入 Google Analytics for Firebase：从工程初始化、依赖配置，到获取FirebaseAnalytics实例、记录SELECT_CONTENT/ 自定义事件、上报用户属性、手动埋点屏幕浏览事件，再到使用 Debug View 实时验证事件是否上报成功。读完本文，你将能够在自己的 Android 项目中复刻这套"图片浏览 + 埋点上报"的完整可运行示例。

示例应用概览

本模块名为analytics，是一个独立的 Gradle 工程（见 analytics/settings.gradle.kts），内部通过include(":app")聚合了:internal:lintchecks、:internal:lint与:internal:chooserx三个内部依赖模块。应用的包名为com.google.firebase.quickstart.analytics（见 analytics/app/build.gradle.kts）。

应用的核心交互是一个"图片浏览 + Tab 切换"界面：

• 顶部是 MaterialTabLayout，底部（主体区域）是一个ViewPager2，布局定义在 analytics/app/src/main/res/layout/activity_main.xml 中：TabLayout约束在顶部，ViewPager2填充其余空间。
• 每个 Tab 对应一张背景图片，图片数据由ImageInfo封装（图片资源 + 标题资源 + ID 资源），四张图分别来自favorite、flash、face、whitebalance四个 drawable 资源。
• 每张图片的展示由ImageFragment承担，其布局 analytics/app/src/main/res/layout/fragment_main.xml 是一张居中展示、带圆形背景的ImageView。

应用启动后，EntryChoiceActivity会提供 Java 与 Kotlin 两个入口选项，分别跳转到com.google.firebase.quickstart.analytics.java.MainActivity和com.google.firebase.quickstart.analytics.kotlin.MainActivity，定义在 analytics/app/src/main/java/com/google/firebase/quickstart/analytics/EntryChoiceActivity.kt 中；AndroidManifest.xml中只有EntryChoiceActivity声明了MAIN/LAUNCHERintent-filter（见 analytics/app/src/main/AndroidManifest.xml）。

该示例演示了 Google Analytics for Firebase 在 Android 上的三个核心能力：

1. 通过FirebaseAnalytics单例获取分析实例；
2. 上报系统预设事件与自定义事件；
3. 通过 User Property（用户属性）为后续的受众细分与报告维度提供依据。

环境准备与工程接入

添加 Firebase 到 Android 工程

按官方流程，将 Firebase 接入 Android 工程需要三步：

1. 在 Firebase 控制台创建项目并注册应用，获取google-services.json；
2. 将google-services.json放入应用模块的根目录（本示例模块为analytics/app/）；
3. 在根级build.gradle.kts（或模块级）应用 Google Services 插件。

本仓库提供了一个模拟用的 mock-google-services.json，供无真实项目时做本地构建/CI 冒烟验证，并有 copy_mock_google_services_json.sh 脚本负责将其复制到各示例模块。

依赖配置（Firebase BoM + Analytics SDK）

analytics/app/build.gradle.kts 展示了标准依赖写法：

plugins { alias(libs.plugins.android.application) alias(libs.plugins.google.services) } // 导入 Firebase BoM，统一管理各 Firebase SDK 版本 implementation(platform("com.google.firebase:firebase-bom:34.18.0")) // 无需指定版本号，版本由 BoM 决定 implementation("com.google.firebase:firebase-analytics") implementation("com.google.android.material:material:1.14.0") implementation("androidx.appcompat:appcompat:1.8.0") implementation("androidx.preference:preference-ktx:1.2.1") implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.11.0")

要点说明：

• 通过firebase-bom:34.18.0统一对齐 Firebase 各 SDK 版本，引入firebase-analytics时无需再写版本号；
• minSdk = 24、targetSdk = 37、compileSdk = 37，Java 兼容级别为 17；
• 开启了viewBinding = true，代码通过ActivityMainBinding访问视图；
• 顶部tasks { check.dependsOn("assembleDebugAndroidTest") }表示跑check时会一并编译 Android 测试 APK。

运行方式

在analytics/目录下使用仓库自带的 Gradle Wrapper 即可构建安装：

./gradlew :app:assembleDebug # 或直接安装到已连接的设备/模拟器 ./gradlew :app:installDebug

运行后，首次进入应用会弹出"Which food is your favorite?"对话框，选择完成后即可开始滑动浏览图片。该示例的 UI 行为由 Espresso 仪器测试 analytics/app/src/androidTest/java/com/google/firebase/quickstart/analytics/MainActivityTest.java 覆盖：它会在对话框出现时自动选择 "Hot Dogs"，然后依次左滑、左滑、右滑，断言每个位置的 Tab 标题（pattern1_title/pattern2_title/pattern3_title）正确显示。

初始化 FirebaseAnalytics：获取与分析会话的唯一入口

无论是 Java 还是 Kotlin 版本，第一步都是获取全局唯一的FirebaseAnalytics实例。

Java 版本（MainActivity.java）：

// 获取 FirebaseAnalytics 实例 mFirebaseAnalytics = FirebaseAnalytics.getInstance(this);

Kotlin 版本（MainActivity.kt）：

// 获取 FirebaseAnalytics 实例 firebaseAnalytics = Firebase.analytics

两者等价：Kotlin 版通过Firebase.analytics扩展属性获得同一单例。之后所有事件上报、用户属性设置、屏幕浏览记录，都通过这个实例完成。

首次启动引导：用 User Property 记录用户偏好

示例在首次启动时弹出一个AlertDialog，让用户从三选一列表（Hot Dogs、Hamburgers、Pizza，定义在 analytics/app/src/main/res/values/strings.xml 的food_items字符串数组中）中选择最喜欢的食物。

选择结果会做两件事：

1. 持久化到SharedPreferences（键为favorite_food，通过PreferenceManager.getDefaultSharedPreferences(this)读取）；
2. 通过setUserProperty("favorite_food", food)上报给 Firebase Analytics。

Java 版本（MainActivity.java）：

private void setUserFavoriteFood(String food) { PreferenceManager.getDefaultSharedPreferences(this).edit() .putString(KEY_FAVORITE_FOOD, food) .apply(); // 设置用户属性 mFirebaseAnalytics.setUserProperty("favorite_food", mFavoriteFood); }

Kotlin 版本（MainActivity.kt）：

private fun setUserFavoriteFood(food: String) { PreferenceManager.getDefaultSharedPreferences(this).edit() .putString(KEY_FAVORITE_FOOD, food) .apply() // 设置用户属性 firebaseAnalytics.setUserProperty("favorite_food", food) }

代码逻辑（以 Kotlin 为例）位于onCreate中：首次打开时getUserFavoriteFood()返回null，于是弹出对话框；之后每次启动都会读取已保存的值并重新上报用户属性。由于选择被持久化到本地，即使用户重新打开应用，也不会重复弹窗。

用户属性的价值在于：favorite_food这样的维度可以用于受众细分（例如按"喜欢 Pizza 的用户"划分群体），并在分析报告中作为附加维度出现。

滑动图片上报 SELECT_CONTENT 事件：系统预设事件实战

应用的核心埋点是"图片浏览"事件。当用户在ViewPager2中滑动切换图片时，onPageSelected(position)回调会触发两次上报：recordImageView()和recordScreenView()。

recordImageView()上报的是 Firebase Analytics 的预设事件SELECT_CONTENT（在 Kotlin 版中为SELECT_ITEM，对应较新的 SDK 事件常量），并携带三个标准参数：

Java 版本（MainActivity.java）：

private void recordImageView() { String id = getCurrentImageId(); String name = getCurrentImageTitle(); // 上报图片浏览事件 Bundle bundle = new Bundle(); bundle.putString(FirebaseAnalytics.Param.ITEM_ID, id); bundle.putString(FirebaseAnalytics.Param.ITEM_NAME, name); bundle.putString(FirebaseAnalytics.Param.CONTENT_TYPE, "image"); mFirebaseAnalytics.logEvent(FirebaseAnalytics.Event.SELECT_CONTENT, bundle); }

Kotlin 版本（MainActivity.kt）：

private fun recordImageView() { val id = getCurrentImageId() val name = getCurrentImageTitle() // 上报图片浏览事件 firebaseAnalytics.logEvent(FirebaseAnalytics.Event.SELECT_ITEM) { param(FirebaseAnalytics.Param.ITEM_ID, id) param(FirebaseAnalytics.Param.ITEM_NAME, name) param(FirebaseAnalytics.Param.CONTENT_TYPE, "image") } }

事件参数的数据来源是当前图片的 ID 与标题：IMAGE_INFOS数组中每张图片的id/title都映射到strings.xml中的字符串资源（pattern1_id~pattern4_id、pattern1_title~pattern4_title，取值如id-A/A）。这样上报到后台的每条记录都能精确对应到具体图片。

触发时机上，onPageSelected在每次切换 Tab 时都会触发，onCreate末尾还会补发一次初始图片的recordImageView()，保证"第一屏"也被统计。

分享菜单上报自定义事件：logEvent 的完整用法

菜单栏（analytics/app/src/main/res/menu/main.xml）中有一个 Share 项。点击后应用会通过Intent.ACTION_SEND调起系统分享，同时上报一个名为share_image的自定义事件，携带image_name与full_text两个参数：

Java 版本（MainActivity.java）：

Bundle params = new Bundle(); params.putString("image_name", name); params.putString("full_text", text); mFirebaseAnalytics.logEvent("share_image", params);

Kotlin 版本（MainActivity.kt）：

firebaseAnalytics.logEvent("share_image") { param("image_name", name) param("full_text", text) }

自定义事件的命名与参数没有预设限制，完全由业务侧决定。官方推荐统一使用snake_case命名事件、为每个事件定义固定的参数集合，以便后续在报告中聚合分析（例如统计哪些图片被分享最多、分享文案的完整内容）。

手动记录屏幕浏览事件：单 Activity 多页面场景的埋点技巧

示例应用只有一个Activity，页面切换完全依赖 Fragment，因此"屏幕浏览"无法由系统自动识别，需要在代码中手动上报SCREEN_VIEW事件。这正是recordScreenView()存在的意义（MainActivity.java）：

// 该字符串长度必须 <= 36 个字符 String screenName = getCurrentImageId() + "-" + getCurrentImageTitle(); Bundle bundle = new Bundle(); bundle.putString(FirebaseAnalytics.Param.SCREEN_NAME, screenName); bundle.putString(FirebaseAnalytics.Param.SCREEN_CLASS, "MainActivity"); mFirebaseAnalytics.logEvent(FirebaseAnalytics.Event.SCREEN_VIEW, bundle);

Kotlin 版本（MainActivity.kt）写法一致，同样通过SCREEN_VIEW预设事件 +SCREEN_NAME/SCREEN_CLASS两个参数完成。

要点：

• 屏幕名称由"图片 ID + 标题"拼接，例如id-A-A，便于在报告中区分具体页面；
• 源码注释特别强调screenName不得超过 36 个字符；
• 触发时机包含三处：onCreate完成初始页设置后、onPageSelected切换页面时、以及onResume中（保证从后台回到前台时也能记录一次屏幕浏览）。

这一模式在"单 Activity + 多 Fragment"的现代 Android 架构下非常实用：SCREEN_VIEW事件配合SCREEN_CLASS参数，能让分析后台准确还原用户在不同"页面"之间的浏览路径。

用 Debug View 实时验证埋点

analytics/README.md 明确指出：应用运行后产生的SELECT_CONTENT事件可以在 Debug View 中实时查看。

开启方式：在 Android 设备（或模拟器）上通过 adb 为应用包名启用调试模式，然后在 Firebase 控制台的 Analytics → DebugView 面板中即可看到实时流入的事件流。调试要点：

• 仅当设备通过 adb 设置调试标志后，事件才会被"实时"转发到 Debug View；否则事件会批量上报，存在延迟；
• Debug View 中可以逐条查看事件名称、参数键值对（如item_id、item_name、content_type），非常适合验证埋点是否按预期触发；
• 首次运行时的"选择 favorite food"对话框选择结果，会以用户属性（User Property）的形式出现，可在 Debug View 的属性区域中核对favorite_food的取值。

测试保障：Espresso 冒烟验证

示例为关键交互提供了仪器测试 MainActivityTest.java，用于验证：

1. 若出现选餐对话框，自动点击 "Hot Dogs"；
2. 初始页面标题pattern1_title（即 "A"）正确显示；
3. 在viewPager上执行swipeLeft()后，标题变为pattern2_title（"B"）；
4. 再次左滑显示pattern3_title（"C"）；
5. 右滑一次回到pattern2_title（"B"）。

该测试通过 Espresso 的onView+swipeLeft/swipeRight+withText断言，保证了 ViewPager 滑动逻辑与标题映射的正确性，可以作为后续新增图片或修改滑动逻辑时的回归基线。

小结

从analytics/README.md出发，结合 analytics 模块源码可以看到，Google Analytics for Firebase 在 Android 端的接入与埋点共四步：

1. 接入 Firebase（google-services.json+ Google Services 插件），并通过 BoM 引入firebase-analytics；
2. 获取FirebaseAnalytics单例（Java 的FirebaseAnalytics.getInstance(this)或 Kotlin 的Firebase.analytics）；
3. 按业务需要上报预设事件（SELECT_CONTENT/SELECT_ITEM、SCREEN_VIEW）与自定义事件（share_image），并设置用户属性（favorite_food）；
4. 通过 Debug View 实时核对事件与参数，用仪器测试保障埋点场景不回归。

这套模式可直接迁移到任意 Android 工程：凡是"内容浏览类"页面（图片、商品、文章），都可参照recordImageView()上报SELECT_CONTENT并携带item_id/item_name/content_type参数；凡是"单 Activity 多页面"架构，都可参照recordScreenView()手动上报SCREEN_VIEW；凡是需要做人群细分的维度（如用户偏好、会员等级），都可使用setUserProperty上报用户属性。

如果想深入了解 Firebase Analytics 的更多能力（受众、漏斗、Debug View 细节），可以继续查阅仓库根目录 README.md 以及其它示例模块（如 auth、config、crash），它们共同构成了 Firebase 各产品线的 Android 快速上手矩阵。

• 示例工程