网页登录 JS SDK 接入指南

使用

安装

npm install @xd-js-sdk/auth

import { signInWithPopup, signInXDWithCode } from "@xd-js-sdk/auth";

接入前准备

接入方需要先向 XD 获取 xd_client_id，并确认要接入国内还是海外。

接入区域	env
国内	prod
海外	prod_intl

env 会决定 SDK 使用哪一套 XD 登录页、后端登录接口和默认重定向地址。公开接入时只使用 prod 或 prod_intl。

如果接入第三方登录，还需要准备对应平台的 client_id。phone、email 和 steam 不需要业务方传第三方 client_id。

登录流程

桌面浏览器默认使用弹窗登录，移动端浏览器会自动切换为当前页面重定向登录。接入方需要在同一个页面里同时处理这两种情况：

1. 页面加载时先读取 URL 上的 xd_auth_payload。
2. 如果存在 xd_auth_payload，调用 signInXDWithCode 换取 XD 登录结果。
3. 如果不存在 xd_auth_payload，在用户点击登录按钮时调用 signInWithPopup 发起登录。
4. 登录完成后，将 SDK 返回的登录结果交给业务自己的登录态逻辑处理。

移动端重定向登录会回到发起登录时的当前页面，并在 URL 上追加 xd_auth_payload。因此接入页面必须能在刷新或重新进入时执行第 1 步和第 2 步。处理完成后，建议清理 URL 上的 xd_auth_payload，避免用户刷新页面时重复处理同一次回调。

SDK6 代码示例

SDK6 是默认登录协议。sdkversion 不传时默认使用 "6"。

下面示例把国内和海外可用平台放在一段里，接入时只保留实际需要的平台。

import { signInWithPopup, signInXDWithCode } from "@xd-js-sdk/auth";

const env = "prod";
// 海外接入使用 env = "prod_intl"
const lang = "zh_CN";
// 海外接入建议使用 lang = "en_US"
const xd_client_id = "your_xd_client_id";

function clearAuthPayload() {
  const url = new URL(window.location.href);
  url.searchParams.delete("xd_auth_payload");
  window.history.replaceState({}, document.title, url.toString());
}

async function handleRedirectResult() {
  const searchParams = new URLSearchParams(window.location.search);
  const xd_auth_payload = searchParams.get("xd_auth_payload");

  if (!xd_auth_payload) return null;

  try {
    return await signInXDWithCode({
      env,
      xd_client_id,
      xd_auth_payload,
    });
  } finally {
    clearAuthPayload();
  }
}

async function login() {
  return signInWithPopup({
    env,
    xd_client_id,
    lang,
    clients: [
      // 国内和海外均可使用
      {
        platform: "taptap",
        client_id: "your_taptap_client_id",
      },
      {
        platform: "email",
      },
      // 国内常用
      {
        platform: "phone",
      },
      // 海外常用
      {
        platform: "google",
        client_id: "your_google_client_id",
      },
      {
        platform: "apple",
        client_id: "your_apple_client_id",
      },
      {
        platform: "steam",
      },
      {
        platform: "facebook",
        client_id: "your_facebook_client_id",
      },
    ],
  });
}

handleRedirectResult()
  .then((result) => {
    if (!result) return;
    // 登录成功，处理 result
  })
  .catch((error) => {
    // 登录失败，处理 error
  });

// 用户点击登录按钮时调用 login()

SDK4 代码示例

SDK4 用于国内 Web SDK 登录场景，支持 TapTap、QQ、微信、Apple 登录。调用方只需要传 XD xd_client_id，clients 中不需要传第三方平台的 client_id、redirect_uri 或 client_uri。

import { signInWithPopup, signInXDWithCode } from "@xd-js-sdk/auth";

const env = "prod";
const xd_client_id = "your_xd_client_id";

function clearAuthPayload() {
  const url = new URL(window.location.href);
  url.searchParams.delete("xd_auth_payload");
  window.history.replaceState({}, document.title, url.toString());
}

async function handleRedirectResult() {
  const searchParams = new URLSearchParams(window.location.search);
  const xd_auth_payload = searchParams.get("xd_auth_payload");

  if (!xd_auth_payload) return null;

  try {
    return await signInXDWithCode({
      env,
      xd_client_id,
      sdkversion: "4",
      xd_auth_payload,
    });
  } finally {
    clearAuthPayload();
  }
}

async function login() {
  return signInWithPopup({
    env,
    xd_client_id,
    sdkversion: "4",
    clients: [
      { platform: "taptap" },
      { platform: "qq" },
      { platform: "weixin" },
      { platform: "apple" },
    ],
    lang: "zh_CN",
    window_features: {
      width: 520,
      height: 720,
    },
  });
}

handleRedirectResult()
  .then((result) => {
    if (!result) return;
    // 登录成功，处理 result
  })
  .catch((error) => {
    // 登录失败，处理 error
  });

// 用户点击登录按钮时调用 login()

API 说明

概览

API	功能
signInWithPopup	发起登录。桌面浏览器使用 window.open 打开登录弹窗；移动端浏览器会自动切换为当前页面重定向。
signInXDWithCode	处理重定向登录回调。读取 URL 上的 xd_auth_payload，换取 XD 登录结果。

SDK6 登录机制

