Mars Android 接入指南

garryyan edited this page Jan 19, 2018 · 24 revisions

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

dependencies {
    compile 'com.tencent.mars:mars-core:1.2.1'
}

或者

dependencies {
    compile 'com.tencent.mars:mars-wrapper:1.1.8'
}

接着就可以使用

本地编译

所有的编译脚本都在libraries目录, 运行编译脚本之前也必须cd到此目录,在当前目录下运行。

python build_android.py

执行命令后,会让选择:

Enter menu:
1. build mars shared libs.
2. build mars static libs.
3. build xlog static libs.
4. build xlog shared libs.
5. exit.

注意如果遇到:error: unknown warning option '-Wclobbered'; did you mean '-Wconsumed'? 类似的错误,请换用ndk-r11c的版本编译。 如需要自定义日志加密算法或者长短连协议加解包,请选择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.6'
}

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

System.loadLibrary("stlport_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", PUB_KEY);
    Xlog.setConsoleLogOpen(true);

} else {
    Xlog.appenderOpen(Xlog.LEVEL_INFO, Xlog.AppednerModeAsync, cachePath, logPath, "MarsSample", 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 接口详细说明

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.