快速开始

这份文档将指导您集成 IMKit 并快速开始聊天。

前提条件

前往ZEGO管理控制台并执行以下操作：
1. 创建一个项目，并获取您的项目的AppID和AppSign。
2. 激活即时通讯服务。

准备环境：
- Android Studio Arctic Fox（2020.3.1）或更高版本
- Android SDK包：Android SDK 30，Android SDK平台-工具30
- 运行在Android 5.0或更高版本且支持音频和视频的Android设备或模拟器。我们建议您使用真实设备。
- Android设备和您的计算机已连接到互联网。

集成 SDK

将 com.github.ZEGOCLOUD:zego_inapp_chat_uikit_android 添加为依赖项

添加 jitpack 配置

Android Gradle 插件版本为 7.1.0 或更高

进入项目的根目录，打开 settings.gradle 文件，将 jitpack 添加到 dependencyResolutionManagement > repositories 中，如下所示：

settings.gradle

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
      google()
      mavenCentral()
// !mark(1:2)
      maven { url 'https://maven.zego.im' }   // <- Add this line.
      maven { url 'https://www.jitpack.io' } // <- Add this line.
   }
}

settings.gradle

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
      google()
      mavenCentral()
// !mark(1:2)
      maven { url 'https://maven.zego.im' }   // <- Add this line.
      maven { url 'https://www.jitpack.io' } // <- Add this line.
   }
}

警告

如果在settings.gradle中找不到上述字段，可能是因为您的Android Gradle插件版本低于v7.1.0。

更多详细信息，请参阅Android Gradle插件发布说明v7.1.0。

Android Gradle插件版本低于7.1.0

进入项目的根目录，打开build.gradle文件，将jitpack添加到allprojects > repositories中，如下所示：

build.gradle

allprojects {
    repositories {
        google()
        mavenCentral()
// !mark(1:2)
        maven { url 'https://maven.zego.im' }   // <- Add this line.
        maven { url "https://jitpack.io" }  // <- Add this line.
    }
}

build.gradle

allprojects {
    repositories {
        google()
        mavenCentral()
// !mark(1:2)
        maven { url 'https://maven.zego.im' }   // <- Add this line.
        maven { url "https://jitpack.io" }  // <- Add this line.
    }
}

修改应用级 build.gradle 文件

dependencies {
    ...
// !mark
    implementation 'com.github.ZEGOCLOUD:zego_inapp_chat_uikit_android:+'    // add this line in your module-level build.gradle file's dependencies, usually named [app].
}

dependencies {
    ...
// !mark
    implementation 'com.github.ZEGOCLOUD:zego_inapp_chat_uikit_android:+'    // add this line in your module-level build.gradle file's dependencies, usually named [app].
}

调用 init 方法来初始化 IMKit

MyApplication.java


import android.app.Application;

import com.zegocloud.zimkit.services.ZIMKit;

public class MyApplication extends Application {
    public static MyApplication sInstance;

    @Override
    public void onCreate() {
        super.onCreate();
        sInstance = this;
        Long appId = ;    // The AppID you get from ZEGOCLOUD Admin Console.
        String appSign = ;    // The App Sign you get from ZEGOCLOUD Admin Console.
// !mark
        ZIMKit.initWith(this,appId,appSign);
        // Online notification for the initialization (use the following code if this is needed).
        ZIMKit.initNotifications();
    }
}

MyApplication.java


import android.app.Application;

import com.zegocloud.zimkit.services.ZIMKit;

public class MyApplication extends Application {
    public static MyApplication sInstance;

    @Override
    public void onCreate() {
        super.onCreate();
        sInstance = this;
        Long appId = ;    // The AppID you get from ZEGOCLOUD Admin Console.
        String appSign = ;    // The App Sign you get from ZEGOCLOUD Admin Console.
// !mark
        ZIMKit.initWith(this,appId,appSign);
        // Online notification for the initialization (use the following code if this is needed).
        ZIMKit.initNotifications();
    }
}

在登录页面上调用 connectUser 方法以登录到 IMKit

警告

您可以自定义规则来生成用户ID和用户名。我们建议您设置一个有意义的用户ID。您可以将用户ID与您的业务账户系统关联起来。

MyZIMKitActivity.java


import android.content.Intent;
import android.os.Bundle;

import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;

import im.zego.zim.enums.ZIMErrorCode;
import com.zegocloud.zimkit.services.ZIMKit;

public class MyZIMKitActivity extends AppCompatActivity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    }

    public void buttonClick() {
        // 用户ID和用户名：1到32个字符，只能包含数字、字母和以下特殊字符：'~'、'!'、'@'、'#'、'$'、'%'、'^'、'&'、'*'、'('、')'、'_'、'+'、'='、'-'、'`'、';'、'’'、','、'.'、'<'、'>'、'/'、'\'。
        String userId = ; // 作为用户的您的ID。
        String userName = ; // 作为用户的您的姓名。
        String userAvatar = ; // 您设置的用户头像必须是网络图片。例如，https://doc-media.zego.im/IMKit/avatar/avatar-0.png。
        connectUser(userId, userName,userAvatar);
    }

    public void connectUser(String userId, String userName,String userAvatar) {
        // Logs in.
// !mark(1:8)
        ZIMKit.connectUser(userId,userName,userAvatar, errorInfo -> {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 成功登录后的操作。只有在成功登录后，您才会被重定向到其他模块。在这个示例代码中，您将被重定向到对话模块。
                toConversationActivity();
            } else {

            }
        });
    }

    // 将会话列表集成到您的Activity中作为一个Fragment。
    private void toConversationActivity() {
      // 重定向到您创建的会话列表（Activity）。
      Intent intent = new Intent(this,ConversationActivity.class);
      startActivity(intent);
    }
}

MyZIMKitActivity.java


