Mars Android 接入指南

https://github.com/Tencent/mars/wiki/Mars-Android-%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97

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.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 接口詳細說明