集成币安SDK

Binance Open SDK

Binance Open SDK(以下简称 SDK)提供了通过币安应用和 Web 页面两种授权的方式，方便用户安全、快捷的使用币安账户进行授权，SDK 会根据不同情况和用户的选择采用不同的方式。
集成 SDK 需要您首先确定应用程序所需的权限范围，我们目前只提供给紧密的生态系合作伙伴。请联系 oauth-apply@binance.com 确认合作关系后，技术团队才会协助注册您的应用程序，然后获取 client_id。

流程介绍

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

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的方式打开指定页面，并把授权结果返回。为了能正常接收到授权结果，需要在调用授权接口的Activity类的onActivityResult方法中添加如下代码

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    binanceAPI?.handleResp(requestCode, resultCode, data)
}

• 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。 示例代码：

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.suppor和com.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)

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

Language	Desc
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 校验失败(信息与注册是不匹配)