更新记录

1.0.1（2026-03-31）

支持 Android、iOS平台授权登录

1.0.0（2025-11-15）

授权登录 支持 鸿蒙平台

平台兼容性

uni-app(4.76)

uni-app x(4.76)

tt-kwai-opensdk

🚀 开放平台SDK插件，为 uni-app x & uni-app 提供授权登录功能

📱 支持平台：uni-app x (TypeScript) 和 uni-app (JavaScript)

📖 目录

• SDK版本信息
• 环境配置
• 快速开始
• 功能介绍
  • ***授权登录
• 错误处理
• 常见问题

SDK版本信息

📚 推荐阅读: ***开放平台集成文档

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法 ⚠️ 测试前需确保应用已在***开放平台完成配置 ⚠️ iOS 平台 register 时 universalLink 为必填项，不能为空 ⚠️ Android 平台需要在 nativeResources/android/manifestPlaceholders.json 中配置 KWAI_APP_ID ⚠️ HarmonyOS 平台需要正确配置 module.json5 文件

环境配置

前置条件

1. 在***开放平台申请移动应用
2. 获取 AppID
3. 配置应用包名和签名

iOS平台配置

1. 配置 URL Scheme

在 uni_modules/tt-kwai-opensdk/utssdk/app-ios/Info.plist 中，将 CFBundleURLSchemes 的值替换为你的*** AppID：

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>你的***AppID</string>
    </array>
  </dict>
</array>

2. 确认查询 Scheme

Info.plist 中需保留 LSApplicationQueriesSchemes，用于检测并拉起***客户端（插件默认已提供）：

• kwai
• kwaiAuth2
• kwaiopenapi
• KwaiBundleToken
• kwai.clip.multi
• KwaiSDKMediaV2
• ksnebula

3. 初始化时传入 universalLink（必填）

iOS 平台调用 register 时，universalLink 不能为空，否则会返回错误码 102。

Android平台配置

1. 配置 AppID

💡 appid 配置说明：Android 平台的 appid 需要在项目的 nativeResources/android/manifestPlaceholders.json 文件中配置，例如：

{
  "KWAI_APP_ID": "你的***AppID"
}

2. 初始化说明

Android 平台 register 时会校验 appid。universalLink 参数在 Android 平台可传空字符串 ""。

HarmonyOS平台配置

⚠️ 重要授权说明:

• uni-app 项目: 由于官方目前不支持试用以及普通授权，建议通过示例中的 uni-app x 项目测通后购买源码授权使用
• uni-app x 项目: 可直接使用

1. 配置 module.json5

⚠️ 重要提示: 由于 harmony-configs/entry/src/main/module.json5 会完全替换默认配置，需要提供完整的配置文件。

