Your browser version is too low, some content may not display properly, please download the latest version!

开发指南

准备工作

Potato登录是基于OAuth2.0协议标准构建的Potato OAuth2.0授权登录系统。

在进行Potato OAuth2.0授权登录接入之前，在Potato开发者中心注册开发者账号，并拥有一个已审核通过的网站应用或移动应用，获取到client_id和client_secret，可开始接入流程。

1、目前移动应用上Potato登录只提供原生的登录方式，需要用户安装Potato客户端才能配合使用。
2、对于Android应用，建议总是显示Potato登录按钮，当用户手机没有安装Potato客户端时，请引导用户下载安装Potato客户端。
3、对于iOS应用，建议总是显示Potato登录按钮，当用户手机没有安装Potato客户端时，请引导用户下载安装Potato客户端。
授权流程说明

Potato OAuth2.0授权登录让Potato用户使用Potato身份安全登录第三方网站或应用，在Potato用户授权登录已接入Potato OAuth2.0的第三方应用后，第三方可以获取到用户的接口调用凭证（access_token），通过access_token可以进行Potato开放平台授权关系接口调用，从而可实现获取Potato用户基本开放信息和帮助用户实现基础开放功能等。

Potato OAuth2.0授权登录目前是authorization_token模式。该模式整体流程为：

1. 第三方发起Potato授权登录请求，Potato用户允许授权第三方应用后，Potato会拉起应用或重定向到第三方网站，并且带上授权access_token;
2. 通过access_token和client_secret，获取用户基本数据资源或帮助用户实现基本操作;
资源下载

Android 接入SDK下载

iOS接入接入SDK下载

网站应用

授权登录

第三方使用网站应用引导用户请求以下URL:

https://oauth.pname.im/oauth2/authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE

说明:使用HTTP GET请求

参数名 必选 类型 说明
response_type 是 string 授权类型，此处的值固定为"token"
client_id 是 string 客户端的ID
redirect_uri 是 string 重定向URI(urlEncode处理)
state 否 string 用于保持请求和回调的状态，授权请求后原样带回给第三方
返回说明

用户允许授权后，将会重定向到redirect_uri的网址上，并且带上token和state参数

redirect_uri?access_token=ACCESS_TOKEN&expired=EXPIRED&state=STATE

若用户禁止授权，则重定向后不会带上token参数，仅会带上state参数

redirect_uri?state=STATE
用access_token获取用户信息

获取用户信息请参考

移动应用

Android SDK接入

1、将下载的 jar 包放于相应的 libs 目录下（或者直接使用导入外部包的方式将 jar 包添加到工程中）

通过拷贝到 libs 目录的方式一定要手动导入该jar包

2、添加jar使用权限（如果应用已添加跳过该步骤），在 AndroidManifest.xml 文件根节点下添加：

<uses-permission android:name="android.permission.INTERNET"/>

3、配置 AndroidManifest.xml 文件，在 application 节点下配置

<activity
    android:name="im.potato.potato_sdk.LoginActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"/>

4、配置 AndroidManifest.xml 文件，在 application 节点下配置

该步骤非必须，请参考步骤5使用

<meta-data
android:name = "PotatoClientID"
android:value = "YourClientId"/>

5、在应用客户端调用：

一旦在AndroidManifest.xml 配置ClientID，不管使用那种调用方式都以AndroidManifest.xml配置为准

1.Login.launchClientLogin(MainActivity) 当使用该方法发起授权时，必需配置步骤4
1.Login.launchClientLogin(MainActivity.this,"Your PotatoClientID");使用该方法发起授权需跳过步骤4,应用的ClientID需当作参数传入

