更新记录

1.0.0（2026-08-27）

支持 Android、iOS Kakao 授权登录

平台兼容性

uni-app(5.15)

uni-app x(5.15)

tt-kakao-open

Kakao 授权登录 UTS API 插件，为 uni-app 和 uni-app x App 提供 KakaoTalk 登录与 Kakao Account 登录能力。

官方资料：Kakao Login | Android SDK | iOS SDK

目录

• 接入前必读
• 平台配置
• 快速开始
• API 参考
• 服务端处理与安全
• 错误处理
• 常见问题

接入前必读

• 调用 login()、logout()、unlink() 前，必须在当前 App 进程中成功调用一次 initialize()。
• nativeAppKey 是 Kakao Developers 中的 Native App Key，不是 REST API Key，也不是 Admin Key。
• 登录成功会直接返回 OAuth token，不会自动读取昵称、头像、邮箱等用户资料。请将 access token 安全地提交到业务服务端，再由服务端调用 Kakao 用户 API。
• logout() 仅清除当前设备的 Kakao SDK 会话；用户执行账号注销时，应调用不可逆的 unlink() 撤销该用户对应用的授权。

平台配置

1. Kakao Developers 后台

1. 登录 Kakao Developers，创建应用并在 Kakao Login 中启用登录。
2. 在应用的平台设置中登记 Android 包名和 iOS Bundle ID，必须与当前打包产物一致。
3. Android 应同时登记当前签名证书的 Key Hash。自定义基座、测试包和正式包通常使用不同证书，均需登记。
4. 根据业务需要在 Kakao Login 的 Consent Item 中启用所需用户信息。插件只负责授权，不会绕过 Kakao 的同意项配置。

2. iOS 配置

编辑 uni_modules/tt-kakao-open/utssdk/app-ios/Info.plist，将以下占位值替换为实际 Native App Key：

<string>kakao请替换为您的NativeAppKey</string>

例如 Native App Key 为 abc123：

<string>kakaoabc123</string>

同时确认 Kakao Developers 中登记的 iOS Bundle ID 与打包 Bundle ID 一致。

快速开始

导入插件

import * as kakaoOpen from '@/uni_modules/tt-kakao-open'

const kakao = kakaoOpen.getTTKakaoSDK()

初始化和登录

kakao.initialize({
  nativeAppKey: 'YOUR_NATIVE_APP_KEY',
  success: () => {
    kakao.login({
      // 默认 true：已安装 KakaoTalk 时优先唤起它；否则使用 Kakao Account。
      preferKakaoTalk: true,
      success: (token) => {
        console.log('Kakao login succeeded')
        console.log('access token:', token.accessToken)
        console.log('access token expires at:', token.accessTokenExpiresAt)

        // 建议立即使用 HTTPS 发送到业务服务端，由服务端校验并建立自己的会话。
        // sendTokenToServer(token.accessToken)
      },
      fail: (error) => {
        console.error('Kakao login failed:', error.errCode, error.errMsg)
      },
      complete: null
    } as kakaoOpen.TTKakaoLoginOptions)
  },
  fail: (error) => {
    console.error('Kakao SDK initialization failed:', error.errCode, error.errMsg)
  },
  complete: null
} as kakaoOpen.TTKakaoInitializeOptions)

判断 KakaoTalk 是否可用

if (kakao.isInstalled()) {
  console.log('KakaoTalk can be used for login')
} else {
  console.log('login() will open Kakao Account login')
}

isInstalled() 表示 KakaoTalk 是否已安装且当前设备可用作授权；它不是 SDK 是否初始化完成的判断。未初始化或 KakaoTalk 不可用时返回 false。

API 参考

getTTKakaoSDK()

返回 Kakao SDK 单例。首次使用时保存实例并调用 initialize()。

initialize(options)

每个 App 进程调用一次后再使用其它 API。

login(options)

login() 默认优先调用 KakaoTalk 登录；其它情况下调用 Kakao Account 登录。iOS 的 Kakao Account 登录必须完成前文的 URL Scheme 配置。

成功结果 TTKakaoLoginSuccess：

logout(options)

清除设备上的 Kakao SDK 登录状态。它不会解除用户和 Kakao 应用的关联，用户以后可再次授权登录。

kakao.logout({
  success: () => console.log('Kakao local session cleared'),
  fail: (error) => console.error(error.errCode, error.errMsg),
  complete: null
})

unlink(options)

调用 Kakao 的 unlink API，撤销该用户对当前应用的授权并清除本地会话。此操作不可逆，通常只应在用户明确注销账号时调用。

kakao.unlink({
  success: () => console.log('Kakao application connection revoked'),
  fail: (error) => console.error(error.errCode, error.errMsg),
  complete: null
})

logout() 和 unlink() 共用 TTKakaoActionOptions：

服务端处理与安全

将 accessToken 通过 HTTPS 提交给业务服务端，由服务端校验 Kakao 身份并签发自己的业务会话；不要将 Kakao token 写入日志、URL、埋点或崩溃报告。

不要把 REST API Key、Admin Key 或任何服务端密钥放入客户端源码。

错误处理

失败回调实现 IUniError，可读取 errCode 和 errMsg。

常见问题

iOS 完成网页登录后没有回到 App

检查插件 utssdk/app-ios/Info.plist 中的 Scheme 是否已替换为准确的 kakao{NativeAppKey}。修改后需重新制作自定义基座或云打包。

Android 报包名、签名或 Key Hash 不匹配

检查 Kakao Developers 中的 Android Package Name 与实际包名一致，并将当前签名证书对应的 Key Hash 加入后台。测试、自定义基座和线上包往往需要分别登记。

KakaoTalk 已安装却打开了 Kakao Account 登录

先确认 isInstalled() 返回值。若返回 false，通常是 KakaoTalk 不可用、系统限制或 Kakao SDK 无法将其作为登录渠道；插件会自动回退到 Kakao Account 登录。

为什么没有昵称、头像或邮箱

该插件的 login() 只返回 OAuth token。请在服务端使用 access token 调用 Kakao 用户 API；昵称、邮箱和其他同意项的可用性由 Kakao Developers 的 Consent Item 和用户授权状态决定。