Android授权登录开发手册

功能介绍

本文档旨在说明:授权登录通过使用抖音短视频授权,获取使用抖音短视频登录第三方应用的权限。通过用户同意授权允许您的 App 访问用户相关个人信息,包括用户昵称、头像等信息。

适用场景

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

注意:该授权sdk不适用抖音极速版,请下载抖音主版完成授权功能

总体授权说明

移动应用使用抖音短视频授权是基于 OAuth2.0 协议标准。抖音短视频授权采用 OAuth2.0 的授权码 (authorization code) 方式,首先需要获取一个临时票据,再用该临时票据获取令牌 (access_token) ,然后通过该令牌获取用户信息。详见总体授权说明

注意:授权功能已经对android 11 做了适配,如果您在android 11上面遇到授权功能异常,请升级sdk版本为0.1.4.0及其以上。请参考接入指南配置软件包可见性保证SDK能正确获取抖音的应用签名。

准备工作

在使用Android授权接入之前,您需要完成接入指南中的申请、配置过程。配置过程详见安卓接入指南

我们提供提供授权的SDKDemo供参考,涉及clientkey不能直接运行完整流程,参见下面的说明修改。点击下载:授权SDKDemo

操作步骤

步骤一:初始化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"; 
        return douyinOpenApi.authorize(request);                    // 优先使用抖音app进行授权,如果抖音app因版本或者其他原因无法授权,则使用web页授权
参数描述是否必传
scope授权域是指您的应用使用抖音授权之后,可以获得抖音用户的哪些信息,目前开放了user_info授权域,表示可以获得请求用户头像、昵称等相关信息的权限, 如果有多种必选权限,权限之间请使用逗号隔开, "xxx,xxx"
state用于保持请求和回调的状态,授权请求后原样带回给第三方,可传任意String
callerLocalEntry第三方指定自定义的回调类Activity, 自定义的时候注意实现IApiEventHandler这个方法
optionalScope0用户可选授权域,默认不勾选
optionalScope1用户可选授权域,默认勾选

展示效果:

执行代码之后,可吊起抖音的授权登录页(如果未安装抖音,此时会吊起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 结果返回说明

返回值及相关说明

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

步骤六.获取access_token

(该接口及后续接口请求建议放在服务端调用原因见注意)

成功获取到auth code之后,您需要再调用接口来获取access_token,详情请见:获取授权令牌接入说明

注意

  1. client_secret是应用密钥,泄漏后可能会发生用户隐私数据泄漏的风险,存储在客户端并不安全,容易被窃取。

  2. access_token为用户授权第三方接口调用的凭证,存储在客户端,可能会被窃取,风险同上。

  3. refresh_token仅用于刷新access_token,泄漏后相当于access_token泄漏,风险同上。 建议将client_secretaccess_token放到服务端来进行存储和使用。

SDK Demo下载

提供授权的SDKDemo供参考,涉及clientkey不能直接运行完整流程,参见上面的说明修改, 点击下载授权SDKDemo

其他

从SDK0.0.1.X升级到新版SDK0.1.1.0版本以上的主要改动

1.类库引入方式

dependencies {
    implementation 'com.bytedance.ies.ugc.aweme:opensdk-china-external:0.1.1.0'
    implementation 'com.bytedance.ies.ugc.aweme:opensdk-common:0.1.1.0'
}

新版sdk需要引入两个aar,这是与旧版sdk最大的不同

2.主要类名修改

原名现在名称
TiktokOpenApiDouYinOpenApi
TikTokConstantsCommonConstants
TikTokOpenConfigDouYinOpenConfig
TikTokOpenApiFactoryDouYinOpenApiFactory
TikTokApiEventHandlerIApiEventHandler

3.授权包名变动的类

类名
DouYinOpenApiFactory
DouYinOpenApi
DouYinOpenConfig

这几个类引入的时候,只需修改为正确的包名即可。

默认回调类的更改为.douyinapi.DouYinEntryActivity

默认回调Activity .tiktokapi.TikTokEntryActivity 更改为 .douyinapi.DouYinEntryActivity,自定义回调Activity可忽略本条

将TikTokOpenApiFactory类更改为DouYinOpenApiFactory

  • DouYinOpenApiFactory.create()方法创建DouYinOpenApi,此方法不再提供targetApp的传参,使用该方法仅仅只能吊起抖音授权和分享,若要使用TikTok的分享,请仔细阅读tiktok for developers内容。

错误码

可以统一在CommonConstants里面查找, 原TikTokConstants

错误码描述
OK = 0成功
ERROR_UNKNOW = -1未知错误
ERROR_CANCEL = -2用户手动取消
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 = 10007Authorization code 失效
ERROR_TOKEN = 10008Access_Token 无效
ERROR_TICKET = 10009非法参数
ERRORREFRESHTOKEN = 10010refresh token 过期
ERRORAUTHORIZATIONNO_PERMISSION = 10011授权鉴权失败
10017授权鉴权失败,需要补全签名信息。点击查看详情 请将您的线上包(发布的应用市场的包)应用安装到手机上之后,再使用签名工具生成签名。

FAQ

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

全屏:安卓或者iOS App通过集成抖音授权sdk 吊起抖音授权登录页面

半屏:抖音端内h5页面使用抖音授权登录,需集成js sdk,吊起抖音授权登录页面

Q: 解除授权通知

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

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

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

更多FAQ,详见:安卓FAQ

诚邀您对本文档易读易用性进行评价
好用
不好用