Flutter tencent_kit 插件 HarmonyOS 平台接入指南：服务端登录模式

三、完整接入流程（严格按官方步骤）

3.1 集成 tencent_kit 插件

3.1.1 添加依赖

在 Flutter 项目的 pubspec.yaml 文件中添加插件依赖，配置 AppID（核心参数不可错）：

dependencies:
  flutter: sdk: flutter
  tencent_kit: ^6.2.0
  tencent_kit:
    app_id: "102061317"
    universal_link: ""

3.1.2 安装依赖

执行以下命令安装插件及相关依赖：

flutter pub get

3.1.3 Flutter 2.5 兼容配置（可选）

若使用 Flutter 2.5 版本，需在 ios/Podfile 中添加兼容配置（避免编译报错）：

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'i386 arm64'
    end
  end
end

3.2 核心功能实现（完全对齐官方示例）

3.2.1 初始化与权限设置（必须第一步）

在应用启动时（如 main.dart 或首页初始化），先调用 setIsPermissionGranted 授予权限，再注册应用，顺序不可颠倒：

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late final TencentKit _tencentKit;

  @override
  void initState() {
    super.initState();
    _initTencentKit();
  }

  Future<void> _initTencentKit() async {
    _tencentKit = TencentKit();
    await _tencentKit.setIsPermissionGranted(true);
    final bool isRegistered = await _tencentKit.registerApp();
    if (isRegistered) {
      debugPrint("腾讯 SDK 注册成功");
    } else {
      debugPrint("腾讯 SDK 注册失败，请检查 AppID 配置");
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text("tencent_kit HarmonyOS 示例")),
        body: const Center(child: LoginButton()),
      ),
    );
  }
}

3.2.2 判断 QQ 安装状态

class LoginButton extends StatefulWidget {
  const LoginButton({super.key});

  @override
  State<LoginButton> createState() => _LoginButtonState();
}

class _LoginButtonState extends State<LoginButton> {
  late final TencentKit _tencentKit;
  bool _isQQInstalled = false;

  @override
  void initState() {
    super.initState();
    _tencentKit = TencentKit();
    _checkQQInstalled();
  }

  Future<void> _checkQQInstalled() async {
    final bool result = await _tencentKit.isQQInstalled();
    setState(() => _isQQInstalled = result);
  }

  @override
  Widget build(BuildContext context) {
    return Text(_isQQInstalled ? "已安装 QQ" : "未安装 QQ");
  }
}

3.2.3 服务端模式登录（核心功能）

支持两种授权方式：拉起 QQ 客户端授权（已安装 QQ 时）、H5 扫码授权（未安装 QQ 时，通过 qrcode: true 开启），返回的授权码需传给后端换取 access_token。

Future<void> _loginServerSide() async {
  if (!_isQQInstalled) {
    _doLogin(qrcode: true);
  } else {
    _doLogin(qrcode: false);
  }
}

Future<void> _doLogin({required bool qrcode}) async {
  try {
    final TencentLoginResp resp = await _tencentKit.loginServerSide(
      qrcode: qrcode,
    );
    if (resp.isSuccess) {
      final String authCode = resp.accessToken ?? "";
      debugPrint("授权码获取成功：$authCode");
      await _getAccessTokenFromBackend(authCode);
    } else {
      debugPrint("登录失败：${resp.errorMessage}，错误码：${resp.errorCode}");
    }
  } catch (e) {
    debugPrint("登录异常：$e");
  }
}

Future<void> _getAccessTokenFromBackend(String authCode) async {
  const String backendUrl = "https://你的后端域名/api/qq/token";
  try {
    // 向后端传递 authCode、AppID、redirect_uri（固定为 auth://tauth.qq.com/）
    // 示例请求（实际项目使用 dio 等网络库）
    // final response = await Dio().get(backendUrl, queryParameters: {"appid": "102061317", "code": authCode, "redirect_uri": "auth://tauth.qq.com/"});
    // 解析后端返回的 access_token 和 openid，用于后续获取用户信息
  } catch (e) {
    debugPrint("换取 Token 失败：$e");
  }
}

@override
Widget build(BuildContext context) {
  return ElevatedButton(
    onPressed: _loginServerSide,
    child: Text(_isQQInstalled ? "QQ 客户端登录" : "QQ 扫码登录"),
  );
}

3.2.4 后端 Token 换取逻辑（参考官方规范）

后端需调用腾讯开放平台的'通过授权码获取 Access Token'接口，流程如下：

1. 接口地址：https://graph.qq.com/oauth2.0/token
2. 请求参数（GET 方式）：
   • grant_type：固定为 authorization_code
   • client_id：你的腾讯 AppID
   • client_secret：你的腾讯 AppKey（仅后端存储，不可泄露）
   • code：客户端传递的授权码（authCode）
   • redirect_uri：固定为 auth://tauth.qq.com/（与客户端一致）
3. 响应结果：返回 access_token、expires_in（有效期）、refresh_token 等，后端需存储并返回给客户端用于后续操作。

四、关键注意事项（避坑核心）

1. 权限调用顺序：setIsPermissionGranted(true) 必须在 registerApp() 之前调用，否则会报'权限未授予'错误（官方强制要求）。
2. 授权码用途：TencentLoginResp.accessToken 是临时授权码（有效期 5 分钟，仅一次有效），不可直接用于获取用户信息，必须通过后端换取正式 access_token。
3. Scheme 配置：module.json5 中的 host 必须是纯数字 AppID，path 固定为 auth，否则 QQ 授权后无法回调应用。
4. 分享功能限制：HarmonyOS 平台暂不支持 tencent_kit 的分享功能，若需实现分享，需结合腾讯官方 HarmonyOS SDK 单独集成。
5. 版本兼容性：确保 tencent_kit 版本≥6.2.0，低版本可能不支持 HarmonyOS 服务端登录模式。

五、常见报错与解决方案

1. 'SDK 注册失败'：
   • 检查 pubspec.yaml 中 app_id 是否与腾讯开放平台一致（含引号，纯数字）；
   • 确认 module.json5 中 package 字段与腾讯开放平台的 BundleName 一致。
2. 登录无回调 / 提示'暂无可用打开方式'：
   • 核对 module.json5 的 skills 配置（scheme、host、actions 字段是否与官方一致）；
   • 重启鸿蒙模拟器 / 真机（配置修改后需重启生效）。
3. '授权码换取 Token 失败'：
   • 检查后端 redirect_uri 是否为 auth://tauth.qq.com/；
   • 确认 client_secret（AppKey）是否正确，且未泄露给客户端。
4. Flutter 编译报错'找不到模块'：
   • 执行 flutter clean 清理缓存后重新 flutter pub get；
   • 确认 DevEco Studio 已同步鸿蒙 SDK 及项目配置。

总结

tencent_kit 插件为 Flutter 开发者提供了 HarmonyOS 平台的 QQ 登录快捷接入方案，但受限于底层 SDK，仅支持服务端模式登录。核心接入要点可概括为：配置对齐官方要求、权限调用顺序不可错、授权码通过后端换 Token。遵循本文步骤，可快速实现稳定的 QQ 登录功能，若需扩展分享等功能，需结合腾讯官方 HarmonyOS SDK 单独集成。