导入 SDK

融云提供了Flutter平台的IMKit SDK，以下是导入SDK的步骤。

环境要求

• Flutter 3.27.0 及以上版本
• Dart 3.6.0 及以上版本
• Android Studio Meerkat 及以上版本（用于Android开发）
• Xcode 16.0 及以上版本（用于iOS开发）
• Android 6.0 (API level 23) 及以上版本（Android平台）
• iOS 15.0 及以上版本（iOS平台）

安装依赖

使用 Dart 的包管理工具 pub 来安装 SDK。在项目的 pubspec.yaml 文件中添加以下依赖：

yaml

dependencies:
  rongcloud_im_kit: ^x.y.z  # 请使用最新版本号

然后在命令行中运行：

bash

flutter pub get

注意

具体的版本号可前往融云官网 SDK 下载页面或者pub.dev查询。

配置平台特定设置

Android 平台

1. 在 android/app/build.gradle 文件中添加以下配置：

gradle

android {
    defaultConfig {
        // 请根据实际情况设置最小SDK版本
        minSdkVersion 23
    }
    
    // 添加Java 8特性支持
    compileOptions {
        // 启用desugaring以支持较新的Java API
        coreLibraryDesugaringEnabled true
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8
    }
    
    // 可选：添加签名配置
    signingConfigs {
        release {
            storeFile file("./your-key.jks")  // 密钥文件路径
            storePassword "yourPassword"      // 密钥库密码
            keyAlias "yourAlias"              // 密钥别名
            keyPassword "yourKeyPassword"     // 密钥密码
        }
    }
    
    // ProGuard混淆配置（可选但推荐）
    buildTypes {
        release {
            // 启用代码混淆
            minifyEnabled true
            // 启用资源压缩
            shrinkResources true
            // 指定ProGuard规则文件
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            // 使用签名配置
            signingConfig signingConfigs.release
        }
    }
}

dependencies {
    // 添加desugaring支持库
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.4'
    // 添加窗口管理相关依赖
    implementation("androidx.window:window:1.0.0")
    implementation("androidx.window:window-java:1.0.0")
}

2. 创建 android/app/proguard-rules.pro 文件，添加以下内容以保护融云SDK代码：

proguard

# 融云SDK混淆规则
-keepattributes Exceptions,InnerClasses,Signature
-keep class io.rong.** {*;}
-keep class cn.rongcloud.** {*;}
-keep class * implements io.rong.imlib.model.MessageContent {*;}
-dontwarn io.rong.**
-dontwarn cn.rongcloud.**

3. 在 android/app/src/main/AndroidManifest.xml 文件中添加必要的权限和配置：

xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 网络权限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    
    <!-- 本地通知权限 -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.VIBRATE" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
    
    <!-- 存储权限 -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    
    <!-- 多媒体相关权限 -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.CAMERA" />
    
    <application
        android:label="你的应用名称"
        android:icon="@mipmap/ic_launcher"
        android:usesCleartextTraffic="true"
        android:networkSecurityConfig="@xml/network_security_config">
        
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:taskAffinity=""
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:hardwareAccelerated="true"
            android:windowSoftInputMode="adjustResize">
            <!-- 其他Activity配置 -->
        </activity>
        
        <!-- Flutter插件注册 -->
        <meta-data
            android:name="flutterEmbedding"
            android:value="2" />
    </application>
    
    <!-- 文本处理相关查询（Flutter引擎需要） -->
    <queries>
        <intent>
            <action android:name="android.intent.action.PROCESS_TEXT"/>
            <data android:mimeType="text/plain"/>
        </intent>
    </queries>
</manifest>

AndroidManifest.xml配置说明

• 网络权限：用于IM通信和媒体消息传输。
• 本地通知权限：用于接收消息时显示通知，提升用户体验。从Android 13开始，POST_NOTIFICATIONS权限必须显式请求，否则无法显示消息通知。
• 网络安全配置：
  • usesCleartextTraffic="true"：允许应用使用明文网络流量（HTTP）
  • networkSecurityConfig：自定义网络安全策略，适应开发和测试环境
• Activity配置：
  • launchMode="singleTop"：防止重复启动活动
  • taskAffinity=""：控制任务栈行为
  • configChanges属性：控制配置变化时活动不重启
  • windowSoftInputMode="adjustResize"：键盘弹出时调整布局
• 查询配置：Flutter 引擎在处理文本时需要的权限声明。

4. 创建 android/app/src/main/res/xml/network_security_config.xml 文件，添加以下内容：

xml

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
        </trust-anchors>
    </base-config>
</network-security-config>

iOS 平台

1. 在 ios/Runner/Info.plist 文件中添加必要的权限和配置：

xml

