更新记录

1.0.0（2025-10-24）

支持双端钉钉授权登录

平台兼容性

uni-app(4.36)

uni-app x(4.36)

tt-dingtalk-oauth

🚀 钉钉授权登录SDK插件，为 uni-app x & uni-app 提供完整的钉钉集成解决方案

📖 目录

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

SDK版本信息

功能支持矩阵

📚 推荐阅读: iOS 应用授权登录接入流程 Android应用授权登录接入流程

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法 ⚠️ 测试前需确保应用已通过钉钉开放平台审核 ⚠️ 需要先调用 register 接口注册 appId，然后才能进行登录操作

环境配置

前置条件

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

iOS平台配置

1. 配置 URL Scheme

编辑插件内的 uni_modules/tt-dingtalk-oauth/utssdk/app-ios/Info.plist，将以下配置项补充为您的实际值：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>dingtalk</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>此处填写您应用的ClientID</string>
        </array>
      </dict>
    </array>
    <key>LSApplicationQueriesSchemes</key>
    <array>
      <string>dingtalk</string>
      <string>dingtalk-openauth</string>
      <string>dingtalk-openauth2</string>
    </array>
  </dict>
</plist>

Android平台配置

Android平台会自动完成相关配置，确保在钉钉开放平台正确配置应用包名和签名即可。

快速开始

1. 导入插件

uni-app x 版本

import * as dingTalkSDK from "@/uni_modules/tt-dingtalk-oauth";

export default {
    data() {
        return {
            dingTalk: null as dingTalkSDK.TTDingTalkOauth | null,
        }
    },
    onLoad() {
        // 初始化钉钉SDK实例
        this.dingTalk = dingTalkSDK.getTTDingTalkOauth()
        // 注册钉钉SDK
        this.initDingTalkSDK()
    },
    methods: {
        // 初始化钉钉SDK
        initDingTalkSDK() {
            // SDK初始化代码见下方
        }
    }
}

uni-app 版本

import * as dingTalkSDK from "@/uni_modules/tt-dingtalk-oauth";

export default {
    data() {
        return {
            dingTalk: dingTalkSDK.TTDingTalkOauth,
        }
    },
    onLoad() {
        // 初始化钉钉SDK实例
        this.dingTalk = dingTalkSDK.getTTDingTalkOauth()
        // 注册钉钉SDK
        this.initDingTalkSDK()
    },
    methods: {
        // 初始化钉钉SDK
        initDingTalkSDK() {
            // SDK初始化代码见下方
        }
    }
}

2. 初始化 SDK

uni-app x 版本

initDingTalkSDK() {
    if (this.dingTalk == null) {
        console.error('钉钉SDK初始化失败')
        return
    }

    this.dingTalk.register({
        appId: "您的钉钉AppID",           // 必填：钉钉开放平台申请的AppID
        success: (e) => {
            console.log("✅ 钉钉SDK初始化成功");
            // 可以在这里进行后续操作
        },
        fail: (err) => {
            console.error("❌ 钉钉SDK初始化失败:", err);
            uni.showToast({
                title: '钉钉SDK初始化失败',
                icon: 'error'
            })
        }
    } as dingTalkSDK.TTDingTalkOauthRegisterOptions);
}

uni-app 版本

initDingTalkSDK() {
    if (this.dingTalk == null) {
        console.error('钉钉SDK初始化失败')
        return
    }

    this.dingTalk.register({
        appId: "您的钉钉AppID",           // 必填：钉钉开放平台申请的AppID
        success: (e) => {
            console.log("✅ 钉钉SDK初始化成功");
            // 可以在这里进行后续操作
        },
        fail: (err) => {
            console.error("❌ 钉钉SDK初始化失败:", err);
            uni.showToast({
                title: '钉钉SDK初始化失败',
                icon: 'error'
            })
        }
    });
}

功能介绍

钉钉授权登录

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

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

参数说明

TTDingTalkOauthOptions

返回值 TTDingTalkOauthSuccess

示例代码

// 钉钉授权登录
handleDingTalkLogin() {
    this.dingTalk?.login({
        redirectUrl: "https://your-domain.com/callback", // 回调域名
        scope: "openid corpid", // 授权范围：openid 或 openid corpid
        state: Date.now().toString(), // 使用时间戳作为唯一标识
        success: (result) => {
            console.log("✅ 获取授权码成功:", result.code);
            // 将code发送到后端服务器
            this.sendCodeToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ 钉钉授权失败:", error);
            uni.showToast({
                title: '授权失败',
                icon: 'error'
            })
        }
    } as dingTalkSDK.TTDingTalkOauthOptions)
}

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

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

📖 详细流程请参考: 获取用户个人access_token 获取用户个人信息

后端需要完成的步骤：

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

错误处理

错误码说明

| 其他错误 |||| | 999 | 其他错误 | 所有功能 | 查看钉钉原始错误码和详细信息 | | 1000 | 暂无支持 | 所有功能 | 当前平台不支持此功能 |

常见问题

1. 找不到插件方法？

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

2. iOS平台登录无响应？

解决方案:

• 检查 uni_modules/tt-dingtalk-oauth/utssdk/app-ios/Info.plist 中的 URL Scheme 配置
• 确认钉钉开放平台的 iOS 应用配置
• 验证回调域名配置

3. Android平台功能异常？

解决方案:

• 确认应用签名与钉钉开放平台配置一致
• 检查包名是否正确
• 确保钉钉客户端版本支持相关功能

4. 授权登录失败？

解决方案:

• 确保已先调用 register 接口注册 appId
• 检查 redirectUrl 是否与钉钉开放平台配置一致
• 验证 scope 参数是否正确

5. 回调域名配置问题？

解决方案:

• 在钉钉开放平台正确配置回调域名
• 确保回调域名可以正常访问
• 回调域名需要与代码中的 redirectUrl 完全一致

6. 获取不到授权码？

解决方案:

• 确认用户是否已授权
• 验证 appId 是否正确
• 检查网络连接是否正常

📞 技术支持

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

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

祝您开发愉快！ 🎉