6、在Activity中重写 onActivityResult

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);

        if (requestCode == IdentifierUtils.sClientLoginRequestCode) {
            if (resultCode == IdentifierUtils.sNetError) { // error network
                String error = data.getStringExtra("error");
                Log.d("error", error);

            } else if (resultCode == RESULT_OK) { //token
                if (data != null) {
                    Bundle bundle = data.getExtras();
                    AuthToken authToken = (AuthToken) bundle.getSerializable("getToken");

                    Log.d("TAG", "token:" + authToken.toString());
                    if (authToken.success) {
                        Log.d("TAG","success");
                    } else {
                        Log.d("TAG","error:" + authToken.message);
                    }

                }
            } else if (resultCode == IdentifierUtils.sNoPotatoClientID) { // configure client_id
                Log.d("TAG", data.getStringExtra("error"));

            } else if (resultCode == IdentifierUtils.sNoInstallPotato) { // install potato
                Log.d("TAG", data.getStringExtra("error"));
            }else if(resultCode == IdentifierUtils.sOAuthFail) {
                Log.d("TAG", data.getStringExtra("error"));
            }
        }
    }
iOS SDK接入

本文档对应SDK版本为1.5，只支持应用授权，暂不支持网页授权

1、下载SDK,将PotatoAuthorizationSDK文件夹中的所有文件全部添加到工程中, 如下图所示:



2、Other linker flags选项添加-ObjC，如下所示:

3、在自己的项目中配置 urlscheme, identifier 为 Potato, scheme 为 Potato+ClientId, 如下所示:

4、将 Potato Scheme 加入白名单, 如下所示:

5、将 PotatoGuards.h 导入到项目中, 如下所示:

6、在 AppDelegate 重写下面两个方法, 如下所示:

7、使用类方法直接调用，成功将获取到token和有效时间，失败会返回错误码和错误原因, 如下所示:

开放接口

获取用户信息

  https://oauth.pname.im/oauth2/api/userinfo?access_token=ACCESS_TOKEN&client_secret=CLIENT_SECRET

POST

application/x-www-form-urlencoded

参数名 必选 类型 说明
access_token 是 string 授权token
client_secret 是 string 客户端secret

返回说明

正确的返回示例：JSON

                        {
                            "open_id":"fHIE0JbejMjql1SaDOp-E-PZ-inFbC1uiAnq7YDJV0k=",//user's unique id
                            "union_id":"Triy0Fj1gnA480MVlqKakmtduDQdMUbdijXn0QJHNrM=",//developer unique id
                            "username":"jack",//user's username
                            "phone":"19912345678",//user's phone number
                            "country_code":"86",//the user country code
                            "photo_base64":"9j/2wCEAAgGBgcGBQgHBw.....",//user's avatars base64 encoded data
                        }

错误的返回示例：JSON

{
                        "success" : false, // error
                        "code" : 4116, //response code
                        "message" : "missing access_token", //response message
                    }

- 更多返回错误代码   返回码说明

刷新access_token

  https://oauth.pname.im/oauth2/api/refreshToken?access_token={{access_token}}&client_secret={{client_secret}}

POST

application/x-www-form-urlencoded

参数名 必选 类型 说明
access_token 是 string 授权token
client_secret 是 string 客户端secret

正确的返回示例：JSON

{
                           "success":true,
                           "code":0,  //error code
                           "message":"ok",
                           "data":{  //token detailed information
                                 "access_token":"CcdUEPpv0_t94WGeIakrm-rm_NwakynkftjuKFMkeoTS4bpsF3UKunITF9MsU6wqmGGF0ifNDSqaTIzNDv-lipJt9TQP7FDo8av_lV5ROEy9", //token
                                 "expires_in":1592987431,// expiration time (time stamp, unit: second)
                                 "token_type":"bearer",//token type
                                 "scope":"userinfo",//extend of competence
                                 "nonce":false // false means token can be used multiple times,  true means token can be used only once
                                  }
                        }

参数名 类型 说明
success bool whether the operation is successful or not
code int status code
message string prompt information
data obj token detailed information

返回码说明(http状态码总是返回:200)

返回 json 结果,成功时 code 为1,失败时 code 如下:

错误码 描述 说明
4116 missing access_token 缺失参数access_token
4117 missing client_secret 缺失参数client_secret
4213 invalid access_token 不合法的access_token
4214 invalid client_secret 不合法的client_secret
5401 the token has expired token过期
5900 $e 其他未知错误