<dict>
    <!-- 必要的权限说明 -->
    <key>NSCameraUsageDescription</key>
    <string>使用摄像头拍摄图片发送消息</string>
    
    <key>NSMicrophoneUsageDescription</key>
    <string>使用麦克风发送语音消息</string>
    
    <key>NSPhotoLibraryUsageDescription</key>
    <string>使用相册选择图片发送消息</string>
    
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>使用位置权限发送位置消息</string>
    
    <key>NSAppleMusicUsageDescription</key>
    <string>使用音乐文件夹发送文件</string>
    
    <!-- 网络安全设置 -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
        <key>NSExceptionDomains</key>
        <dict>
            <key>dualstack-collection.rongcloud.net</key>
            <dict>
                <key>NSExceptionAllowsInsecureHTTPLoads</key>
                <true/>
                <key>NSIncludesSubdomains</key>
                <true/>
            </dict>
        </dict>
    </dict>
    
    <!-- URL Scheme 查询支持 -->
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>http</string>
        <string>https</string>
    </array>
    
    <!-- 文档支持配置 -->
    <key>LSSupportsOpeningDocumentsInPlace</key>
    <true/>
    <key>UISupportsDocumentBrowser</key>
    <true/>
    
    <!-- 可选：如需支持后台推送，取消注释以下部分 -->
    <!-- 
    <key>UIBackgroundModes</key>
    <array>
        <string>remote-notification</string>
    </array>
    -->
    
    <!-- 其他默认配置 -->
    <key>UIApplicationSupportsIndirectInputEvents</key>
    <true/>
    <key>CADisableMinimumFrameDurationOnPhone</key>
    <true/>
    
    <!-- 支持的界面方向 -->
    <key>UISupportedInterfaceOrientations</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
</dict>

2. 确保 ios/Podfile 中的 iOS 版本设置正确：

ruby

platform :ios, '15.0'

3. 修改 ios/Runner/AppDelegate.swift 文件以支持本地通知（如果使用Objective-C，修改对应的AppDelegate.m文件）：

对于Swift：

swift

import Flutter
import UIKit
import flutter_local_notifications  // 添加本地通知插件导入

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    // 设置本地通知插件回调
    FlutterLocalNotificationsPlugin.setPluginRegistrantCallback { (registry) in
        GeneratedPluginRegistrant.register(with: registry)
    }

    // 设置通知中心代理（iOS 10及以上）
    if #available(iOS 10.0, *) {
      UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate
    }
    
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

对于Objective-C：

objc

#import "AppDelegate.h"
#import "GeneratedPluginRegistrant.h"
#import <flutter_local_notifications/FlutterLocalNotificationsPlugin.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // 设置本地通知插件回调
  [FlutterLocalNotificationsPlugin setPluginRegistrantCallback:^(NSObject<FlutterPluginRegistry> *registry) {
    [GeneratedPluginRegistrant registerWithRegistry:registry];
  }];
  
  // 设置通知中心代理（iOS 10及以上）
  if (@available(iOS 10.0, *)) {
    [UNUserNotificationCenter currentNotificationCenter].delegate = (id<UNUserNotificationCenterDelegate>) self;
  }
  
  [GeneratedPluginRegistrant registerWithRegistry:self];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

AppDelegate配置说明

1. 本地通知配置：

   • 设置插件注册回调，确保通知能正确处理
   • 这些配置对接收IM消息时显示本地通知至关重要

2. 通知中心代理：

   • 在iOS 10及以上版本，设置通知中心代理
   • 允许应用在前台运行时也能收到通知
   • 提升用户体验，确保消息不会被错过

iOS配置说明

1. 隐私权限：

   • 相机、麦克风、相册权限是发送多媒体消息必需的
   • 位置权限用于发送位置消息
   • 每个权限都需要提供明确的使用说明

2. 网络安全配置：

   • NSAllowsArbitraryLoads 允许应用使用HTTP连接
   • NSExceptionDomains 为融云服务器域名设置特殊的网络安全例外

3. URL和文档支持：

   • LSApplicationQueriesSchemes 允许应用打开HTTP/HTTPS链接
   • LSSupportsOpeningDocumentsInPlace 支持文件处理，用于发送和查看文件消息

4. 后台模式：

   • 如需支持应用在后台接收推送通知，应启用 remote-notification 后台模式

5. 最低iOS版本：

   • 需设置为iOS 15.0或更高，以支持SDK的全部功能

初始化与连接

在应用启动时初始化 SDK：

Dart

import 'package:rongcloud_im_kit/rongcloud_im_kit.dart';
import 'package:provider/provider.dart';
import 'package:rongcloud_im_kit/app_providers.dart'; // 引入Provider配置

// 在主应用中确保已配置Provider
// 使用 RongCloudAppProviders.of 来包裹你的根组件
runApp(
  RongCloudAppProviders.of(
    MyApp(), // 你的根组件
    additionalProviders: [ // 可以添加额外的Provider
      // ...
    ],
  ),
);

// 在需要初始化的页面中获取Provider
final engineProvider = Provider.of<RCKEngineProvider>(context, listen: false);

// 初始化并连接到融云服务器

final engine = await engineProvider.engineCreate(
  appKey,
  options,
);

await engineProvider.engineConnect(
  token,
  100,
  onResult: (code) {
    if (code == 0) {
      //连接成功
    } else {
      //错误提示
    }
  },
);

使用 IMKit 的 UI 组件

在需要使用会话列表的页面中：

Dart

import 'package:flutter/material.dart';
import 'package:rongcloud_im_kit/rongcloud_im_kit.dart';

class ConversationListScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('会话列表'),
      ),
      body: RCKConvoPage(),
    );
  }
}

在需要使用聊天页面的页面中：

Dart

import 'package:flutter/material.dart';
import 'package:rongcloud_im_kit/rongcloud_im_kit.dart';

class ChatScreen extends StatelessWidget {
  final RCIMIWConversation conversation;
  
  ChatScreen({required this.conversation});
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('聊天'),
      ),
      body: RCKChatPage(
        conversation: conversation,
      ),
    );
  }
}