4、FinChat SDK Android 集成文档


  • administrators

    0. 集成 Android SDK 前的准备工作

    申请注册凡泰极客开发者账号,申请 AppIdAppKey,详细请咨询相关接口人。

    1. Android SDK 介绍及导入

    1.1 Android SDK 介绍

    FinChat SDK 为用户开发 IM 应用提供完善的功能框架。本SDK最低支持Android 4.4(API19),最高支持Android Q,通过Gradle的方式引入依赖。

    架构图如下:

    0_1571299687704_5b962a39c37e1.png

    • 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 创建配置选项

    要求在 ApplicationonCreate() 方法中进行初始化。初始化依赖传入 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配置


Locked