集成币安SDK
#
Binance Open SDKBinance Open SDK(以下简称 SDK)提供了通过币安应用和 Web 页面两种授权的方式,方便用户安全、快捷的使用币安账户进行授权,SDK 会根据不同情况和用户的选择采用不同的方式。
集成 SDK 需要您首先确定应用程序所需的权限范围,我们目前只提供给紧密的生态系合作伙伴。请联系 oauth-apply@binance.com 确认合作关系后,技术团队才会协助注册您的应用程序,然后获取 client_id。
#
流程介绍用户在应用中点击使用币安账户登陆后,会调起币安应用进行授权操作,如果用户未安装支持授权的币安应用,会提示用户可以选择通过浏览器进行授权,或者下载币安应用后再进行授权。用户授权完成,会把授权结果返回给应用。
#
Android 集成 SDK#
1. 引入 SDK- 确保您的项目中已包含
jcenter
仓库(project > build.gradle
)。
- 在项目的
build.gradle
文件中添加如下依赖:(project > module > build.gradle
)。
- 在 AndroidManifest.xml 文件中配置 clientID
#
2. 调用授权接口我们提供了两种授权模式
- 有后端服务的 App 请使用授权码模式。
- 没有后端服务的 App 请使用 PKCE 模式。
#
2.1. 授权码模式接口参数说明
参数 | 说明 |
---|---|
redirectUri | 在向 Binance 注册时使用的 redirectUri,用于通过 web 授权登陆时返回接入方 app 使用。 |
scope | 本次进行授权所申请的权限,多个权限用","分割。 |
state | 为了防止 CSRF 攻击,请携带此参数,授权完成后,Binance 会将该字段原样返回给接入方。 |
#
2.2. PKCE 模式PKCE 模式提供了一套客户端验证机制,防止第三方恶意拦截授权流程,获取访问令牌,非法盗取数据。 详细内容参见:https://tools.ietf.org/html/rfc7636
generateCodeChallenge: SDK 提供了对 codeVerifier 加密的工具方法,方便开发者快速获取 codeChallenge。Java 代码可通过BinanceKit.generateCodeChallenge(codeVerifier)
调用。
获取
accessToken
以及用户信息的接口参见: 使用授权码获取 accessToken、调用币安 API
接口参数说明
参数 | 说明 |
---|---|
redirectUri | 在向 Binance 注册时使用的 redirectUri,用于通过 web 授权登陆时返回接入方 app 使用。 |
scope | 本次进行授权所申请的权限,多个权限用","分割。 |
state | 为了防止 CSRF 攻击,请携带此参数,授权完成后,Binance 会将该字段原样返回给接入方。 |
codeVerifier | 随机字符串,用于获取 accessToken 时校验。 |
code_challenge | 对 codeVerifier 使用 SHA-256 加密后的 Base64 哈希值。 |
#
3. 接收返回数据如果用户通过币安 App 进行登陆授权,则会在BinanceListener
中收到授权结果。如果用户是通过 Web 登录授权,会通过DeepLink
的方式打开指定页面,并把授权结果返回。为了能正常接收到授权结果,需要在调用授权接口的Activity类的onActivityResult
方法中添加如下代码
BinanceListener
授权成功会回调
onSuccess
方法,code
为授权结果,state
为调用authorize
接口时传递的参数state
。用户取消授权会回调
onCancel
接口,表示授权过程被取消。授权失败会回调
onError
接口,errCode
为错误码。errCode 原因 10000 Binance App 未安装 10001 Binance App 版本不支持 10002 clientId 为空 10003 参数错误 10004 App 检验失败(app 信息与注册信息不一致)
DeepLink
如果用户是通过 Web 登录授权,授权完成后,会通过DeepLink
的方式打开指定页面(注册时redirectUri
对应的页面),此时需要在该页面的onCreate
方法和onNewIntent
方法中处理授权结果,授权成功的DeepLink
格式为{redirectUri}?code=xxxxx&state=xxxxx
。 示例代码:
#
iOS 集成 SDK#
版本- Binance iOS App: 2.17.0+
- iOS 系统: iOS10+
#
集成#
Cocoapods#
手动- 下载
BinanceOpenSDK.framework
动态库文件 - 将
BinanceOpenSDK.framework
添加到你的工程文件内 - 选择
Build Phases
选项,将BinanceOpenSDK.framework
添加到Embed Frameworks
#
使用#
Bundle ID & App ID首先,你需要Binance
为您提供的基于你工程的BundleID
所对应的AppID
。
#
Info.plist配置Info.plist
必要的参数:
- 在
LSApplicationQueriesSchemes
内添加两个参数:account.binance.oauth.suppor
和com.binance.app.binance
- 新增一个
String
类型参数,key 为BinanceAppID
,value 为你自己的AppID
#
接口列表#
验证(authorize)我们提供了两种授权模式
- 有后端服务的 App 请使用授权码模式。
- 没有后端服务的 App 请使用 PKCE 模式。
两种授权模式都使用通过authorize(with:, baseAt:, onSuccess:, onFailure:)
这个接口来发起一次oauth
的验证请求。
#
OAuthParametersOAuthParameters
是用于封装OAuth
请求必需的参数的结构体。
codeChallenge
是对 codeVerifier 使用 SHA-256 加密后的 Base64 哈希值,SDK 提供了工具方法帮你计算BinanceOpenUtils.generateCodeChallendge(codeVerifier)
。
如果你使用授权码模式,则无需传入codeChallenge
,如果采用PKCE
模式,则可传入.s256(code: BinanceOpenUtils.generateCodeChallendge(codeVerifier)!)
参数 | 说明 |
---|---|
redirectUri | 在向 Binance 注册时使用的 redirectUri,用于通过 web 授权登陆时返回接入方 app 使用。 |
scope | 本次进行授权所申请的权限。 |
state | 为了防止 CSRF 攻击,请携带此参数,授权完成后,Binance 会将该字段原样返回给接入方。 |
codeChallenge | 对 codeVerifier 使用 SHA-256 加密后的 Base64 哈希值 |
#
Handle Open URL需要在AppDelegate
中处理openURL
:
#
状态自检BinanceOpenSDK
提供了selfTest()
函数用于自我状态的检测。此函数用于检测 SDK 所必须的参数和环境,当检测失败时,会将具体的问题返回给你。如果返回值为nil
,那么则表明检测后 SDK 当前状态是没有问题的。
具体的返回的警告是以下的枚举:
#
多语言BinanceOpenSDK
目前支持两种语言模式:
- 自动模式(默认): 自动模式 SDK 将会跟随系统语言来展示文案
- 手动模式: 你可以为 SDK 指定一种语言
目前支持的语言有以下几种:
Language | Desc |
---|---|
english | 英文 |
chinese | 简体中文 |
traditionalChinese | 繁体中文 |
korean | 韩文 |
turkish | 土耳其语 |
vietnamese | 越南语 |
spanish | 西班牙语 |
russia | 俄语 |
portuguese | 葡语 |
japanese | 日语 |
polish | 波兰语 |
ukrainian | 乌克兰语 |
french | 法语 |
#
错误类型整体看来BinanceOpenSDK
的错误类型分为两种,一种是 SDK 内部的错误,一种是调用 Binance App 之后,回调的错误。主要是以下的枚举:
fromBinanceApp
为 Binance App 返回的错误,常见的 3 种类型如下:
- cancelled: 用户手动取消验证
- readClientInfoFailed: 获取第三方 App 信息失败
- invaildClientInfo: 第三方 App 校验失败(信息与注册是不匹配)