转载:https://github.com/Meituan-Dianping/walle
Walle
瓦力,Android Signature V2 Scheme签名下的新一代渠道包打包神器
瓦力通过在Apk中的APK Signature Block
区块添加自定义的渠道信息来生成渠道包,从而提高了渠道包生成效率,可以作为单机工具来使用,也可以部署在HTTP服务器上来实时处理渠道包Apk的升级网络请求。
Quick Start
为了方便大家的使用,我们提供了2种使用方式:
- Gradle插件方式,方便快速集成
- 命令行方式,最大化满足各种自定义需求
Gradle插件使用方式
配置build.gradle
在位于项目的根目录 build.gradle
文件中添加Walle Gradle插件的依赖, 如下:
buildscript {
dependencies {
classpath 'com.meituan.android.walle:plugin:1.1.3'
}
}
- 1
- 2
- 3
- 4
- 5
并在当前App的 build.gradle
文件中apply这个插件,并添加上用于读取渠道号的AAR
apply plugin: 'walle'
dependencies {
compile 'com.meituan.android.walle:library:1.1.3'
}
- 1
- 2
- 3
- 4
- 5
配置插件
walle {
// 指定渠道包的输出路径
apkOutputFolder = new File("${project.buildDir}/outputs/channels");
// 定制渠道包的APK的文件名称
apkFileNameFormat = '${appName}-${packageName}-${channel}-${buildType}-v${versionName}-${versionCode}-${buildTime}.apk';
// 渠道配置文件
channelFile = new File("${project.getProjectDir()}/channel")
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
配置项具体解释:
- apkOutputFolder:指定渠道包的输出路径, 默认值为
new File("${project.buildDir}/outputs/apk")
apkFileNameFormat:定制渠道包的APK的文件名称, 默认值为
'${appName}-${buildType}-${channel}.apk'
可使用以下变量:projectName - 项目名字 appName - App模块名字 packageName - applicationId (App包名packageName) buildType - buildType (release/debug等) channel - channel名称 (对应渠道打包中的渠道名字) versionName - versionName (显示用的版本号) versionCode - versionCode (内部版本号) buildTime - buildTime (编译构建日期时间) fileSHA1 - fileSHA1 (最终APK文件的SHA1哈希值) flavorName - 编译构建 productFlavors 名
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
channelFile:包含渠道配置信息的文件路径。 具体内容格式如下:
meituan #美团 samsungapps #三星 hiapk anzhi xiaomi #小米 91com gfan appchina nduoa 3gcn mumayi 10086com wostore 189store lenovomm hicloud meizu wandou googleplay #Google Play baidu #百度 360cn #360 myapp
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
支持使用#号添加注释。
如何获取渠道信息
在需要渠道等信息时可以通过下面代码进行获取
String channel = WalleChannelReader.getChannel(this.getApplicationContext());
- 1
如何生成渠道包
生成渠道包的方式是和assemble${variantName}Channels
指令结合,渠道包的生成目录默认存放在 build/outputs/apk/
,也可以通过walle
闭包中的apkOutputFolder
参数来指定输出目录
用法示例:
- 生成渠道包
./gradlew clean assembleReleaseChannels
- 支持 productFlavors
./gradlew clean assembleMeituanReleaseChannels
更多用法
插入额外信息
channelFile
只支持渠道写入,如果想插入除渠道以外的其他信息,请在walle配置中使用configFile
walle {
// 渠道&额外信息配置文件,与channelFile互斥
configFile = new File("${project.getProjectDir()}/config.json")
}
- 1
- 2
- 3
- 4
configFile
是包含渠道信息和额外信息的配置文件路径。
配置文件采用json格式,支持为每个channel单独配置额外的写入信息。具体内容格式如下:
{
//extraInfo 不要出现以`channel`为key的情况
/*
不声明extraInfo的channel默认使用的extraInfo
如果没有此项则没有默认extraInfo
*/
"defaultExtraInfo": {
"key2": "20161213",
"key": "20161212"
},
/*
strategy:
1. ifNone (默认适用此策略) : 仅当对应channel没有extraInfo时生效
2. always : 所有channel都生效,channel中extraInfo的key与defaultExtraInfo重复时,覆盖defaultExtraInfo中的内容。
*/
//"defaultExtraInfoStrategy": "always",
"channelInfoList": [
{
"channel": "meituan",
// 此channel将使用自己声明的extraInfo
/*
此alias可以做到写入apk的channel是meituan,而打包时输出的文件名是美团
注意:alias不声明时,walle配置apkFileNameFormat中channel就是channel,否则为alias
*/
"alias": "美团",
"extraInfo": {
"buildtime": "20161212",
"hash": "123"
}
},
{
"channel": "360cn",
// 此channel将使用自己声明的extraInfo
"extraInfo": {
"key": "20161213"
}
},
{
"channel": "googleplay"
// 此channel将使用defaultExtraInfo
},
{
"channel": "xiaomi"
// 此channel将使用defaultExtraInfo
},
{
"channel": "meizu"
// 此channel将使用defaultExtraInfo
},
{
"channel": "wandoujia",
"excludeDefaultExtraInfo": true
//强制声明不使用defaultExtraInfo,默认false
},
{
"channel": "myapp",
"excludeDefaultExtraInfo": true,
//强制声明不使用defaultExtraInfo,默认false
"extraInfo": {
// 尽管exclude default,但也可以继续写入自己的。
"key": "20161212"
}
}
]
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
注意:
- 此配置项与
channelFile
功能互斥,开发者在使用时选择其一即可,两者都存在时configFile
优先执行。 - extraInfo 不要出现以
channel
为key的情况
而对应的渠道信息获取方式如下:
ChannelInfo channelInfo= WalleChannelReader.getChannelInfo(this.getApplicationContext());
if (channelInfo != null) {
String channel = channelInfo.getChannel();
Map<String, String> extraInfo = channelInfo.getExtraInfo();
}
// 或者也可以直接根据key获取
String value = WalleChannelReader.get(context, "buildtime");
- 1
- 2
- 3
- 4
- 5
- 6
- 7
临时生成某渠道包
我们推荐使用channelFile/configFile配置来生成渠道包,但有时也可能有临时生成渠道包需求,这时可以使用:
- 生成单个渠道包:
./gradlew clean assembleReleaseChannels -PchannelList=meituan
- 生成多个渠道包:
./gradlew clean assembleReleaseChannels -PchannelList=meituan,dianping
生成渠道包&写入额外信息:
./gradlew clean assembleReleaseChannels -PchannelList=meituan -PextraInfo=buildtime:20161212,hash:xxxxxxx
注意: 这里的extraInfo以
key:value
形式提供,多个以,
分隔。- 使用临时channelFile生成渠道包:
./gradlew clean assembleReleaseChannels -PchannelFile=/Users/xx/Documents/channel
- 使用临时configFile生成渠道包:
./gradlew clean assembleReleaseChannels -PconfigFile=/Users/xx/Documents/config.json
使用上述-P参数后,本次打包channelFile/configFile配置将会失效,其他配置仍然有效。 -PchannelList
,-PchannelFile
, -PconfigFile
三者不可同时使用。
命令行工具使用方式
walle-cli是walle提供的命令行程序,可以使用该工具来支持各类自定义的需求,具体使用方式如下:
获取信息
显示当前apk中的渠道和额外信息:
java -jar walle-cli-all.jar show /Users/Meituan/app/build/outputs/apk/app.apk
- 1
写入信息
写入渠道
java -jar walle-cli-all.jar put -c meituan /Users/Meituan/Downloads/app.apk
- 1
写入额外信息,不提供渠道时不写入渠道
java -jar walle-cli-all.jar put -c meituan -e buildtime=20161212,hash=xxxxxxx /Users/xxx/Downloads/app.apk
- 1
指定输出文件,自定义名称。 不指定时默认与原apk包同目录。
java -jar walle-cli-all.jar put -c meituan /Users/Meituan/Downloads/app.apk /Users/xxx/Downloads/app-new-hahha.apk
- 1
批量写入
命令行指定渠道列表
java -jar walle-cli-all.jar batch -c meituan,meituan2,meituan3 /Users/walle/app/build/outputs/apk/app.apk
- 1
指定渠道配置文件
java -jar walle-cli-all.jar batch -f /Users/Meituan/walle/app/channel /Users/Meituan/walle/app/build/outputs/apk/app.apk
- 1
输出目录可指定,不指定时默认在原apk包同目录下。
指定渠道&额外信息配置文件
java -jar walle-cli-all.jar batch2 -f /Users/Meituan/walle/app/config.json /Users/Meituan/walle/app/build/outputs/apk/app.apk
- 1
输出目录可指定,不指定时默认在原apk包同目录下。
更多用法
获取cli所有功能
java -jar walle-cli-all.jar -h
- 1
其他使用方式
为了更好的满足大家的各类自定义需求,我们把对APK Signing Block
区块进行读写操作的模块进行了封装。
读写模块的使用说明如下:
APK Signing Block读取模块:
payload_reader
dependencies { compile 'com.meituan.android.walle:payload_reader:1.1.6' }
- 1
- 2
- 3
本库对外提供两个读取类:
- ChannelReader:读取Walle内置id对应的信息,一般用来存放渠道和额外信息。
- PayloadReader: 读取自定义id对应的信息。
注意
非Android系统使用此jar包时需要添加org.json依赖
compile 'org.json:json:20080701'
- 1
备注:这么做主要是为了减少android方法数,利用系统自带的org.json
APK Signing Block写入模块:
payload_writer
dependencies { compile 'com.meituan.android.walle:payload_writer:1.1.6' }
- 1
- 2
- 3
本库对外提供两个写入类:
- ChannelWriter:向Walle内置id对应区域写入/移除信息,一般存放渠道和额外信息。额外信息key相同时覆盖写入。
- PayloadWriter: 自定义id写入,id相同时覆盖。
注意:请确保Android未使用此id
注意
非Android系统使用此jar包时需要添加org.json依赖
compile 'org.json:json:20080701'
- 1
备注:这么做主要是为了减少android方法数,利用系统自带的org.json
原理介绍
对该工具的原理感兴趣的同学,可以移步美团Android新一代渠道包生成工具进行了解。
注意事项
使用apksigner重新对Apk签名会导致渠道信息丢失,需要再次写入渠道信息。