FinChat SDK 客户端集成教程之Android篇



  • 集成 Android SDK 前的准备工作

    注册申请凡泰极客开发者账号,申请AppId,AppKey

    详细请咨询相关接口人。

    Android SDK 介绍及导入

    Android SDK 介绍

    FinoChat SDK 为用户开发 IM 相关的应用提供的一套完善的开发框架。包括以下几个部分:

    • SDK_Core: 为核心的消息协议实现,完成与服务器之间的信息交换。
    • SDK: 是基于核心协议实现的完整的 IM 功能,实现了不同类型消息的收发、会话管理、群组、好友、聊天室等功能。
    • HttpEngine: H5资源加速服务组件
    • ConvoUI: 会话型UI交互组件
    • FinoChatClient: 是 SDK 的入口,主要完成初始化等功能,也是获取其他模块的入口。
      • AccountApi: 负责账户管理相关功能,包括登入、登出等。
      • ContacApi: 负责好友的添加删除,黑名单的管理。
      • GroupApi: 负责群组的管理,创建、删除群组,管理群组成员等功能。
      • ChatRoomApi: 负责聊天室的管理。
      • UIApi: 是一组 IM 相关的 UI 控件,旨在帮助开发者快速集成FinoChat SDK。
        • ChatUI: 消息聊天界面UI
        • ConversationUI: 会话列表UI
        • MineUI: “我”的信息UI
        • ContactUI: 通讯录UI

    集成 Android SDK

    在您阅读此文档时,我们假定您已经具备了基础的 Android 应用开发经验,并能够理解相关基础概念,SDK支持Android 4.4及以上iOS版本。

    下载SDK

    请到凡泰极客官网 http://www.finogeeks.com 下载SDK。

    手动导入 SDK

    您可以到凡泰极客官网下载FinoChat SDK。

    到此您已经下载好了 SDK,下面开始学习 SDK 的集成使用吧!

    SDK 目录讲解

    从官网上下载下来的包中分为如下五部分:

    • 凡泰极客 Android FinoChatSDK 开发使用
    • 凡泰极客 Android doc SDK 相关API文档
    • 凡泰极客 Android FinoChatAppDemo 工程源码

    具体接口讲解请转到 Api Docs。

    第三方库介绍

    FinoChatUI 中用到的第三方库:

    • PhotoView: 图片处理库,浏览显示
    • Glide: 用于页面刷新
    • RxJava: 响应式框架

    配置工程

    添加依赖库

    FinoChat Android sdk可以直接通过gradle添加依赖集成:

    dependencies {
    	//finochatsdk 版本号替换为自己要使用的版本
    	implementation “com.finogeeks.finochat.sdk:finochatsdk:latest.release”
        //音视频通话模块 可选配置 不需要可以不添加
        implementation “com.finogeeks.finochat.sdk:finovideochat:latest.release”
    }
    

    编译工程

    以上步骤进行完后,编译工程。如果没有报错,恭喜你,集成 SDK 成功,可以进行下一步了。

    Android SDK使用

    接口文档

    请参考APIDoc

    使用指引

    SDK在集成及导入后接下来就可以使用了。

    第一步:创建配置选项

    要求在 application 的oncreate方法中做初始化,初始化的时候需要传入设置好的 options。

    FinoChatOptions options = new FinoChatOptions();       
    options.setAppKey(“appKey”);
    options.setAppType(“appType”);
    options.setAppId("3");
    options.setApiPrefix("/api/v1");        
    options.setNotificationIcon(R.drawable.login_logo);// 后台运行的icon
    options.setNotificationSubtitle(“正在后台运行”) // 后台运行的文案        
    options.setThemeId(R.style.ChatTheme);//主题配置 可选
    options.setAppDebug(BuildConfig.DEBUG);//是否是debug模式 必须设置       	
    options.setSdkVersion(BuildConfig.VERSION_NAME);//设置页面展示的应用版本号
    options.setSettings(new HashMap<String, Object>() {
        	  {   //一些额外的配置选项 参见api文档  
        	    put("isWatermarkChangeable", true);      	
        	    put("dispatchMode", "B");
        	  } 	
    });
    

    第二步:初始化

    sdk初始化入口主要是对sdk部分配置的初始化和session的初始化,建议初始化成功后,在Application 中做关闭闪屏页跳到主页面的操作:

    FinoChatClient.getInstance().initFinoChatSession(this, options, new FinoCallBack<Void>() {
        @Override
        public void onSuccess(Void result) {
            Log.i(LOG_TAG, "init success");
    	    // 注册监听回调消息未读数(正整数),0为没有未读消息,请自行使用角标库显示数值
    	    // 全局仅需注册一次
    	    FinoChatClient.getInstance()
    		    .getBadgeManager()
    		    .addBadgeCountListener(i -> {Log.i(TAG,“最新未读数:”+i)});
    		SplashActivity.navigate2Home();        
            
        }
        @Override
        public void onProgress(int progress, String status) { }
        @Override
        public void onError(int code, String message) {
            //初始化失败 错误码参见FinoError
            Log.e(LOG_TAG, "code:" + code + message);
        }
    });
    

    注意:如果用户未登录,不会进行session初始化,同时不会回调onSuccess或onError,所以用户需要在启动页或初始化时通过FinoChatClient.getInstance().accountManager().isLogin()先判断是否为登录状态,如果是未登录状态,则应该跳转到登录页面或执行登录操作,登录成功后sdk会自动执行session的初始化。示例:

    //在闪屏页判断
    if (!FinoChatClient.getInstance().accountManager().isLogin()) { 
        startActivity(new Intent(this, LoginActivity.class));
        finish();
        return;
    } else if (FinoChatClient.getInstance().isSessionInitSuccess()) {           
        startActivity(new Intent(SplashActivity.this, HomeActivity.class));
        finish();
        return;
    }
    

    第三步: 用户登录

    FinoChatClient.getInstance().accountManager().login(username, password, new FinoCallBack<Map<String, Object>>() {//回调
        @Override
        public void onSuccess(Map<String, Object> result) {
            SplashActivity.navigate2Home();
        }
        @Override
        public void onProgress(int progress, String status) {
            startActivity(new Intent(LoginActivity.this, SplashActivity.class));
            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的登录接口。

    主页面搭建

    为了提供灵活的页面配置,sdk没有提供默认主页面,而是提供了对应的Fragment供用户自由组装,其中包括“会话“页面、”通讯录“页面和”我的“页面。开发者可以通过FinoChatClient.getInstance().chatUIManager().conversationFragment()获取对应的Fragment组装主页面。

    主要API接口

    sdk对外暴露的API接口主要在com.finogeeks.finochat.sdk包中:

    • FinoChatClient :客户端主要入口,提供初始化接口和获取其他服务;
    • IAccountManager:账户相关接口,包括登录 注销 登录状态判断等;
    • IChatUiManager:UI相关接口,用户获取一些Fragment以及启动一些页面或对话框;
    • INotificationManager:sdk事件通知接口,可以用于监听sdk内部事件 如退出登录然后执行自己的操作;
    • IPluginManager : 一些UI定制的接口 例如可以在聊天页面更多菜单里注册自己的选项并获取事件监听 也可以定制我的页面的项目;