转载：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签名会导致渠道信息丢失，需要再次写入渠道信息。