一键签到 签到插件开发文档

1 程序的框架结构

《一键签到》把整个程序划分为主程序与插件两大部分。主程序负责管理签到任务、管理签到插件、调用签到插件执行签到任务等各种琐事。插件仅负责执行特定网站具体的签到功能。 本程序的插件对文件的结构有严格的规定,必须按照规定组织文件才能编写出正确的插件。

主程序与插件有交流的过程一共有三个,分别是扫描注册插件、添加修改任务、执行签到。编写插件就是要响应这三种过程的交互操作。

1.1 插件的文件结构

主程序在调用插件时,会读取插件APK内的一些信息,这些信息必须按照规定命名与设置。一个典型的插件文件结构如图1.1。

典型插件的文件结构

图1.1 典型插件的文件结构

图1.1是格瓦拉生活网红包签到插件的文件结构图,其中被选中的文件即是规定好文件名的,这些文件的文件名不能进行任何修改。

CaptchaUtil、CommonData、CommonData、ManageTask这四个类是整个插件会用到的类,它们必须放在与插件APK包名一致的包下。比如插件在AndroidManifest.xml里设置的包名是me.shumei.open.oks.gewara,则这四个文件也必须放在me.shumei.open.oks.gewara包下。程序使用Jsoup类库来访问网络,org.jsoup.*包下都是Jsoup类库的文件,不需要改动。

CaptchaUtil.java是验证码操作类,负责下载、显示验证码图片,使用时只需调用showCaptcha函数,无需关心验证码的下载与显示等细节。该类一般不需要进行任何修改。

CommonData.java是保存一些公共信息的类,一般不需要进行修改。

ManageTask.java比较特殊,是管理插件自定义高级配置界面的类,负责在添加、修改签到任务时管理高级配置界面。如果插件没有使用自定义高级配置界面,则可以不编写该类。

Signin.java是最重要的类,负责执行网站的签到操作。该类里必须要实现的一个函数是public String[] start(Context ctx, boolean isAutoSign, String cfg, String user, String pwd),它是主程序执行签到的入口,此函数执行完毕后会返回一个String数组,主程序根据这个数组的内容判断是否签到成功。主程序并不关心签到的过程,只关心签到的结果。

config_layout.xml文件比较特殊,位于layout目录下,是自定义高级界面的布局文件,在这个文件里可以使用Android常用的UI控件进行布局。此文件是和ManageTask类结合使用的,在ManageTask的相应函数中可以对此布局内的控件进行操作。

string.xml里保存有插件的名称、作者、配置说明等信息,这些信息都必须用规定的名称存储,不能改为其他名称。

1.2 扫描注册插件流程

图1.2是扫描注册插件的流程图。

1.主程序扫描手机内所有已经安装的程序,读取这些程序的包名。

2.如果发现这个程序的包名是以me.shumei.open.oks开头,则判定其为《一键签到》的插件。

3.如果判定此程序为《一键签到》的插件,则开始读取APK包内的string.xml里的配置信息。

4.把string.xml里读取出的配置信息保存到数据库中,完成插件的注册。

图1.2 扫描注册插件流程

1.3 签到任务的添加修改流程

签到任务的添加和修改所执行的操作大部分都相同,仅有小部分数据有差异。

图1.3是主程序在执行任务的添加、修改操作时的一个大概流程,标注为橙色的流程在执行时会有比较复杂的操作。

1.当在主程序里点击“添加任务”或“任务管理”页面里的列表项时(“添加任务”里是插件列表,“任务管理”里是任务列表),会弹出该任务的配置窗口,这个配置窗口的界面是由插件在string.xml里设置的cfg_config_type字段的值决定的。