import android.content.Intent;
import android.os.Bundle;

import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;

import im.zego.zim.enums.ZIMErrorCode;
import com.zegocloud.zimkit.services.ZIMKit;

public class MyZIMKitActivity extends AppCompatActivity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    }

    public void buttonClick() {
        // 用户ID和用户名：1到32个字符，只能包含数字、字母和以下特殊字符：'~'、'!'、'@'、'#'、'$'、'%'、'^'、'&'、'*'、'('、')'、'_'、'+'、'='、'-'、'`'、';'、'’'、','、'.'、'<'、'>'、'/'、'\'。
        String userId = ; // 作为用户的您的ID。
        String userName = ; // 作为用户的您的姓名。
        String userAvatar = ; // 您设置的用户头像必须是网络图片。例如，https://doc-media.zego.im/IMKit/avatar/avatar-0.png。
        connectUser(userId, userName,userAvatar);
    }

    public void connectUser(String userId, String userName,String userAvatar) {
        // Logs in.
// !mark(1:8)
        ZIMKit.connectUser(userId,userName,userAvatar, errorInfo -> {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 成功登录后的操作。只有在成功登录后，您才会被重定向到其他模块。在这个示例代码中，您将被重定向到对话模块。
                toConversationActivity();
            } else {

            }
        });
    }

    // 将会话列表集成到您的Activity中作为一个Fragment。
    private void toConversationActivity() {
      // 重定向到您创建的会话列表（Activity）。
      Intent intent = new Intent(this,ConversationActivity.class);
      startActivity(intent);
    }
}

显示 IMKit 的会话组件

ConversationActivity的布局在activity_conversation.xml中指定：

ConversationActivity.java

   public class ConversationActivity extends AppCompatActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
// !mark
        setContentView(R.layout.activity_conversation);
    }

}

   public class ConversationActivity extends AppCompatActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
// !mark
        setContentView(R.layout.activity_conversation);
    }

}

理想情况下，到这个时候，您的应用程序应该是这个样子的：

开始聊天

IMKit 支持以下功能：

开始一对一聊天

警告

无论是开始一对一聊天还是群聊，你想要聊天的用户或者你想要邀请的群聊成员必须至少登录过 IMKit 一次。否则，将会出现错误。

使用您自己的业务逻辑生成userId（这里的userId是指您想要与之聊天的对等用户）。
填写userId参数并运行以下代码：

private void startSingleChat(String userId) {
// !mark
    ZIMKitRouter.toMessageActivity(this, userId, ZIMKitConversationType.ZIMKitConversationTypePeer);
}

private void startSingleChat(String userId) {
// !mark
    ZIMKitRouter.toMessageActivity(this, userId, ZIMKitConversationType.ZIMKitConversationTypePeer);
}

开始一个群聊

使用您自己的业务逻辑获取生成的 ids 和 groupName。（这里的 ids 指的是您想邀请加入群聊的用户的ID列表。）
填写 ids 和 groupName 参数，并运行以下代码：

public void createGroupChat(List<String> ids, String groupName) {
    if (ids == null || ids.isEmpty()) {
        return;
    }
// !mark(1:13)
    ZIMKit.createGroup(groupName, ids, (groupInfo, inviteUserErrors, errorInfo) -> {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            if (!inviteUserErrors.isEmpty()) {
                // 根据您的业务逻辑，当群组中存在一个不存在的用户ID时实现提示窗口的逻辑。
            } else {
                // 成功创建群聊后直接进入聊天页面。
                ZIMKitRouter.toMessageActivity(this, groupInfo.getId(),
                        ZIMKitConversationType.ZIMKitConversationTypeGroup);
            }
        } else {
                // 根据返回的错误信息实现提示窗口的逻辑，用于在创建群聊失败时使用。
        }
    });
}

public void createGroupChat(List<String> ids, String groupName) {
    if (ids == null || ids.isEmpty()) {
        return;
    }
// !mark(1:13)
    ZIMKit.createGroup(groupName, ids, (groupInfo, inviteUserErrors, errorInfo) -> {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            if (!inviteUserErrors.isEmpty()) {
                // 根据您的业务逻辑，当群组中存在一个不存在的用户ID时实现提示窗口的逻辑。
            } else {
                // 成功创建群聊后直接进入聊天页面。
                ZIMKitRouter.toMessageActivity(this, groupInfo.getId(),
                        ZIMKitConversationType.ZIMKitConversationTypeGroup);
            }
        } else {
                // 根据返回的错误信息实现提示窗口的逻辑，用于在创建群聊失败时使用。
        }
    });
}

加入一个群聊

使用您自己的业务逻辑生成groupId（这里的groupId指的是您想要加入的群聊）。
填写groupId参数并运行以下代码：

public void joinGroupChat(String groupId) {
// !mark(1:8)
    ZIMKit.joinGroup(groupId, (groupInfo, errorInfo) -> {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 成功加入群聊后，进入群聊页面。
            ZIMKitRouter.toMessageActivity(this, groupInfo.getId(), ZIMKitConversationType.ZIMKitConversationTypeGroup);
        } else {
            // 根据返回的错误信息实现提示窗口的逻辑，用于在加入群聊失败时使用。
        }
    });
}

public void joinGroupChat(String groupId) {
// !mark(1:8)
    ZIMKit.joinGroup(groupId, (groupInfo, errorInfo) -> {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 成功加入群聊后，进入群聊页面。
            ZIMKitRouter.toMessageActivity(this, groupInfo.getId(), ZIMKitConversationType.ZIMKitConversationTypeGroup);
        } else {
            // 根据返回的错误信息实现提示窗口的逻辑，用于在加入群聊失败时使用。
        }
    });
}

快速开始

前提条件

集成 SDK

开始聊天

相关指南