SDK6 会根据 env 和 clients 生成登录页参数。桌面浏览器中，登录页通过 postMessage 把授权结果回传给当前页面，SDK 再换取 XD 登录结果；移动端浏览器中，当前页面会跳转到登录页，登录完成后再重定向回业务页面，并携带 xd_auth_payload。

接入方通常不需要手动配置 redirect_uri 和 signIn_uri。只有 XD 明确提供定制地址或要求覆盖时，才需要传这两个参数。

SDK4 登录机制

当 sdkversion 为 "4" 时，SDK 会打开 XD 登录页，登录页通过 XD 后端发起第三方授权。第三方登录完成后，SDK 会使用 /v3/authorizations/{platform} 换取 XD 登录凭证。通常只需要传 env，不需要手动配置 SDK4 的后端登录地址。

SDK4 当前支持的平台：

platform	登录方式
taptap	TapTap
qq	QQ
weixin	微信
apple	Apple

SDK4 返回值

当 sdkversion 为 "4" 时，signInWithPopup 登录成功后 Promise resolve 的数据结构如下：

{
  status: "success",
  data: {
    success: true,
    state: "业务传入或 SDK 生成的 state",
    data: {
      id: 123,
      user_id: "123456",
      access_token: "xxx",
      scopes: "sdk,user",
      id_token: "xxx",
      refresh_token: "xxx" // 部分登录方式返回
    }
  }
}

signInXDWithCode 成功时返回同样的 status 和 data.success / data.data，但不会额外补充 state 字段。

id_token 为 JWT，主要字段如下：

字段	说明
iss	签发方，固定为 https://api.xd.com
sub	用户标识，与返回值中的 user_id 一致。若账号存在游客升级关系，该值会是对应的游客 ID
aud	XD client id
appId	XD client id
iat	签发时间
nbf	生效时间
exp	过期时间
from	登录来源
jti	JWT 唯一标识

signInWithPopup

参数	是否必填	说明	类型	默认值
clients	必填	各登录平台的配置，详见下方 clients 参数说明。	Array	无
xd_client_id	必填	XD client id。	String	无
env	必填	接入环境。国内使用 prod，海外使用 prod_intl。	String	无
state	可选	业务自定义状态值，用于维护授权请求和授权响应之间的状态。不能包含 ^ 字符。	String	随机生成
window_features	可选	弹窗特性参数，详见 Window.open 位置和尺寸特征，参数会透传给登录弹窗。	Object	{}
lang	可选	登录页语言。国内建议传 zh_CN，海外建议传 en_US。	String	en_US
signIn_uri	可选	登录页地址。默认由 env 决定；如需覆盖，应使用 XD 提供或已配置白名单的登录页地址，不要配置为业务方自己的回调页。	String	由 env 决定
sdkversion	可选	Web 登录协议版本，不是 XDSDK 文档版本。可选值为 "1"、"4"、"6"；默认使用 "6"。传 "4" 时调用 SDK4 Web 登录流程。	String	"6"
set_cookie	可选	将登录结果 JSON 化后写入 XD_AUTH cookie。可以传入对象作为 cookie 设置，例如 set_cookie: { expires: 180 }。	Boolean/Object	false

clients

参数	是否必填	说明	类型	默认值
platform	必填	登录平台。SDK6 国内常用：taptap、phone、email；SDK6 海外常用：taptap、google、apple、steam、facebook、email；SDK4 支持：taptap、qq、weixin、apple。	String	无
client_id	部分平台必填	第三方平台的客户端 ID。SDK6 中 steam、phone、email 不需要传；SDK4 不需要传。	String	无
state	可选	单个平台的状态值，默认使用外层 state。不能包含 ^ 字符。	String	外层 state
redirect_uri	可选	第三方平台授权后的回调地址。默认由 env 和 platform 决定；如需覆盖，请使用 XD 提供或已配置白名单的地址。SDK4 不需要传。	String	由 env 和 platform 决定

signInXDWithCode

参数	是否必填	说明	类型	默认值
env	必填	接入环境，同 signInWithPopup。	String	无
xd_client_id	必填	XD client id，同 signInWithPopup。	String	无
xd_auth_payload	必填	重定向回业务页面后，URL 上携带的 xd_auth_payload 参数。	String	无
sdkversion	可选	Web 登录协议版本。新版 SDK 会从 xd_auth_payload 自动读取；历史 payload 未携带版本时可显式传入。	String	"6"
set_cookie	可选	同 signInWithPopup。	Boolean/Object	false

错误处理

signInWithPopup 和 signInXDWithCode 都会返回 Promise。登录失败、参数缺失、平台不支持或服务端登录失败时，Promise 会进入 catch。用户主动关闭弹窗或取消授权时，不同浏览器和登录方式的 Promise 表现可能不同，接入方不应只依赖 catch 恢复页面状态。

try {
  const result = await signInWithPopup(config);
  // 登录成功
} catch (error) {
  // 登录失败
}

接入方不应只依赖弹窗流程。移动端浏览器会重定向回当前页面，如果页面没有处理 xd_auth_payload，移动端登录会无法完成。

代码兼容性

SDK 使用 @babel/preset-env 转义代码，浏览器兼容范围如下：

defaults
>0.3%
Chrome >= 50

具体浏览器支持程度，请查看 browserslist。