4、FinChat SDK Android 集成文档
-
0. 集成 Android SDK 前的准备工作
申请注册凡泰极客开发者账号,申请 AppId 和 AppKey,详细请咨询相关接口人。
1. Android SDK 介绍及导入
1.1 Android SDK 介绍
FinChat SDK 为用户开发 IM 应用提供完善的功能框架。本SDK最低支持Android 4.4(API19),最高支持Android Q,通过Gradle的方式引入依赖。
架构图如下:
- SDK_Core: 核心消息协议实现,完成与服务器之间的信息交换。
- SDK: 基于核心协议实现完整的 IM 功能,实现消息收发、会话管理、群组创建、好友增删等功能。
- HttpEngine: HTML5资源加速服务组件
- ConvoUI: 会话型UI交互组件
- FinoChatClient: 使用SDK接口的入口:负责完成初始化,也是获取功能模块的入口。
- AccountApi: 提供账户管理相关功能,包括登入、登出等。
- ContacApi: 提供好友的添加删除,黑名单的管理。
- GroupApi: 提供群组的管理,创建、删除群组,管理群组成员等功能。
- ChatRoomApi: 提供聊天室的管理。
- ChatUI: “消息聊天”用户交互界面
- ConversationUI: “会话”列表用户交互界面
- MineUI: “我的”用户交互界面
- ContactUI: “通讯录”用户交互界面
2. 集成 Android SDK
在您阅读此文档时,我们假定您已具备基础的Android开发经验,并能够理解基础技术概念。
2.1 通过Demo直接体验
您可以到凡泰极客官方git平台下载Demo工程 finchat-android-demo。
2.2 为现有工程集成FinChatSDK
若您有已上线应用,并希望在现有代码上集成FinChatSDK,请看下文具体配置步骤。
3. 配置工程
3.1 配置仓库地址
在项目顶层 build.gradle 配置:
allprojects { repositories { google() jcenter() // 添加以下依赖源 maven { url "https://jitpack.io" } maven { url "https://gradle.finogeeks.club/repository/finogeeks/" credentials { username "gradle" password "ftjk@@123321" } } maven { url "https://dl.bintray.com/drummer-aidan/maven" } maven { url "https://dl.bintray.com/thelasterstar/maven/" } } }
3.2 添加依赖库
然后通过项目模块 build.gradle 添加依赖并编译工程:
dependencies { ...... // 指定具体版本号或使用"latest.release" implementation "com.finogeeks.finochat.sdk:finochat-android-sdk:latest.release" // 音视频模块为可选配置,根据功能需求选择性添加 // 指定具体版本号或使用"latest.release" implementation "com.finogeeks.finochat.sdk:finovideochat:latest.release" // FinChatSDK方法引用超过64K,必须依赖multidex implementation 'androidx.multidex:multidex:2.0.1' }
在项目模块 build.gradle(Module:app) 的 android 层级增加若干配置,如下
android { compileSdkVersion 29 buildToolsVersion "29.0.2" defaultConfig { applicationId "com.finogeeks.finochatapp" targetSdkVersion 29 // 最低支持版本19 minSdkVersion 19 // useSupportLibrary开启 vectorDrawables.useSupportLibrary = true // 指定ABI ndk { abiFilters "armeabi", "x86", "armeabi-v7a" } // 为Android5.0及以上开启内置MultiDex defaultConfig { multiDexEnabled true } } ...... // 增加以下配置 compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } packagingOptions { doNotStrip '*/mips/*.so' doNotStrip '*/mips64/*.so' // The project react-native does not provide 64-bit binaries at the // time of this writing. Unfortunately, packaging any 64-bit // binaries into the .apk will crash the app at runtime on 64-bit // platforms. exclude '/lib/mips64/**' exclude '/lib/arm64-v8a/**' exclude '/lib/x86_64/**' pickFirst '/lib/x86/libjsc.so' pickFirst '/lib/armeabi-v7a/libjsc.so' exclude 'META-INF/proguard/androidx-annotations.pro' } }
3.3 配置权限
在 AndroidManifest.xml 为SDK运行配置必要权限:
<uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.INTERNET" />
4. Android SDK使用
接口文档请参考链接:APIDoc
4.1 创建配置选项
要求在 Application 的 onCreate() 方法中进行初始化。初始化依赖传入 FinoChatOption 对象实例获取SDK运行过程中的必要参数。
注意:Application父类必须继承 MultiDexApplication
public class XApplication extends MultiDexApplication { private static final String TAG = "XApplication"; @Override public void onCreate() { super.onCreate(); // 转发消息到微信、QQ、微博、微信小程序,需要设置外部SDK的Key // 若对应外部模块不需要则无须设置 FinoChatOption.ShareParams params = new FinoChatOption.ShareParams(); params.wechatAppId = "....."; params.qqAppId = "....."; params.weiBoAppKey = "....."; params.miniProgramId = "....."; params.appletAvatar = R.drawable.app_icon; FinoChatOption option = new FinoChatOption(); option.setApiURL("https://api.finogeeks.club"); // 服务器地址 option.setAppKey("AppKey"); option.setAppType("STAFF"); option.setAppId("3"); option.setApiPrefix("/api/v1"); option.getNotification().notificationIcon = R.drawable.app_icon; option.setAppDebug(BuildConfig.DEBUG); option.setLogLevel(android.util.Log.VERBOSE); option.setSdkVersion(com.finogeeks.finochat.BuildConfig.VERSION_NAME); option.setShareParams(params); // 同步初始化 FinoChatClient.getInstance().initFinoChatSession(this, option, new FinoCallBack() { @Override public void onProgress(int i, String s) { } @Override public void onSuccess(Object o) { Log.i(TAG, "initFinoChatSession() is Success."); } @Override public void onError(int i, String s) { Log.e(TAG, "initFinoChatSession.onError(), code:" + i + ",message:" + s); } }); } }
4.2 检查登录状态
在 Application 完成初始化后,可在 SplashActivity 检查用户是否已经登录,并执行不同逻辑,如下示例:
class SplashActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) if (FinoChatClient.getInstance().accountManager().isLogin) { startActivity(Intent(this, HomeActivity::class.java)) // 进入主页使用FinChatSDK } else { startActivity(Intent(this, LoginActivity::class.java)) // 进入用户账户登录界面 } } }
4.3 用户登录
用户登录界面,使用以下接口登录FinChatSDK
FinoChatClient.getInstance().accountManager().login(username, password, new FinoCallBack<Map<String, Object>>() { @Override public void onSuccess(Map<String, Object> result) { startActivity(new Intent(LoginActivity.this, SplashActivity.class)); finish(); } @Override public void onProgress(int progress, String status) { finish(); } @Override public void onError(int code, String message) { Log.d("LoginActivity", message); Toast.makeText(LoginActivity.this, message, Toast.LENGTH_LONG).show(); } });
登录成功后会自动初始化session,同时sdk还会提供有token的登录接口。
5. 主页面搭建
为了提供灵活的页面配置,sdk没有提供默认主页面,而是提供了对应的Fragment供用户自由组装,其中包括“会话“页面、”通讯录“页面和”我的“页面。
开发者可以通过以下代码获取页面Fragment:
FinoChatClient.getInstance().chatUIManager().conversationFragment();
例如以下示例:
public class HomeActivity extends AppCompatActivity { @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_home); Fragment f = FinoChatClient.getInstance().chatUIManager().conversationFragment(); getSupportFragmentManager().beginTransaction() .add(R.id.container, f) .commit(); } }
对应页面布局:
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="match_parent" android:orientation="vertical"> <FrameLayout android:id="@+id/container" android:layout_width="match_parent" android:layout_height="match_parent" android:background="@android:color/white" /> </FrameLayout>
6. 主要API接口
sdk对外暴露的API接口主要在com.finogeeks.finochat.sdk包中:
- FinoChatClient :客户端主要入口,提供初始化接口和获取其他服务;
- IAccountManager:账户相关接口,包括登录 注销 登录状态判断等;
- IChatUiManager:UI相关接口,用户获取一些Fragment以及启动一些页面或对话框;
- INotificationManager:sdk事件通知接口,可以用于监听sdk内部事件 如退出登录然后执行自己的操作;
- IPluginManager : 一些UI定制的接口 例如可以在聊天页面更多菜单里注册自己的选项并获取事件监听 也可以定制我的页面的项目;
7. 主题配置示例
1.在styles.xml里自定义主题
<style name="Theme_ICBC_GOLD"> <item name="TP_color_normal">#A6844F</item> // 主题色普通态 <item name="TP_color_pressed">#584529</item> // 主题色点击态 <item name="TP_color_disable">#D2C1A7</item> // 主题色不可点击态 <item name="Bubble_Host_solid_color">#FFF5E7</item> // 本人消息气泡填充 <item name="Bubble_Host_stroke_color">#E4DACA</item> // 本人消息气泡描边 <item name="Bubble_Guest_solid_color">#FFFFFF</item> // 对方消息气泡填充 <item name="Bubble_Guest_stroke_color">#CFCFCF</item> // 对方消息气泡描边 <item name="button_solid_normal">#A6844F</item> // 按钮普通态填充 <item name="button_solid_pressed">#584529</item> // 按钮点击态填充 <item name="button_solid_disable">#D2C1A7</item> // 按钮不可点击填充 <item name="NAV_color">#FAFAFA</item> // Toolbar背景色 <item name="NAV_TP_color_normal">#A6844F</item> // Toolbar切图,文字普通(包含调用系统的返回箭头) <item name="NAV_TP_color_pressed">#584529</item> // Toolbar切图,文字点击(包含调用系统的返回箭头) <item name="NAV_TP_color_disable">#D2C1A7</item> // Toolbar切图,文字不可点击(包含调用系统的返回箭头) <item name="NAV_title_color">#333333</item> // Toolbar标题文字颜色 <item name="NAV_line">#B0B0B0</item> //Toolbar分割线颜色 <item name="switch_solid_enable_off">#FFFFFF</item> // 开关可操作_关闭 <item name="switch_solid_enable_on">#A6844F</item> // 开关可操作_打开 <item name="switch_solid_disable_off">#FFFFFF</item> // 开关不可操作_关闭 <item name="switch_solid_disable_on">#D2C1A7</item> // 开关不可操作_打开 <item name="Primary_color">?attr/TP_color_normal</item> // 主题色 <item name="Primary_dark_color">?attr/NAV_color</item> // 状态栏颜色 <item name="Accent_color">?attr/TP_color_normal</item> // 主题高亮色 <item name="NavigationBarColor">@color/white</item> // 虚拟导航栏颜色 </style>
2.代码配置
Application.onCreate() 初始化过程中注入主题:
Map themeMap = new LinkedHashMap(); themeMap.put("热情红", R.style.Theme_Red); themeMap.put("高雅金", R.style.Theme_GOLD); options.setThemeMap(themeMap);
8. 第三方推送
ServiceFactory.getInstance().getThirdPartyPusher().push(this, "pushKey", null);
9. 疑难解答
错误1:MultiDex错误
构建过程出现以下错误:
Cannot fit requested classes in a single dex file (# methods: 167850 > 65536 ; # fields: 207046 > 65536)
原因:没有开启 MultiDex 编译声明,在 build.gradle(Module:app) 开启:
解决方案:
android { compileSdkVersion 29 defaultConfig { applicationId "com.finogeeks.finochatapp" multiDexEnabled true // 开启声明 .... }
错误2
java.lang.UnsatisfiedLinkError: dalvik.system.PathClassLoader[DexPathList[[zip file "/data/app/com.finogeeks.finchatsdk-09X2htoKGcUERLLIrRwNcQ==/base.apk"],nativeLibraryDirectories=[/data/app/com.finogeeks.finchatsdk-09X2htoKGcUERLLIrRwNcQ==/lib/arm64, /system/lib64, /system/product/lib64]]] couldn't find "libsdkcore.so"
原因:没有声明ABI时App使用错误ABI导致崩溃
解决方案:
android { compileSdkVersion 29 buildToolsVersion "29.0.2" defaultConfig { applicationId "com.finogeeks.finchatsdk" ndk { abiFilters "armeabi", "x86", "armeabi-v7a" } // 声明支持的ABI类型 } ..... }
错误3
报错:
Manifest merger failed : uses-sdk:minSdkVersion 17 cannot be smaller than version 19 declared in library [com.finogeeks.finochat.sdk:finochat-android-sdk:3.4.31]
解决方案:SDK支持最低 minSdkVersion 为19,请自行修改gradle配置