2.使用cfg_config_type一共可以设置三种不同的显示界面,主程序根据不同的设置显示相应的界面。
当cfg_config_type的值为0时,表示除了必要的标题、账号和密码外不需要再填写额外信息,见图1.4。此时所有的操作由主程序进行管理,插件不需要关心。比如界面的初始化、UI的管理、数据的保存等,都是由主程序处理。
当值为1时,表示除了必要的三项信息外,还需要主程序显示一个“配置”输入框用以输入额外的配置信息,见图1.5。此时所有的操作,包括“配置”输入框的数据验证与存储也都是由主程序进行管理,插件不需要关心。
当值为2时,表示由插件自己定义复杂的界面布局,见图1.6。此时插件需要在ManageTask类中初始化UI界面,配置信息的组织也是由ManageTask类负责。

3.当用户完成任务的配置,点击“保存”时,主程序会把任务的账号密码等配置信息保存到数据库。

图1.3 任务添加修改流程 图1.4 cfg_config_type值为0时,不需要填写额外配置 图1.5 cfg_config_type值为1时,需要显示一个“配置”输入框 图1.6 cfg_config_type值为2时,由插件自己定义高级界面

1.4 执行插件进行签到的流程

图1.7是执行插件进行签到的流程图。

假设插件的包名为me.shumei.open.oks.myplugin,则整个执行签到流程如下:

1.主程序首先加载me.shumei.open.oks.myplugin.Signin类,并生成这个类的一个实例,然后用这个生成的实例执行它的public String[] start(Context ctx, boolean isAutoSign, String cfg, String user, String pwd)方法。执行的同时把主程序的Context、任务的配置信息、任务的明文账号密码等作为参数传入此函数。

2.插件的start函数利用这些数据完成全部的签到操作,最后返回一个有两个元素的String数组,String[0]的值规定只能为"true"或"false",前者表示签到成功,后者表示签到失败。String[1]是签到成功或失败的反馈信息,用以告知用户签到成败的详细结果。

3.主程序接收到插件返回的String数组,便根据这数组里的两个元素的数值进行数据处理。

图1.7 主程序执行插件进行签到的流程

2 插件的编写

2.1 下载Demo包

因插件的文件结构稍显复杂且规定名称的文件较多,所以在制作插件时,应当直接修改官方提供的插件DEMO源码,不推荐建立全新的项目自行编写。

推荐下载官方的“格瓦拉生活网红包”签到插件DEMO源码,此插件包含有所有规定好名称的文件,且包含有验证码显示、自定义配置界面这两个功能的实现方法。

“格瓦拉生活网红包”签到插件DEMO源码地址:https://github.com/wolforce/me-shumei-open-oks-gewara

下载完毕后解压,导入Eclipse即可开始修改。修改时可按照以下步骤进行,可有效避免遗漏:
1) 改AndroidManifest.xml与src目录下的包名
2) 改string.xml里的配置
3) 改drawable里的应用图标
4) 设计自定义配置界面config_layout.xml
5) 编写配置界面的ManageTask类
6) 编写Signin类

其中第4、5步只有在使用自定义配置界面时才需要编写,其他情况下可直接忽略。

2.2~2.7节以编写包名为me.shumei.open.oks.myplugin的新插件为例,说明插件的编写步骤。

2.2 改AndroidManifest.xml与src目录下的包名

打开项目的Manifest文件,修改package为me.shumei.open.oks.myplugin,见图2.1。注意包名的前半部分me.shumei.open.oks是固定的,不能修改。保存修改后Eclipse会提示是否更新配置信息,确定即可。

图2.1 修改Manifest文件

改完后src目录会出现错误提示,此时需要把src目录下的me.shumei.open.oks.gewara包重命名为oks.shumei.open.oks.myplugin。

图2.2 修改src下的包名

2.3 改string.xml里的配置

