跳到主要内容 Flutter tencent_kit 插件 HarmonyOS 平台接入指南:服务端登录模式 | 极客日志
Dart 大前端
Flutter tencent_kit 插件 HarmonyOS 平台接入指南:服务端登录模式 本文介绍 Flutter 项目使用 tencent_kit 插件在 HarmonyOS 平台接入 QQ 登录的完整流程。由于底层限制,仅支持服务端模式登录。主要步骤包括添加依赖、配置腾讯开放平台 AppID 及鸿蒙 BundleName、设置 module.json5 中的 Scheme 回调权限、初始化 SDK 并调用 registerApp 和 setIsPermissionGranted。核心功能为 loginServerSide,返回授权码需经后端换取 access_token。注意事项包括权限调用顺序、授权码有效期及 Scheme 配置细节,避免常见报错如注册失败或无回调。
Pythonist 发布于 2026/3/27 0 浏览在 Flutter 跨平台开发中,tencent_kit 插件为 Android、iOS 及 HarmonyOS 提供了统一的腾讯(QQ)SDK 接入能力。针对 HarmonyOS 平台,该插件受底层 SDK 限制,仅支持服务端模式登录及部分基础功能,本文将严格遵循 pub.dev 官方文档规范,详细拆解接入流程、核心功能实现及注意事项,帮助开发者规避常见报错。
一、核心能力说明(HarmonyOS 平台专属限制)
根据 tencent_kit 6.2.0 版本官方定义,HarmonyOS 平台仅支持以下 4 个核心方法,其他功能(如客户端直接登录、分享拓展类型等)暂不支持:
setIsPermissionGranted:设置权限授权状态(必须在注册应用前调用)
registerApp:初始化并注册应用(关联腾讯开放平台 AppID)
isQQInstalled:判断设备是否安装 QQ 客户端
loginServerSide:服务端模式登录(唯一支持的登录方式,返回授权码用于后端换取 Token)关键提醒:服务端模式下,插件返回的'授权码'存储在 TencentLoginResp.accessToken 字段中,不可直接当作客户端 Token 使用 ,需通过后端接口换取正式的 access_token 和 openid。
二、接入前置准备
2.1 环境要求
Flutter 版本:支持 Flutter 2.5 及以上(兼容配置见下文)
HarmonyOS 版本:支持 HarmonyOS NEXT 系统及以上(模拟器版本≥0.0.68 或真机)
tencent_kit 版本:^6.2.0(最新稳定版)
开发工具:DevEco Studio 4.0+ + Android Studio/VS Code(Flutter 开发环境)
2.2 开发者资质与配置
腾讯开放平台配置:
登录 腾讯开放平台 ,创建鸿蒙平台应用,获取 AppID(纯数字字符串)
完善应用配置:提交鸿蒙应用的 BundleName、签名指纹(参考应用签名配置方法),审核通过后生效
HarmonyOS 应用配置(module.json5):必须按以下格式配置 Scheme 和权限,否则 QQ 回调会失败(字段不可遗漏或修改):
{
"module" : {
"name" : "entry" ,
"type" : "entry" ,
"package" : "com.example.flutterharmony" ,
"versionCode" : 1000000 ,
"versionName" : "1.0.0" ,
"querySchemes" : [
"https" ,
"qqopenapi"
] ,
"abilities" : [
{
"name" : ".MainAbility" ,
"srcEntry" : "./ets/MainAbility/MainAbility.ets" ,
"launchType" : "standard" ,
"skills" : [
{
"entities" : [
"entity.system.browsable"
] ,
"actions" : [
"ohos.want.action.viewData"
] ,
"uris" : [
{
"scheme" : "qqopenapi" ,
"host" : "102061317" ,
"path" : "auth" ,
"linkFeature" : "Login"
}
]
}
]
}
]
}
}
三、完整接入流程(严格按官方步骤)
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 安装依赖
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'接口,流程如下:
接口地址:https://graph.qq.com/oauth2.0/token
请求参数(GET 方式):
grant_type:固定为 authorization_code
client_id:你的腾讯 AppID
client_secret:你的腾讯 AppKey(仅后端存储,不可泄露)
code:客户端传递的授权码(authCode)
redirect_uri:固定为 auth://tauth.qq.com/(与客户端一致)
响应结果:返回 access_token、expires_in(有效期)、refresh_token 等,后端需存储并返回给客户端用于后续操作。
四、关键注意事项(避坑核心)
权限调用顺序 :setIsPermissionGranted(true) 必须在 registerApp() 之前调用,否则会报'权限未授予'错误(官方强制要求)。
授权码用途 :TencentLoginResp.accessToken 是临时授权码(有效期 5 分钟,仅一次有效),不可直接用于获取用户信息,必须通过后端换取正式 access_token。
Scheme 配置 :module.json5 中的 host 必须是纯数字 AppID,path 固定为 auth,否则 QQ 授权后无法回调应用。
分享功能限制 :HarmonyOS 平台暂不支持 tencent_kit 的分享功能,若需实现分享,需结合腾讯官方 HarmonyOS SDK 单独集成。
版本兼容性 :确保 tencent_kit 版本≥6.2.0,低版本可能不支持 HarmonyOS 服务端登录模式。
五、常见报错与解决方案
'SDK 注册失败' :
检查 pubspec.yaml 中 app_id 是否与腾讯开放平台一致(含引号,纯数字);
确认 module.json5 中 package 字段与腾讯开放平台的 BundleName 一致。
登录无回调 / 提示'暂无可用打开方式' :
核对 module.json5 的 skills 配置(scheme、host、actions 字段是否与官方一致);
重启鸿蒙模拟器 / 真机(配置修改后需重启生效)。
'授权码换取 Token 失败' :
检查后端 redirect_uri 是否为 auth://tauth.qq.com/;
确认 client_secret(AppKey)是否正确,且未泄露给客户端。
Flutter 编译报错'找不到模块' :
执行 flutter clean 清理缓存后重新 flutter pub get;
确认 DevEco Studio 已同步鸿蒙 SDK 及项目配置。
总结 tencent_kit 插件为 Flutter 开发者提供了 HarmonyOS 平台的 QQ 登录快捷接入方案,但受限于底层 SDK,仅支持服务端模式登录。核心接入要点可概括为:配置对齐官方要求、权限调用顺序不可错、授权码通过后端换 Token 。遵循本文步骤,可快速实现稳定的 QQ 登录功能,若需扩展分享等功能,需结合腾讯官方 HarmonyOS SDK 单独集成。
微信扫一扫,关注极客日志 微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
相关免费在线工具 Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
Markdown 转 HTML 将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online
HTML 转 Markdown 将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML 转 Markdown在线工具,online
JSON 压缩 通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
JSON美化和格式化 将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online