原生移动开发 / 系统课时

用 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 字段时显式开启生成能力。

kotlin
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> 节点内。

xml
<meta-data
    android:name="distribution_channel"
    android:value="${CHANNEL}" />

构建时执行:

bash
./gradlew :app:assembleRelease -Pchannel=huawei

预期输出:

text
BUILD SUCCESSFUL in <TIME>

实际耗时会不同。此时生成的 Release 构建中,BuildConfig.CHANNEL 与 Manifest 的 distribution_channel 都来自 huawei。

在运行时读取渠道值

如果业务代码只需要判断渠道,优先读取 BuildConfig,调用简单且不会重复解析 Manifest。以下为 Activity 中的片段示例,依赖应用模块生成的 BuildConfig。

kotlin
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 输出:

text
I/Channel: channel=huawei

如果某个第三方 SDK 只从 Manifest 的 <meta-data> 读取配置,就保留 Placeholder;如果只有应用代码使用渠道,则没有必要同时维护两套读取逻辑。

给缺失渠道设置明确策略

示例用 unknown 作为默认值,适合开发构建避免因为漏参数而中断。正式发渠道包时,更稳妥的做法是在 CI 中把 channel 设为必填,并让发布任务在缺失时失败,而不是悄悄产出 unknown 渠道包。

当渠道差异只是一两个字符串时,Gradle 参数加 BuildConfig 已经足够;如果不同市场还要切换资源、依赖甚至代码,就应把渠道提升为 Product Flavor,由构建变体统一管理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Gradle 注入渠道标识

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通