微信小程序（uniapp）对接腾讯云IM

news2025/6/3 4:37:59

UniApp 对接腾讯云 IM（即时通讯）完整指南

一、项目背景与需求分析

随着社交场景的普及，即时通讯功能已成为移动应用的标配。腾讯云 IM（Tencent IM，即 TIM）提供稳定可靠的即时通讯服务，支持单聊、群聊、消息推送等核心功能。本文将详细讲解如何在 uniapp 框架下实现腾讯云 IM 的无缝对接，覆盖微信小程序、H5 等多端适配。

二、技术选型与前置条件

开发环境要求
- HBuilderX 3.4+（推荐最新版）
- 微信开发者工具（小程序端调试）
- 腾讯云控制台账号（立即注册）
服务端准备
- 创建腾讯云通信应用（获取 SDKAppID）
- 配置用户鉴权服务（需自行实现签名算法）
- 配置合法域名（webim.tim.qq.com 等）

客户端依赖

// package.json
"dependencies": {
  "tim-js-sdk": "^2.22.1",
  "tim-upload-plugin": "^1.1.0"
}

三、核心实现步骤

1. 初始化 SDK（条件编译处理）

// utils/tim.js
let TIM = null

// 微信小程序环境
#ifdef MP-WEIXIN
TIM = require('tim-wx-sdk')
#endif

// H5 环境
#ifdef H5
TIM = require('tim-js-sdk')
#endif

// 通用插件配置
const uploadPlugin = require('tim-upload-plugin')

export default function createTIM(options) {
  const tim = TIM.create({
    SDKAppID: options.SDKAppID
  })

  tim.registerPlugin({ 'tim-upload-plugin': uploadPlugin })
  return tim
}

2. 登录模块实现

// services/im.js
import createTIM from '@/utils/tim'

let timInstance = null

export function initIM(options) {
  if (!timInstance) {
    timInstance = createTIM(options)
  }
  return timInstance
}

// 登录逻辑
export async function loginIM({ userID, userSig }) {
  const tim = initIM({ SDKAppID: process.env.VUE_APP_SDK_APPID })
  
  return new Promise((resolve, reject) => {
    tim.login({
      userID,
      userSig
    }).then(imResponse => {
      console.log('登录成功', imResponse.data)
      resolve(imResponse.data)
    }).catch(imError => {
      console.error('登录失败:', imError)
      reject(imError)
    })
  })
}

3. 消息收发核心代码

// 发送文本消息
export function sendTextMessage(to, text) {
  const tim = initIM()
  const message = tim.createTextMessage({
    to,
    conversationType: 'C2C', // 单聊
    payload: { text }
  })

  tim.sendMessage(message).then(res => {
    console.log('发送成功', res)
  }).catch(err => {
    uni.showToast({ title: '发送失败', icon: 'none' })
  })
}

// 消息监听
export function setupMessageListener(callback) {
  const tim = initIM()
  tim.on(tim.EVENT.MESSAGE_RECEIVED, (event) => {
    const messages = event.data
    messages.forEach(msg => {
      callback(msg)
    })
  })
}

4. 会话管理实现

// 获取会话列表
export function getConversationList() {
  const tim = initIM()
  return tim.getConversationList().then(res => {
    return res.data.conversationList || []
  })
}

// 创建群聊
export async function createGroup(options) {
  const tim = initIM()
  return tim.createGroup({
    type: 'Public', // 公开群
    name: options.name,
    groupID: options.groupID,
    memberList: options.members
  })
}

四、关键问题解决方案

1. 用户签名生成（服务端示例）

# Python 示例（需自行实现）
import hashlib
import hmac
import base64
import time

def generate_user_sig(user_id, sdk_app_id, key):
    expire = int(time.time()) + 86400 * 180  # 180天有效期
    signature = hmac.new(
        key.encode('utf-8'),
        f'WebSDKAppId={sdk_app_id}&Identifier={user_id}&UserBuf=&Expire={expire}&'
        .encode('utf-8'),
        hashlib.sha1
    ).digest()
    
    return base64.b64encode(signature).decode() + f'|{expire}'

2. 微信小程序域名配置

// manifest.json
{
  "mp-weixin": {
    "appid": "your_appid",
    "permission": {
      "scope.userInfo": {
        "desc": "需要获取用户信息以登录IM"
      }
    },
    "requiredPrivateInfos": [
      "getUserInfo",
      "getUserProfile"
    ]
  }
}

3. 消息类型扩展

// 自定义消息类型示例
const tim = initIM()

// 创建红包消息
const redPacketMessage = tim.createCustomMessage({
  to: 'user123',
  conversationType: 'C2C',
  payload: {
    data: JSON.stringify({
      type: 'red_packet',
      amount: 100,
      description: '新年红包'
    }),
    extension: ''
  }
})