cordova-plugin-qqsdk

一款专为Cordova/PhoneGap应用设计的QQ SDK集成插件，支持iOS、Android和OHOS三平台，快速实现QQ登录、QQ分享、获取用户信息等核心功能，适配QQ官方最新SDK版本，满足移动应用的社交化需求。

概述

cordova-plugin-qqsdk封装了QQ官方开放平台的iOS、Android SDK和OHOS，提供统一的JavaScript API接口。开发者无需深入原生开发即可快速集成QQ登录、分享到QQ好友/空间、获取QQ用户基本信息等功能，解决了Cordova应用接入QQ社交能力的繁琐问题。

核心特性

• QQ登录：支持标准QQ登录授权流程，获取access_token和openid，支持快速登录（已安装QQ客户端）和网页登录（未安装QQ客户端）

• 用户信息获取：通过授权后获取QQ用户昵称、头像、性别、省份等基本信息

• QQ分享：支持分享文本、图片、链接、音乐、视频、小程序等多种类型内容到QQ好友或QQ空间

• 授权管理：支持检查QQ客户端安装状态、获取当前授权信息、清除本地授权缓存

• 回调统一：所有操作结果通过Promise和回调函数两种方式返回，适配不同编码习惯

• 错误处理：完善的错误码体系，覆盖授权失败、分享取消、客户端未安装等各类场景

• 无侵入性：插件集成后不影响原有应用逻辑，API简洁直观，快速上手

• 隐私合规：遵循QQ开放平台隐私政策，授权前明确提示用户，获取信息范围可控

前置准备

在集成插件前，需在QQ开放平台完成应用注册和配置，获取必要的密钥信息：

1. 登录QQ开放平台，进入「管理中心」创建移动应用

2. 填写应用基本信息（名称、图标、包名/ Bundle ID等），提交审核（审核通过后才能正式使用）

3. 审核通过后，在应用详情页获取「APP ID」和「APP Key」（后续配置需使用）

4. 配置授权回调域：iOS端为应用的Bundle ID，Android端为应用的包名（需与工程配置一致）

注意：测试阶段可使用QQ开放平台的测试账号，无需等待审核通过，但正式上线前必须完成应用审核。

安装

在Cordova项目根目录下执行以下命令安装插件，支持从GitHub或本地路径安装，安装时需指定QQ开放平台获取的APP ID：

#安装hcordova
npm install -g hcordova

# 基础安装
hcordova plugin add cordova-plugin-qqsdk --variable QQ_APP_ID=QQ_APP_ID

# 指定OHOS安装
hcordova plugin add cordova-plugin-qqsdk --variable QQ_APP_ID=QQ_APP_ID --platform ohos

# 从GitHub安装（推荐，获取最新稳定版）
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-qqsdk.git --variable QQ_APP_ID=QQ_APP_ID --platform ohos

卸载

如需移除插件，在项目根目录执行以下命令：

# 全平台卸载
cordova plugin remove cordova-plugin-qqsdk

#指定OHOS卸载
cordova plugin remove cordova-plugin-qqsdk --platform ohos

OHOS配置

1. 修改项目中的oh-package.json5文件，在dependencies中加入QQ @tencent/qq-open-sdk 的依赖项：

{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
     "@tencent/qq-open-sdk": "^1.0.3",
    "@magongshou/harmony-cordova": "file:../cordova"
  }
}

2 工程级modules.json5中添加

 "querySchemes": [
    "https",
    "weixin",
    "wxopensdk",
    "qqopenapi", //添加qq的Schemes
    "amapuri"
],

另外还需要再modules.json5中配置App link https://wiki.connect.qq.com/harmonyos_sdk%e7%8e%af%e5%a2%83%e6%90%ad%e5%bb%ba

3. 修改项目中的EntryAbility的代码，添加QQ插件在ArkTS侧监听和初始化：

export default class EntryAbility extends UIAbility {
   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
      //添加如下代码，注册QQ监听插件
      //QQAction/QQAction,动态导入微信插件
      //EntryAbility 微信插件的入口函数
      //1107765192，在qq开放平台获取的appID
      PluginRegisterHandle(this, want, "QQAction/QQAction", "EntryAbility", "1107765192");
      
   }

   onNewWant(want: Want): void {
      //添加如下代码，注册QQ监听插件
      //QQAction/QQAction,动态导入微信插件
      //EntryAbility 微信插件的入口函数
      //1107765192，在qq开放平台获取的appID
      PluginRegisterHandle(this, want, "QQAction/QQAction", "EntryAbility", "1107765192");
   }
}

