Mars Android 接入指南
Mars Android 接入指南
gradle 接入使用的日志加密算法是不加密的，长连接短连接加解包也是默认的，如需自定义请参考本地编译。注意 gradle接入因为考虑依赖包体积的大小，只提供了 armeabi 和 x86_64 两种 CPU 架构的 so， 如果你使用的其他 so 有其他架构的，务必不要使用 gradle 依赖，参考本地编译 编出你需要的 so,否则会报 Couldn’t find “xxxx.so”的错误
目前 gradle 接入支持两种方式：mars-core 和 mars-wrapper。只是做个 sample 的话建议可以使用 mars-wrapper， 但是如果在实际 App 中使用 mars，建议使用 mars-core 或本地编译
在 app 的 gradle 文件 app/build.gradle，添加 Mars 的库依赖:
dependencies {
compile 'com.tencent.mars:mars-core:1.2.2'
}
或者
dependencies {
compile 'com.tencent.mars:mars-wrapper:1.2.0'
}
接着就可以使用了
本地编译
环境
安装 cmake 以及 python2.7， 以及下载 ndk-r16b，并配置环境变量 NDK_ROOT 指向 ndk 路径。
如果是 Windows 系统还需要安装 cygwin，并务必要安装其中的 make, gcc gdb。 然后把 cygwin 的 bin 目录配置到环境变量中的 PATH 中
编译
所有的编译脚本都在mars/mars 目录, 运行编译脚本之前也必须cd到此目录，在当前目录下运行，默认是编译 armeabi 的，如果需要其他 CPU 架构，把编译脚本中的archs = set(['armeabi'])稍作修改即可。
python build_android.py
执行命令后，会让选择:
Enter menu:
1. Clean && build mars.
2. Build incrementally mars.
3. Clean && build xlog.
4. Exit
如需要自定义日志加密算法或者长短连协议加解包，请选择static libs选项，即 2 和 3。选项 1 和 2 输出结果全部在 mars_android_sdk 目录中，3 和 4 输出结果全部在 mars_xlog_sdk 目录中。
用选项 1 做范例。mars_android_sdk 中编译后的输出文件详细介绍如下：
| 文件名 | 描述 |
|---|---|
| mars_libs/ | 编译生成的 mars 的各个子项目的静态库。 |
| libs/ | 最终编译生成的 mars 的动态库，也是发布用的库。 |
| obj/ | 和 libs/ 里动态库相对应的符号信息，如果发布用了 libs/ 下面的库，此目录应永久备份。以防查问题时后续 ndk-stack 或者 addr2line 使用。 |
| src/ | 使用 mars 所需要的 Java 文件。 |
| log_crypt.cc.rewriteme | 最新版本已不再需要 |
| log_crypt.h | 最新版本已不再需要 |
| jni/longlink_packer.cc.rewriteme | 长连接协议可扩展部分，使用前请先改名为 longlink_packer.cc，如若想自定义长连接包头以及加解包，重写该文件。 |
| jni/longlink_packer.h | 编译 longlink_packer.cc 需要使用的头文件，请勿修改。 |
| jni/shortlink_packer.cc.rewriteme | 短连接协议可扩展部分，使用前请先改名为 shortlink_packer.cc，如若想自定义短连接包头(HTTP Head)，重写该文件。 |
| jni/shortlink_packer.h | 编译 shortlink_packer.cc 需要使用的头文件，请勿修改。 |
进入 mars_android_sdk 目录，自定义日志加密算法或者长短连协议加解包后执行ndk-build -B -j编译出来最终 libs。
把 mars_android_sdk/src 目录下的 Java 文件以及 libs/ 复制到你的项目中： 
在 AndroidManifest.xml 中增加网络访问权限以及读取运营商信息( STN 使用)和文件读写权限( xlog 使用)
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
使用
xlog
注意如果只想使用 xlog 不想使用 mars 的其他组件可以选择： 在 app 的 gradle 文件 app/build.gradle，添加 xlog 的库依赖:
dependencies {
compile 'com.tencent.mars:mars-xlog:1.0.7'
}
不管是 mars-core 还是 mars-wrapper 或者是进行的本地编译，使用 xlog 的方式都是一样的。
推荐在 程序启动时加载 xlog：
System.loadLibrary("c++_shared");
System.loadLibrary("marsxlog");
在程序启动加载 xlog 后紧接着初始化 xlog:
final String SDCARD = Environment.getExternalStorageDirectory().getAbsolutePath();
final String logPath = SDCARD + "/marssample/log";
// this is necessary, or may cash for SIGBUS
final String cachePath = this.getFilesDir() + "/xlog"
//init xlog
if (BuildConfig.DEBUG) {
Xlog.appenderOpen(Xlog.LEVEL_DEBUG, Xlog.AppednerModeAsync, cachePath, logPath, "MarsSample", 0, PUB_KEY);
Xlog.setConsoleLogOpen(true);
} else {
Xlog.appenderOpen(Xlog.LEVEL_INFO, Xlog.AppednerModeAsync, cachePath, logPath, "MarsSample", 0, PUB_KEY);
Xlog.setConsoleLogOpen(false);
}
Log.setLogImp(new Xlog());
在 程序退出时反初始化：
Log.appenderClose();
需要注意：
- 如果你的程序使用了多进程，不要把多个进程的日志输出到同一个文件中，保证每个进程独享一个日志文件。
- 保存 log 的目录请使用单独的目录，不要存放任何其他文件防止被 xlog 自动清理功能误删。
- debug 版本下建议把控制台日志打开，日志级别设为 Verbose 或者 Debug, release 版本建议把控制台日志关闭，日志级别使用 Info.
- cachePath这个参数必传，而且要data下的私有文件目录，例如 /data/data/packagename/files/xlog， mmap文件会放在这个目录，如果传空串，可能会发生 SIGBUS 的crash。
STN
建议在程序启动时或者使用网络之前初始化 STN。
mars-core 和本地编译的方式对 STN 的初始化以及释放如下：
// set callback
AppLogic.setCallBack(stub);
StnLogic.setCallBack(stub);
SdtLogic.setCallBack(stub);
// Initialize the Mars PlatformComm
Mars.init(getApplicationContext(), new Handler(Looper.getMainLooper()));
// Initialize the Mars
StnLogic.setLonglinkSvrAddr(profile.longLinkHost(), profile.longLinkPorts());
StnLogic.setShortlinkSvrAddr(profile.shortLinkPort());
StnLogic.setClientVersion(profile.productID());
Mars.onCreate(true);
BaseEvent.onForeground(true);
StnLogic.makesureLongLinkConnected();
初始化顺序不一定要严格遵守上述代码的顺序，但在初始化时首先要调用 setCallBack 接口(callback 文件的编写可以参考 demo )，再调用 Mars.init，最后再调用 onForeground 和 makesureLongLinkConnect，中间顺序可以随意更改。注意：STN 默认是后台，所以初始化 STN 后需要主动调用一次BaseEvent.onForeground(true)
在程序退出时或需要释放 stn 时调用：
Mars.onDestroy();
在网络切换时调用：
BaseEvent.onNetworkChange()
mars-wrapper 中 MarsServiceNative 的 onDestroy 函数中已经会自动释放 Mars，所以使用 mars-wrapper 后只需要初始化 Mars 就行了，初始化方式如下：
MarsServiceProxy.init(this, getMainLooper(),null);
不管是 mars-core 还是 mars-wrapper，使用 STN 前并没有主动调用System.loadLibrary，这是因为在 Mars.java 中已经做了这个工作。在网络切换时mars-wrapper也没有主动调用BaseEvent.onNetworkChange()，因为这个在 mars-wrapper 中已经帮忙完成。但不管哪种接入方式在下面几个事件发生后需要主动调用。
前后台切换时需要主动调用：
BaseEvent.onForeground(boolean);
当账号信息更改时需要调用：
StnLogic.reset();
更详细的的接口说明请参考 Mars Android 接口详细说明
