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 接口详细说明