在项目的 harmony-configs/entry/src/main/module.json5 文件中使用以下完整配置：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "querySchemes": [
      "kwai",
      "ksnebula"  // ***开放平台scheme
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

💡 配置说明:

• 必须使用完整配置: module.json5 会覆盖默认配置，不能只添加部分字段
• 关键添加项: querySchemes 数组包含 kwai、ksnebula
• 保留默认配置: 其他配置项保持与默认模板一致

2. 使用说明

配置文件覆盖机制:

• HarmonyOS 的 harmony-configs/entry/src/main/module.json5 采用完全替换机制
• 一旦创建此文件，会完全覆盖默认的 module.json5 配置
• 因此必须提供完整的配置内容，不能只添加部分字段

配置要点:

• ✅ 使用上述提供的完整模板
• ✅ 确保 querySchemes 包含***相关 scheme（kwai、ksnebula ）
• ✅ 保留所有默认的 abilities、permissions 等配置
• ❌ 不要只添加部分字段（会导致其他配置丢失）

快速开始

1. 导入插件

uni-app x 版本

import * as ksdk from "@/uni_modules/tt-kwai-opensdk";

export default {
    data() {
        return {
            kwai: null as ksdk.TTKwaiOpenSDK | null,
        }
    },
    onLoad() {
        // 初始化***SDK实例
        this.kwai = ksdk.getTTKwaiOpenSDK()
        // 注册***SDK
        this.initKwaiSDK()
    },
    methods: {
        // 初始化***SDK
        initKwaiSDK() {
            // SDK初始化代码见下方
        }
    }
}

uni-app 版本

// 在页面中引入插件
import * as ksdk from "@/uni_modules/tt-kwai-opensdk";

export default {
    data() {
        return {
            kwai: null
        }
    },
    onLoad() {
        // 初始化***SDK实例
        this.kwai = ksdk.getTTKwaiOpenSDK()
        // 注册***SDK
        this.initKwaiSDK()
    },
    methods: {
        // 初始化***SDK
        initKwaiSDK() {
            // SDK初始化代码见下方
        }
    }
}

2. 初始化 SDK

uni-app x 版本

initKwaiSDK() {
    if (this.kwai == null) {
        console.error('***SDK初始化失败')
        return
    }

    this.kwai?.register({
        appid: "您的***AppID",           // 必填：***开放平台申请的AppID
        universalLink: "https://your.domain.com/link/", // iOS必填；Android/Harmony可传空字符串
        success: (e) => {
            console.log("✅ ***SDK初始化成功");
            // SDK初始化完成，可以进行后续操作
        },
        fail: (err) => {
            console.error("❌ ***SDK初始化失败:", err);
            uni.showToast({
                title: '***SDK初始化失败',
                icon: 'error'
            })
        }
    } as ksdk.TTKwaiRegisterOptions);
}

uni-app 版本

initKwaiSDK() {
    if (this.kwai == null) {
        console.error('***SDK初始化失败')
        return
    }

    this.kwai.register({
        appid: "您的***AppID",           // 必填：***开放平台申请的AppID
        universalLink: "https://your.domain.com/link/", // iOS必填；Android/Harmony可传空字符串
        success: (e) => {
            console.log("✅ ***SDK初始化成功");
            // SDK初始化完成，可以进行后续操作
        },
        fail: (err) => {
            console.error("❌ ***SDK初始化失败:", err);
            uni.showToast({
                title: '***SDK初始化失败',
                icon: 'error'
            })
        }
    });
}

功能介绍

***授权登录

💡 ***登录是一个两步过程：先获取code，再通过后端接口换取用户信息

第一步：获取授权码 (code)

参数说明

TTKwaiLoginOptions

返回值 TTKwaiLoginSuccess

示例代码

uni-app x 版本

// ***授权登录
handleKwaiLogin() {
    this.kwai?.login({
        success: (result) => {
            console.log("✅ 获取授权码成功:", result.code);
            // 将code发送到后端服务器
            this.sendCodeToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ ***授权失败:", error);
            uni.showToast({
                title: '授权失败: ' + (error.errMsg || '未知错误'),
                icon: 'error'
            })
        },
    } as ksdk.TTKwaiLoginOptions)
}

// 发送code到后端服务器
sendCodeToServer(code: string) {
    uni.request({
        url: 'https://your-server.com/api/kwai/login',
        method: 'POST',
        data: { code },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
        }
    })
}

uni-app 版本

// ***授权登录
handleKwaiLogin() {
    this.kwai.login({
        success: (result) => {
            console.log("✅ 获取授权码成功:", result.code);
            // 将code发送到后端服务器
            this.sendCodeToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ ***授权失败:", error);
            uni.showToast({
                title: '授权失败: ' + (error.errMsg || '未知错误'),
                icon: 'error'
            })
        },
    })
}

// 发送code到后端服务器
sendCodeToServer(code) {
    uni.request({
        url: 'https://your-server.com/api/kwai/login',
        method: 'POST',
        data: { code },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
        }
    })
}

第二步：后端换取用户信息

📖 详细流程请参考: 获取accessToken

后端需要完成的步骤：

1. 使用code换取access_token
2. 使用access_token获取用户信息
3. 返回用户信息给前端

错误处理

错误码说明

常见问题

1. 找不到插件方法？

解决方案: 确保使用自定义基座运行，标准基座不包含原生插件。

2. HarmonyOS平台授权无响应？

解决方案:

• 检查 harmony-configs/entry/src/main/module.json5 中的 querySchemes 配置
• 确认 querySchemes 数组包含 kwai、ksnebula
• 验证***开放平台的 HarmonyOS 应用配置
• 确保 EntryAbility 已正确配置

3. SDK初始化失败？

解决方案:

• 确认 AppID 是否正确
• 检查网络连接是否正常
• 验证***开放平台应用状态是否正常

4. 授权失败？

解决方案:

• 确保用户已安装***客户端
• 检查***客户端版本是否支持授权功能
• 查看错误详情（通过 error.cause 获取原始错误信息）
• 确认应用已在***开放平台完成审核

5. iOS/Android平台如何使用？

解决方案:

• iOS / Android / HarmonyOS 均已支持
• iOS 请重点检查 Info.plist 的 CFBundleURLSchemes 和 universalLink 配置
• Android 请重点检查 nativeResources/android/manifestPlaceholders.json 中的 KWAI_APP_ID 配置

📞 技术支持

如果在使用过程中遇到问题，请：

1. 查阅上方常见问题
2. 参考***开放平台开发文档
3. 检查配置是否正确
4. 确认***客户端版本

祝您开发愉快！ 🎉