Android SDK 接入

本文档介绍如何将 xhs-login SDK 集成到你的 Android 应用， 实现小红书账号 OAuth2 授权登录。1.1.0+ 提供了全新入口 XHSAuth， 默认使用 Secret 模式接入；完全公开分发、无法保护 app_secret 的场景可选用 PKCE 模式。

1. 接入前准备

在管理中心创建应用获取 app_id + app_secret（默认 Secret 模式）； 若你选择 PKCE 模式，仅需 app_id。

2. 添加依赖

2.1 Maven 依赖（生产推荐）

dependencies {
    implementation("com.xingin.android:xhs-login:1.1.0")
}

2.2 本地 AAR 依赖（测试用）

dependencies {
    implementation(files("libs/xhslogin-android-release-1.1.0.aar"))
}

3. AndroidManifest 配置

Android 11+ 需要声明包名查询权限：

<queries>
    <package android:name="com.xingin.xhs" />
</queries>

4. 初始化 SDK

在 Application.onCreate() 中初始化：

class YourApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        XHSAuth.configure(appId = "YOUR_APP_ID")

        if (!XHSAuth.isXHSAppAvailable(this)) {
            Log.w("XHS_SDK", "小红书未安装、版本过低或不支持授权")
        }
    }
}

5. Secret 模式（默认）

平台默认的授权码认证方式，SDK 直接使用 app_secret 完成 token 交换。适用于可安全存放 app_secret 的移动端 App。

XHSAuth.authorizeWithSecret(
    activity = this,
    appSecret = "YOUR_APP_SECRET",
    scopes = arrayOf(XHSScope.BASIC_INFO),
    callback = object : XHSAuthCallback {
        override fun onSuccess(code: String, state: String?) {
            // SDK 自动完成 token 交换
        }
        override fun onError(error: XHSAuthError) {
            handleAuthError(error)
        }
        override fun onCancel() {}
    }
)

6. PKCE 模式（可选）

无需 app_secret，授权码由你的后端换取 token，适用于完全公开分发、无法在本地保护 app_secret 的场景。

6.1 发起授权

XHSAuth.authorizeWithPKCE(
    activity = this,
    scopes = arrayOf(XHSScope.BASIC_INFO),
    callback = object : XHSAuthCallback {
        override fun onSuccess(code: String, state: String?) {
            // 将 code 发送到你的服务端，由服务端换取 token
            sendCodeToBackend(code)
        }
        override fun onError(error: XHSAuthError) {
            handleAuthError(error)
        }
        override fun onCancel() {
            Toast.makeText(this@MainActivity, "用户取消授权", Toast.LENGTH_SHORT).show()
        }
    }
)

6.2 处理回调

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

6.3 后端换取 Token

拿到 code 后由你的服务端调用小红书接口换取 token（不要在客户端执行）：

// 服务端伪代码
POST https://openaccount.xiaohongshu.com/api/sns/v1/oauth2/access_token
Content-Type: application/json

{
  "app_id": "xhs...",
  "code": "从客户端上传的 code",
  "code_verifier": "SDK 保存的 verifier（PKCE 模式必填）"
}

7. App-to-App Intent 参数规范

如需手动构造 Intent（不使用 SDK 封装）：

val intent = Intent().apply {
    component = ComponentName(
        "com.xingin.xhs",
        "com.xingin.login.oauth.activity.OAuthWrapperActivity"
    )
    putExtra("app_id", "YOUR_APP_ID")
    putExtra("scope", arrayOf("basic_info"))
    putExtra("state", "random_state_string")
    putExtra("code_challenge", "pkce_challenge")
    putExtra("code_challenge_method", "S256")
}
activity.startActivityForResult(intent, REQUEST_CODE_XHS_AUTH)

7.1 小红书返回结果

// 授权成功
resultIntent.putExtra("err_code", 0)
resultIntent.putExtra("code", "authorization_code")
resultIntent.putExtra("state", "original_state_string")

// 授权失败
resultIntent.putExtra("err_code", -2)
resultIntent.putExtra("err_str", "用户取消授权")

8. XHSAuth API 参考

9. XHSAuthCallback

interface XHSAuthCallback {
    fun onSuccess(code: String, state: String?)  // 授权成功，获取到授权码
    fun onError(error: XHSAuthError)             // 授权失败
    fun onCancel()                               // 用户取消授权
}

10. XHSAuthError 错误码

11. 错误处理示例

private fun handleAuthError(error: XHSAuthError) {
    when (error.code) {
        XHSAuthError.ERROR_APP_NOT_INSTALLED -> {
            AlertDialog.Builder(this)
                .setTitle("需要安装或更新小红书")
                .setMessage("请安装或更新到小红书 v9.3.0 及以上版本")
                .setPositiveButton("去更新") { _, _ -> openAppStore("com.xingin.xhs") }
                .show()
        }
        XHSAuthError.ERROR_NOT_CONFIGURED -> {
            Log.e("XHS_SDK", "SDK 未初始化，请先调用 XHSAuth.configure()")
        }
        else -> {
            Toast.makeText(this, "授权失败：${error.message}", Toast.LENGTH_LONG).show()
        }
    }
}

12. 从旧版迁移（XHSLoginManager → XHSAuth）

13. 安全注意事项

1. Secret 模式下请通过 KeyStore / 混淆 / 加密存储等方式妥善保护 app_secret，避免明文硬编码；完全公开分发的客户端可选用 PKCE 模式规避 app_secret 泄露
2. 所有 token 交换必须走 HTTPS
3. 授权码有效期极短（10 分钟）且一次性有效，获取后立即上传后端处理
4. SDK 自动检测小红书 App 版本兼容性
5. 使用随机 state 参数防止 CSRF 攻击