插件的配置信息保存于string.xml,见图2.3。按照注释修改该图里的字段即可。
app_name是APK程序的名称。
label_activity_main是主Activity的名称。
cfg_plugin_name是插件在《一键签到》内显示的名称。
cfg_author是插件作者的信息。
cfg_info是“添加任务”的弹出窗口上显示的说明信息,提示用户怎么使用此插件。
cfg_config_type用以配置插件的任务管理界面的类型,这个配置决定是否需要在插件里编写config_layout.xml文件和ManageTask类。
cfg_times表示该网站的任务一天可以签到几次。

图2.3 string.xml的配置

2.4 改drawable里的应用图标

软件的图标路径是res/drawble-hdpi/ic_launcher.png,大小为72x72,做个好看点的图标替换掉即可。

图2.4 软件的图标

2.5 *设计自定义配置界面config_layout.xml

config_layout.xml文件的路径是/res/layout/config_layout.xml,它保存的是插件的自定义配置界面布局,见图2.5。在此文件中,可以使用常用的Android控件来布局,设计方法和一般的应用相同。

如果没有在string.xml里设置cfg_config_type的值为2,则可以不用编写此文件。

图2.5 config_layout.xml界面

2.6 *编写配置界面的ManageTask类

ManageTask类的作用是管理config_layout.xml渲染出的View。里面有三个函数是必须要实现的:
public View initView(Context context, View view, String cfg)
public boolean dataValidator(Context context, View view)
public String getConfigData(Context context, View view)

initView函数用以初始化界面,主程序会把任务的配置信息通过cfg参数传入。 如果当前是“添加任务”,则cfg是长度为0的String。如果当前是“修改任务”,则传入的cfg是任务已经保存的自定义view里的配置信息,这些配置信息是上一次修改保存任务的时候,主程序调用getConfigData函数获取的,具体说明见图2.6。

dataValidator函数用以验证配置界面内的数据的有效性,可以在此函数内对传入的view使用findViewById(int)获取config_layout.xml内的控件,并检测它们的数据是否填写正确,如果全部正确就返回true,否则就要返回false。具体信息见图2.7。

getConfigData函数用以把自定义配置界面内的数据转化成为一个字符串,这个字符串由主程序进行保存,函数仅需返回字符串即可。推荐使用JSON字符串保存数据。具体信息见图2.8。

这三个函数都由主程序自动调用,插件只需要实现函数的功能,不需手动调用。

图2.6 initView函数的注释


图2.7 dataValidator函数的注释


图2.8 getConfigData函数的注释


2.7 编写Signin类

Signin是执行签到的类,它有一个必须实现的函数:
public String[] start(Context ctx, boolean isAutoSign, String cfg, String user, String pwd)

此函数是签到的入口,主程序在执行签到时会调用这个函数并根据函数的返回值判断签到是否成功。此函数须返回长度为2的一维String数组,String[0]的值规定只能为"true"或"false",前者表示签到成功,后者表示签到失败。String[1]是签到成功或失败的反馈信息,用以告知用户签到成败的详细信息。

主程序是在线程中调用此函数的,所以在编写此函数时,不需要再开新的线程访问网络。使用新线程有可能会导致软件出错。

函数的说明见图2.9。

图2.9 start函数的注释

在所有数据都修改完后,把程序导出APK包安装到手机上,即可完成插件的安装。打开《一键签到》主程序时,插件会被主程序自动扫描并注册到主程序的数据库中,到“添加任务”界面可看到插件出现在任务列表中,点击即可添加签到任务。

3 ProGuard混淆压缩

如果需要对代码进行混淆压缩,可使用以下配置代码避免接口被删除:

        -keep class me.shumei.open.oks.*.Signin
        -keep class me.shumei.open.oks.*.Signin {
              public <methods>;
        }
         
        -keep class me.shumei.open.oks.*.CaptchaUtil
        -keep class me.shumei.open.oks.*.CaptchaUtil {
              public static java.lang.String captcha_input;
              public <methods>;
        }
         
        -keep class me.shumei.open.oks.*.ManageTask
        -keep class me.shumei.open.oks.*.ManageTask {
              public <methods>;
        }