4. 4、FinChat SDK Android 集成文档

4、FinChat SDK Android 集成文档

  • administrators

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

    申请注册凡泰极客开发者账号，申请 AppId 和 AppKey，详细请咨询相关接口人。

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

    要求在 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配置

    0
Locked