抖音开放平台Logo
开发者文档
控制台
  • 移动应用
  • open SDK 概述
  • open SDK 下载
  • open SDK 接入
  • 抖音分享
  • 抖音投稿发布
  • 抖音名片
  • 抖音登录和授权
  • 登录与授权
  • 获取授权令牌
  • iOS
  • Android
  • Android 授权
  • 授权页面配置备注
  • 鸿蒙
  • 常见问题
  • 网站应用
  • 适用场景

    本能力适用于通过使用抖音短视频授权,获取使用抖音短视频登录第三方应用的权限。

    背景信息

    移动应用使用抖音短视频授权是基于 OAuth2.0 协议标准。抖音短视频授权采用 OAuth2.0 的授权码(authorization code)方式,首先需要获取一个临时票据,再用该临时票据获取令牌(access_token),然后通过该令牌获取用户信息。详情请参见总体授权说明
    注意:授权功能已经对 Android 11 做了适配,如果您在 Android 11 上面遇到授权功能异常,请升级 SDK 到 0.1.4.0 及以上版本。请参考接入指南,配置软件包可见性,保证 SDK 能正确获取抖音的应用签名。

    准备工作

      在使用 Android 授权登录之前,您需要完成接入指南中的申请、配置过程。具体操作,请参见 Android 接入
      我们提供授权 SDK Demo,涉及 ClientKey 不能直接运行完整流程,参见下面的说明修改。

    操作步骤

    第一步:初始化 DouYinOpenApiFactory

    在 Application 的 onCreate() 中,初始化 DouYinOpenApiFactory。
    String clientkey = "xxxxxx"; // 需要到开发者网站申请 DouYinOpenApiFactory.init(new DouYinOpenConfig(clientkey));

    第二步:在 Manifest 中注册信息

    <uses-permission android:name="android.permission.INTERNET" /> <activity android:name=".douyinapi.DouYinEntryActivity" android:launchMode="singleTask" android:taskAffinity="你的包名" android:exported="true"> </activity>

    第三步:设置参数

    开发者接入抖音 OpenSDK,设置授权域(Scope),调用下面方法后,将会拉起抖音授权界面。用户在选择开放给第三方的信息并确认之后,抖音服务器会返回给第三方应用授权临时票据(code)。
    DouYinOpenApi douyinOpenApi = DouYinOpenApiFactory.create(this); Authorization.Request request = new Authorization.Request(); request.scope = "user_info"; // 用户授权时必选权限 //request.state = "ww"; // 用于保持请求和回调的状态,授权请求后原样带回给第三方。 request.callerLocalEntry = "com.xxx.xxx...activity"; // 第三方指定自定义的回调类 Activity return douyinOpenApi.authorize(request); // 优先使用抖音app进行授权,如果抖音app因版本或者其他原因无法授权,则使用web页授权
    参数
    描述
    是否必传
    scope
    授权域是指您的应用使用抖音授权之后,可以获得抖音用户的哪些信息,目前开放了user_info 授权域,表示可以获得请求用户头像、昵称等相关信息的权限,如果有多种必选权限,权限之间请使用逗号隔开, "xxx,xxx"。
    state
    用于保持请求和回调的状态,授权请求后原样带回给第三方,可传任意 String。
    callerLocalEntry
    第三方指定自定义的回调类 Activity, 自定义的时候注意实现 IApiEventHandler 这个方法。
    optionalScope0
    用户可选授权域,默认不勾选。
    optionalScope1
    用户可选授权域,默认勾选。
    webAuthType
    没安装抖音情况下拉起H5授权的类型。
    目前取值有qrcode,当为qrcode时会展示二维码页面,优化大屏场景体验。
    展示效果:
    执行代码之后,可调起抖音的授权登录页(如果未安装抖音,此时会调起 Web 授权页)。
    展示效果:

    第四步:接受返回信息

    在应用包名下创建 douyinapi.DouYinEntryActivity(或者自定义的 callerLocalEntry),初始化 DouYinOpenApi,实现 IApiEventHandler 接口,在 onResp 方法中获取授权码(auth code)结果。
    public class DouYinEntryActivity extends Activity implements IApiEventHandler { DouYinOpenApi douYinOpenApi; @Override public void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); douYinOpenApi = DouYinOpenApiFactory.create(this); douYinOpenApi.handleIntent(getIntent(), this); } @Override public void onReq(BaseReq req) { } @Override public void onResp(BaseResp resp) { // 授权成功可以获得authCode if (resp.getType() == CommonConstants.ModeType.SEND_AUTH_RESPONSE) { Authorization.Response response = (Authorization.Response) resp; if (resp.isSuccess()) { Toast.makeText(this, "授权成功,获得权限:" + response.grantedPermissions, Toast.LENGTH_LONG).show(); } else { Toast.makeText(this, "授权失败" + response.grantedPermissions, Toast.LENGTH_LONG).show(); } finish(); } } @Override public void onErrorIntent(@Nullable Intent intent) { // 错误数据 Toast.makeText(this, "intent出错啦", Toast.LENGTH_LONG).show(); finish(); }
    注意,若应用的代码存在混淆情况,调起抖音授权之后,不能拿到授权结果的回调,请将接收回调的 activity(DouYinEntryActivity 或者自定义的回调 activity) 也加入免混淆清单。

    第五步: 获取 auth code 结果返回说明

    返回值及相关说明
    返回值
    说明
    errorCode
      OK = 0:授权成功
      ERRORUNKNOW = -1:未知错误
      ERRORCANCEL = -2:用户手动取消
    更多错误码请参考 CommonConstants.java。
    authCode
    临时票据 code,用来换取 access_token。
    state
    第三方程序发送时用于表示其请求的唯一性标志,由第三方程序调 openApi.authorize(request) 时传入,由抖音终端回传。
    grantedPermissions
    第三方通过用户授权取得的授权域。
    extra
    Bundle,通过"aweme_auth_host_app"获取当前授权方式。
      H5:web授权
      douyin:抖音授权

    第六步:获取 access_token

    成功获取到 auth code 之后,您需要再调用接口来获取 access_token,详情请参见获取授权令牌
    该接口及后续接口请求建议放在服务端调用,因为:
      client_secret是应用密钥,泄漏后可能会发生用户隐私数据泄漏的风险,存储在客户端并不安全,容易被窃取。
      access_token为用户授权第三方接口调用的凭证,存储在客户端,可能会被窃取,泄漏后可能会发生用户隐私数据泄漏的风险。
      refresh_token仅用于刷新access_token,泄漏后相当于access_token泄漏,泄漏后可能会发生用户隐私数据泄漏的风险。 建议将client_secretaccess_token放到服务端来进行存储和使用。

    错误码

    可以统一在 CommonConstants 里面查找。
    错误码
    描述
    OK = 0
    成功
    ERROR = 7
    访问频繁,命中风控
    ERROR_UNKNOW = -1
    未知错误
    ERROR_CANCEL = -2
    用户手动取消
    ERROR = -3
    网络异常
    ERRORNETWORKNO_CONNECTION = -12
    网络未连接
    ERRORNETWORKCONNECT_TIMEOUT = -13
    网络连接超时
    ERRORNETWORKTIMEOUT = -14
    网络超时
    ERRORNETWORKIO = -15
    网络io错误
    ERRORNETWORKUNKNOWNHOSTERROR = -16
    网络未知host错误
    ERRORNETWORKSSL = -21
    网络ssl错误
    ERROR_SYSTEM = 10001
    系统异常
    ERROR_PARAM = 10002
    参数错误
    ERROR_CONFIG = 10003
    非法的配置(partner_client)
    ERROR_SCOPE = 10004
    授权域配置错误
    ERRORNPARAMS = 10005
    缺少参数
    ERRORREDIRECTURL = 10006
    非法重定向url
    ERRORCODEEXPIRED = 10007
    Authorization code 失效
    ERROR_TOKEN = 10008
    Access_Token 无效
    ERROR_TICKET = 10009
    非法参数
    ERRORREFRESHTOKEN = 10010
    refresh token 过期
    ERRORAUTHORIZATIONNO_PERMISSION = 10011
    授权鉴权失败
    10011
    应用标识有误,配置的包名和实际的包名不符
    10012
    应用审核中,无法使用,联系运营同学
    10013
    client_key或者client_secret错误
    10014
    客户端携带的client_key不一致
    10015
    应用类型错误,检查是否混用APP/WEB 类型的client_key
    10017
    授权鉴权失败,需要补全签名信息。查看详情 请将您的线上包(发布的应用市场的包)应用安装到手机上之后,再使用签名工具生成签名。

    FAQ

    全屏与半屏的区别是什么?

      全屏:Android 或者 iOS App通过集成抖音授权 SDK 调起抖音授权登录页面。
      半屏:抖音端内 H5 页面使用抖音授权登录,需集成 JS SDK,调起抖音授权登录页面。

    解除授权通知

    用户可在抖音 APP-设置-帐号与安全-授权管理中解除对应用的授权,如需及时获知用户解除授权通知,请接入解除授权事件通知,具体调用方式,请参见 Webhooks-事件

    为什么同一个应用使用签名工具获取的签名信息不一样?

    签名工具的使用方法是:
      1.将你的应用的 release 包(发布到应用市场的包)下载到手机上。
      2.然后安装签名工具,输入你的应用的包名之后,即可获得签名。
    如果你安装了本地电脑打出来的 debug 包来获取签名,这个时候拿到的签名和线上 release 包的签名是不一样的,就会导致 10017 错误码。
    更多 FAQ,详见 Android 常见问题