原生移动开发 / 系统课时
用 Gradle 注入渠道标识
用 Gradle 注入渠道标识
同一份 Android 代码发往多个应用市场时,常需要把“当前渠道”固化进构建产物,供统计、开关或 SDK 初始化读取。本节用 Gradle 构建参数作为来源,同时注入 BuildConfig 与 Manifest,并验证应用运行时拿到的是本次构建的渠道值。
学习目标
- 理解构建参数、
BuildConfig与 Manifest Placeholder 各自负责什么。 - 能用 Gradle 参数注入渠道值,并在 Kotlin 代码中读取。
- 能判断渠道标识适合放在哪里,以及哪些内容不应作为渠道值注入。
先分清三种注入方式
-Pchannel=huawei 这类 Gradle Project Property 只存在于构建阶段,应用运行后不能直接读取。通常需要把它继续写入 BuildConfig 或 Manifest,才能进入 APK/AAB。
| 方式 | 适合场景 | 运行时读取 |
|---|---|---|
BuildConfig |
业务代码、埋点、功能开关需要渠道值 | 直接读取生成的常量 |
| Manifest Placeholder | SDK 的 <meta-data>、组件属性需要渠道值 |
由 Android 框架或 PackageManager 读取 |
Gradle -P 参数 |
CI、脚本或本地命令决定本次构建渠道 | 不能直接在应用进程中读取 |
渠道值应该只有一个来源,再派生到需要的位置,避免 BuildConfig 写成 huawei、Manifest 却写成 xiaomi。
从构建参数注入两个位置
以下为 app/build.gradle.kts 片段示例,假设项目已经应用 Android Application 插件并已有 android {} 配置。自定义 BuildConfig 字段时显式开启生成能力。
val channel = providers.gradleProperty("channel")
.orElse("unknown")
.get()
android {
buildFeatures {
buildConfig = true
}
defaultConfig {
// String 类型的值会原样写入生成的 Java/Kotlin 常量,因此要包含字符串引号。
buildConfigField("String", "CHANNEL", "\"$channel\"")
// 同一来源同时提供给 AndroidManifest.xml。
manifestPlaceholders["CHANNEL"] = channel
}
}Manifest 中可把同一个值交给需要 <meta-data> 的 SDK 或组件。下面同样是片段示例,放在现有 <application> 节点内。
<meta-data
android:name="distribution_channel"
android:value="${CHANNEL}" />构建时执行:
./gradlew :app:assembleRelease -Pchannel=huawei预期输出:
BUILD SUCCESSFUL in <TIME>实际耗时会不同。此时生成的 Release 构建中,BuildConfig.CHANNEL 与 Manifest 的 distribution_channel 都来自 huawei。
在运行时读取渠道值
如果业务代码只需要判断渠道,优先读取 BuildConfig,调用简单且不会重复解析 Manifest。以下为 Activity 中的片段示例,依赖应用模块生成的 BuildConfig。
import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val channel = BuildConfig.CHANNEL
Log.i("Channel", "channel=$channel")
}
}使用前面的 -Pchannel=huawei 构建并运行后,预期 Logcat 输出:
I/Channel: channel=huawei如果某个第三方 SDK 只从 Manifest 的 <meta-data> 读取配置,就保留 Placeholder;如果只有应用代码使用渠道,则没有必要同时维护两套读取逻辑。
给缺失渠道设置明确策略
示例用 unknown 作为默认值,适合开发构建避免因为漏参数而中断。正式发渠道包时,更稳妥的做法是在 CI 中把 channel 设为必填,并让发布任务在缺失时失败,而不是悄悄产出 unknown 渠道包。
当渠道差异只是一两个字符串时,Gradle 参数加 BuildConfig 已经足够;如果不同市场还要切换资源、依赖甚至代码,就应把渠道提升为 Product Flavor,由构建变体统一管理。