gradle 接入

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 的库依赖:

  1. dependencies {
  2.     compile 'com.tencent.mars:mars-core:1.2.2'
  3. }

或者

  1. dependencies {
  2.     compile 'com.tencent.mars:mars-wrapper:1.2.0'
  3. }

接着就可以使用了

本地编译

环境

安装 cmake 以及 python2.7， 以及下载 ndk-r16b，并配置环境变量 NDK_ROOT 指向 ndk 路径。

如果是 Windows 系统还需要安装 cygwin，并务必要安装其中的 make, gcc gdb。 然后把 cygwin 的 bin 目录配置到环境变量中的 PATH 中

编译

所有的编译脚本都在mars/mars 目录, 运行编译脚本之前也必须cd到此目录，在当前目录下运行，默认是编译 armeabi 的，如果需要其他 CPU 架构，把编译脚本中的archs = set(['armeabi'])稍作修改即可。

  1. python build_android.py

执行命令后，会让选择:

  1. Enter menu:
  2. 1. Clean && build mars.
  3. 2. Build incrementally mars.
  4. 3. Clean && build xlog.
  5. 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/ 复制到你的项目中：Mars Android 接入指南 - 图1

在 AndroidManifest.xml 中增加网络访问权限以及读取运营商信息( STN 使用)和文件读写权限( xlog 使用)

  1. <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
  2. <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  3. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  4. <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
  5. <uses-permission android:name="android.permission.INTERNET" />
  6. <uses-permission android:name="android.permission.WAKE_LOCK" />

使用

xlog

注意如果只想使用 xlog 不想使用 mars 的其他组件可以选择：在 app 的 gradle 文件 app/build.gradle，添加 xlog 的库依赖:

  1. dependencies {
  2.     compile 'com.tencent.mars:mars-xlog:1.0.7'
  3. }

不管是 mars-core 还是 mars-wrapper 或者是进行的本地编译，使用 xlog 的方式都是一样的。推荐在 程序启动时加载 xlog：

  1. System.loadLibrary("c++_shared");
  2. System.loadLibrary("marsxlog");

在程序启动加载 xlog 后紧接着初始化 xlog:

  1. final String SDCARD = Environment.getExternalStorageDirectory().getAbsolutePath();
  2. final String logPath = SDCARD + "/marssample/log";
  3.  
  4. // this is necessary, or may cash for SIGBUS
  5. final String cachePath = this.getFilesDir() + "/xlog"
  6.  
  7. //init xlog
  8. if (BuildConfig.DEBUG) {
  9.     Xlog.appenderOpen(Xlog.LEVEL_DEBUG, Xlog.AppednerModeAsync, cachePath, logPath, "MarsSample", 0, PUB_KEY);
  10.     Xlog.setConsoleLogOpen(true);
  11.  
  12. } else {
  13.     Xlog.appenderOpen(Xlog.LEVEL_INFO, Xlog.AppednerModeAsync, cachePath, logPath, "MarsSample", 0, PUB_KEY);
  14.     Xlog.setConsoleLogOpen(false);
  15. }
  16.  
  17. Log.setLogImp(new Xlog());

在 程序退出时反初始化：

  1. Log.appenderClose();

需要注意：

  • 如果你的程序使用了多进程，不要把多个进程的日志输出到同一个文件中，保证每个进程独享一个日志文件。
  • 保存 log 的目录请使用单独的目录，不要存放任何其他文件防止被 xlog 自动清理功能误删。
  • debug 版本下建议把控制台日志打开，日志级别设为 Verbose 或者 Debug, release 版本建议把控制台日志关闭，日志级别使用 Info.
  • cachePath这个参数必传，而且要data下的私有文件目录，例如 /data/data/packagename/files/xlog， mmap文件会放在这个目录，如果传空串，可能会发生 SIGBUS 的crash。

STN

建议在程序启动时或者使用网络之前初始化 STN。

mars-core 和本地编译的方式对 STN 的初始化以及释放如下：

  1. // set callback
  2. AppLogic.setCallBack(stub);
  3. StnLogic.setCallBack(stub);
  4. SdtLogic.setCallBack(stub);
  5.  
  6. // Initialize the Mars PlatformComm
  7. Mars.init(getApplicationContext(), new Handler(Looper.getMainLooper()));
  8.  
  9. // Initialize the Mars
  10. StnLogic.setLonglinkSvrAddr(profile.longLinkHost(), profile.longLinkPorts());
  11. StnLogic.setShortlinkSvrAddr(profile.shortLinkPort());
  12. StnLogic.setClientVersion(profile.productID());
  13. Mars.onCreate(true);
  14.  
  15. BaseEvent.onForeground(true);
  16. StnLogic.makesureLongLinkConnected();
  17.  

初始化顺序不一定要严格遵守上述代码的顺序，但在初始化时首先要调用 setCallBack 接口(callback 文件的编写可以参考 demo )，再调用 Mars.init，最后再调用 onForeground 和 makesureLongLinkConnect，中间顺序可以随意更改。注意：STN 默认是后台，所以初始化 STN 后需要主动调用一次BaseEvent.onForeground(true)

在程序退出时或需要释放 stn 时调用：

  1. Mars.onDestroy();

在网络切换时调用：

  1. BaseEvent.onNetworkChange()

mars-wrapper 中 MarsServiceNative 的 onDestroy 函数中已经会自动释放 Mars，所以使用 mars-wrapper 后只需要初始化 Mars 就行了，初始化方式如下：

  1. MarsServiceProxy.init(this, getMainLooper(),null);

不管是 mars-core 还是 mars-wrapper，使用 STN 前并没有主动调用System.loadLibrary，这是因为在 Mars.java 中已经做了这个工作。在网络切换时mars-wrapper也没有主动调用BaseEvent.onNetworkChange()，因为这个在 mars-wrapper 中已经帮忙完成。但不管哪种接入方式在下面几个事件发生后需要主动调用。

前后台切换时需要主动调用：

  1. BaseEvent.onForeground(boolean);

当账号信息更改时需要调用：

  1. StnLogic.reset();

更详细的的接口说明请参考 Mars Android 接口详细说明