集成币安SDK

Binance Open SDK#

Binance Open SDK(以下简称 SDK)提供了通过币安应用和 Web 页面两种授权的方式,方便用户安全、快捷的使用币安账户进行授权,SDK 会根据不同情况和用户的选择采用不同的方式。
集成 SDK 需要您首先确定应用程序所需的权限范围,联系我们注册您的应用程序,然后获取 client_id。

流程介绍#

用户在应用中点击使用币安账户登陆后,会调起币安应用进行授权操作,如果用户未安装支持授权的币安应用,会提示用户可以选择通过浏览器进行授权,或者下载币安应用后再进行授权。用户授权完成,会把授权结果返回给应用。

img

Android 集成 SDK#

1. 引入 SDK#

  • 确保您的项目中已包含jcenter仓库(project > build.gradle)。
repositories {
jcenter()
}
  • 在项目的build.gradle文件中添加如下依赖:(project > module > build.gradle)。
dependencies {
implementation 'com.binance.android:binance-opensdk:0.3.1'
}
  • 在 AndroidManifest.xml 文件中配置 clientID
<application>
<meta-data
android:name="BINANCE_CLIENT_ID"
android:resource="clientID"/>
</application>

2. 调用授权接口#

我们提供了两种授权模式

  1. 有后端服务的 App 请使用授权码模式。
  2. 没有后端服务的 App 请使用 PKCE 模式。

2.1. 授权码模式#

// context必须是Activity对象
val binanceAPI = BinanceAPIFactory.createAPI(context)
val oauthParams = OAuthParams(redirectUri, scope, state)
binanceAPI.authorize(oauthParams, object : BinanceListener {
override fun onSuccess(code: String, state: String) {
Log.d(LOG_TAG, "code $code")
}
override fun onCancel() {
Log.d(LOG_TAG, "onCancel")
}
override fun onError(errCode: Int) {
Log.d(LOG_TAG, "errCode $errCode")
}
})

接口参数说明

参数说明
redirectUri在向 Binance 注册时使用的 redirectUri,用于通过 web 授权登陆时返回接入方 app 使用。
scope本次进行授权所申请的权限,多个权限用","分割。
state为了防止 CSRF 攻击,请携带此参数,授权完成后,Binance 会将该字段原样返回给接入方。

2.2. PKCE 模式#

PKCE 模式提供了一套客户端验证机制,防止第三方恶意拦截授权流程,获取访问令牌,非法盗取数据。 详细内容参见:https://tools.ietf.org/html/rfc7636

// createAPI的第一个参数必须是Activity对象
val binanceAPI = BinanceAPIFactory.createAPI(context)
val oauthParams = OAuthParams(redirectUri, scope, state)
val codeVerifier = UUID.randomUUID().toString()
val codeChallenge = generateCodeChallenge(codeVerifier)
val challengeParams = ChallengeParams(codeChallenge, "S256")
binanceAPI.authorize(oauthParams, challengeParams, object : BinanceListener {
override fun onSuccess(code: String, state: String) {
Log.d(LOG_TAG, "code $code")
}
override fun onCancel() {
Log.d(LOG_TAG, "onCancel")
}
override fun onError(errCode: Int) {
Log.d(LOG_TAG, "errCode $errCode")
}
})

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的方式打开指定页面,并把授权结果返回。

  • BinanceListener

    • 授权成功会回调onSuccess方法,code为授权结果,state为调用authorize接口时传递的参数state

    • 用户取消授权会回调onCancel接口,表示授权过程被取消。

    • 授权失败会回调onError接口,errCode为错误码。

      errCode原因
      10000Binance App 未安装
      10001Binance App 版本不支持
      10002clientId 为空
      10003参数错误
      10004App 检验失败(app 信息与注册信息不一致)
  • DeepLink
    如果用户是通过 Web 登录授权,授权完成后,会通过DeepLink的方式打开指定页面(注册时redirectUri对应的页面),此时需要在该页面的onCreate方法和onNewIntent方法中处理授权结果,授权成功的DeepLink格式为{redirectUri}?code=xxxxx&state=xxxxx。 示例代码:

class LoginActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val code = intent?.data?.getQueryParameter("code")
val state = intent?.data?.getQueryParameter("state")
Log.d(LOG_TAG, "code $code")
}
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
val code = intent?.data?.getQueryParameter("code")
val state = intent?.data?.getQueryParameter("state")
Log.d(LOG_TAG, "code $code")
}
......
}