核心API说明

插件挂载在QQSDK对象上，所有API均支持Promise和回调函数两种调用方式，推荐使用Promise链式调用以优化代码可读性。

1. 基础工具API

1.1 检查QQ客户端是否安装

判断设备是否安装了QQ客户端，用于提前提示用户安装以支持快速登录和分享。

function checkClientInstalled() {
  var args = {};
  args.client = QQSDK.ClientType.QQ;//支持：QQSDK.ClientType.QQ, 当前版本OHOS不支持：QQSDK.ClientType.TIM;
  QQSDK.checkClientInstalled(function () {
      document.getElementById("checkClientInstalled").innerHTML = 'client is installed';
  }, function () {
      // if installed QQ Client version is not supported sso,also will get this error
      document.getElementById("checkClientInstalled").innerHTML = 'client is not installed';
  }, args);
}

1.2 获取QQ登录授权

获取本地缓存的QQ授权信息（access_token、openid等），用于判断用户是否已授权。

function ssoLogin() {
    var args = {};
    args.client = QQSDK.ClientType.QQ;//支持：QQSDK.ClientType.QQ, 当前版本OHOS不支持：QQSDK.ClientType.TIM;
    QQSDK.ssoLogin(function (result) {
        document.getElementById("ssoLogin").innerHTML = "authCode:" + result.authCode;
        //获取openID,推荐后台获取，这里提供前台获取方法，Android的SDK会返回openid，但是鸿蒙官方推荐后台获取
        getOpenIdSimple(
            result.authCode,
            "1107765192", //appID
            "joO6TGfk1CzHAddf" //appKey，推荐保存到后台，
        );
    }, function (failReason) {
        document.getElementById("ssoLogin").innerHTML = JSON.stringify(failReason);
    }, args);
}

//前台通过js获取openId（JQuery发送请求获取，实际业务根据您的框架发送请求，推荐后台获取）
function getOpenIdSimple(authCode, appId, appKey) {
    $.getJSON('https://graph.qq.com/oauth2.0/token?grant_type=authorization_code&client_id=' + appId + '&client_secret=' + appKey + '&code=' + authCode + '&fmt=json')
        .done(function(token) {
            if (token.error) {
                console.log('Token错误:', token.error);
                return;
            }
            $.getJSON('https://graph.qq.com/oauth2.0/me?access_token=' + token.access_token + '&fmt=json')
                .done(function(data) {
                    console.log('OpenID:', data.openid);
                    console.log('Token:', token.access_token);
                    openId = data.openid;
                })
                .fail(function() {
                    console.log('获取openid失败');
                });
        })
        .fail(function() {
            console.log('获取token失败');
        });
}

1.3 分享图文

当前HarmonOS只支持分享图文

在当前OHOS的QQSDK版本中url,title,description image分享参数必须传

function ssoShare() {
    var args = {};
    args.client = QQSDK.ClientType.QQ;//QQSDK.ClientType.QQ,QQSDK.ClientType.TIM;
    args.scene = QQSDK.Scene.QQ;//QQSDK.Scene.QQZone,QQSDK.Scene.Favorite
    args.url = 'https://cordova.apache.org'; 
    args.title = '这个是 Cordova QQ 新闻分享的标题';
    args.description = '这个是 Cordova QQ 新闻分享的描述';
    args.image = 'https://cordova.apache.org/static/img/cordova_bot.png';
    args.openId = openId;
    args.appKey = "joO6TGfk1CzHAdtC"; //推荐保存到后台
    QQSDK.shareNews(function (info) {
        document.getElementById("ssoShare").innerHTML = JSON.stringify(info);
    }, function (failReason) {
        alert(failReason);
    }, args);
}

许可证

本插件基于 Apache License 开源，详见 LICENSE 文件。

联系方式

OHOS Cordova https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-qqsdk

Android/iOS：https://npmjs.com/cordova-plugin-qqsdk/issues