抖音开放平台Logo
开发者文档
控制台

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 常见问题