iOS 集成 SDK#

版本#

  • Binance iOS App: 2.17.0+
  • iOS 系统: iOS10+

集成#

Cocoapods#
手动#
  1. 下载BinanceOpenSDK.framework动态库文件
  2. BinanceOpenSDK.framework添加到你的工程文件内
  3. 选择Build Phases选项,将BinanceOpenSDK.framework添加到Embed Frameworks

使用#

Bundle ID & App ID#

首先,你需要Binance为您提供的基于你工程的BundleID所对应的AppID

Info.plist#

配置Info.plist必要的参数:

  1. LSApplicationQueriesSchemes内添加两个参数: account.binance.oauth.supporcom.binance.app.binance
  2. 新增一个String类型参数,key 为BinanceAppID,value 为你自己的AppID
接口列表#
验证(authorize)#

我们提供了两种授权模式

  1. 有后端服务的 App 请使用授权码模式。
  2. 没有后端服务的 App 请使用 PKCE 模式。

两种授权模式都使用通过authorize(with:, baseAt:, onSuccess:, onFailure:)这个接口来发起一次oauth的验证请求。

public func authorize(with parameters: OAuthParameters, baseAt container: UIView, onSuccess:((String, String) -> Void)?, onFailure: ((OAuthError) -> Void)?)
OAuthParameters#

OAuthParameters是用于封装OAuth请求必需的参数的结构体。

codeChallenge是对 codeVerifier 使用 SHA-256 加密后的 Base64 哈希值,SDK 提供了工具方法帮你计算BinanceOpenUtils.generateCodeChallendge(codeVerifier)

如果你使用授权码模式,则无需传入codeChallenge,如果采用PKCE模式,则可传入.s256(code: BinanceOpenUtils.generateCodeChallendge(codeVerifier)!)

public struct OAuthParameters {
public var scope: String
public var state: String
public var redirectURI: String
public var codeChallenge: CodeChallenge?
}
参数说明
redirectUri在向 Binance 注册时使用的 redirectUri,用于通过 web 授权登陆时返回接入方 app 使用。
scope本次进行授权所申请的权限。
state为了防止 CSRF 攻击,请携带此参数,授权完成后,Binance 会将该字段原样返回给接入方。
codeChallenge对 codeVerifier 使用 SHA-256 加密后的 Base64 哈希值

Handle Open URL#

需要在AppDelegate中处理openURL:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return BinanceOpenSDK.shared.handle(openURL: url)
}
状态自检#

BinanceOpenSDK提供了selfTest()函数用于自我状态的检测。此函数用于检测 SDK 所必须的参数和环境,当检测失败时,会将具体的问题返回给你。如果返回值为nil,那么则表明检测后 SDK 当前状态是没有问题的。

具体的返回的警告是以下的枚举:

public enum Warning {
case invalidAppID
case invalidBundleID
case noBinanceApp
case oauth(OAuthWarning)
}
多语言#

BinanceOpenSDK目前支持两种语言模式:

  1. 自动模式(默认): 自动模式 SDK 将会跟随系统语言来展示文案
  2. 手动模式: 你可以为 SDK 指定一种语言
// 自动模式
BinanceOpenSDK.shared.languageMode = .automatic
// 手动模式
BinanceOpenSDK.shared.languageMode = .manual(language: .russia)

目前支持的语言有以下几种:

LanguageDesc
english英文
chinese简体中文
traditionalChinese繁体中文
korean韩文
turkish土耳其语
vietnamese越南语
spanish西班牙语
russia俄语
portuguese葡语
japanese日语
polish波兰语
ukrainian乌克兰语
french法语
错误类型#

整体看来BinanceOpenSDK的错误类型分为两种,一种是 SDK 内部的错误,一种是调用 Binance App 之后,回调的错误。主要是以下的枚举:

public enum OAuthError: Error {
case invalidBundleID
case invalidAppID
case invalidParameters
case openAppFailed
case openSafariFailed
case fromBinanceApp(type: String, desc: String)
}

fromBinanceApp为 Binance App 返回的错误,常见的 3 种类型如下:

  • cancelled: 用户手动取消验证
  • readClientInfoFailed: 获取第三方 App 信息失败
  • invaildClientInfo: 第三方 App 校验失败(信息与注册是不匹配)