如何使用Login Widget SDK API调用

如有以下需求,可在登录小组件之外单独使用Login Widget SDK API调用:

  • 使用您自己的小组件设计
  • 部分实现登录管理器小组件的工作流程

注:
并非所有API调用都支持此场景。

代码初始化

要在不使用小组件的情况下使用Login Widget SDK API调用,请在<body>标记后追加以下代码:

Copy
Full screen
Small screen
1<script>
2const api = new XsollaLogin.Api({
3  projectId: 'someProjectId'
4});
5</script>

使用npm-package时的初始化代码:

Copy
Full screen
Small screen
1import XsollaLogin from '@xsolla/login-sdk';
2const api = new XsollaLogin.Api({
3  projectId: 'someProjectId'
4});

在初始化代码中传入以下参数:

参数类型描述
projectId
string您在发布商帐户中的登录管理器项目ID。必需
fullLocale
string<language code>_<country code>格式的界面语言和区域,其中:支持以下语言:阿拉伯语(ar_AE)、保加利亚语(bg_BG)、捷克语(cs_CZ)、菲律宾语(fil_PH)、英语(en_XX)、德语(de_DE)、西班牙语(es_ES)、法语(fr_FR)、希伯来语(he_IL)、印度尼西亚语(id_ID)、意大利语(it_IT)、日语(ja_JP)、高棉语(km-KH)、韩语(ko_KR)、老挝语(lo_LA)、缅甸语(my_MM)、尼泊尔语(ne_NP)、波兰语(pl_PL)、葡萄牙语(pt_BR)、罗马尼亚语(ro_RO)、俄语(ru_RU)、泰语(th_TH)、土耳其语(tr_TR)、越南语(vi_VN)、简体中文(zh_CN)、繁体中文(zh_TW)。
该参数影响根据指定区域的使用频率对社交网络进行排序,并影响发送给用户的邮件的语言。
callbackUrl
string登录或注册成功后,艾克索拉登录管理器使用的URL。
emailTemplate
string向用户发送邮件的项目主体名称。
payload
string可在代码中传递的额外数据。该数据在用户成功登录后追加到用户JWT中。
with_logout
boolean新登录期间是否撤销之前的令牌。默认为false
clientId
string客户端应用的ID。如应用使用了基于OAuth 2.0协议的认证,则需传入。
scope
string应用请求的关于用户帐户的额外信息。如应用使用基于OAuth 2.0协议的认证,则应传入。 可能值:
  • email — 通过社交网络登录时对用户邮箱地址的额外请求。
  • offline — JWT到期后的自动更新。
  • playfab — 如用户数据存储在PlayFab,则自动向JWT中传入SessionTicket参数。
您也可以指定自己的参数。艾克索拉登录管理器服务器不处理它们,仅将它们返回给JWT。
state
string用于防止CSRF攻击等的额外用户验证。必须大于8个字符。
redirectUrl
string用户验证帐户、登录或确认密码重置后将其重定向到的URL。
boolean用户通过邮箱或手机免密登录时,是否禁用通过邮件中的链接进行免密认证确认。默认为false
is_oauth2
boolean是否对用户使用基于OAuth 2.0协议的认证。默认为false

API调用

可在不使用登录管理器小组件的情况下使用以下Login Widget SDK API调用:

用户使用密码进行注册

调用描述参数
api.signup(userInfo);注册新用户。用户数据在注册过程中传入userInfo对象。已注册用户的令牌在响应中传入。
  • email (string) — 用户邮箱地址。必需
  • username (string) — 用户名。必需
  • password (string) — 用户密码。必需
  • nickname (string) — 用户昵称。
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.signup({
 4  userInfo: {
 5    email: 'email@address.com',
 6    fields: {
 7      nickname: 'Johny'
 8    },
 9    password: 'password123',
10    username: 'John'
11  }
12}).then((res) => {
13  result = res;
14})
15
16// Response
17result === {
18  login_url: 'https://someurl.com?token=XXXXXXX'
19}

使用密码登录

调用描述参数
api.login(credentials);通过密码认证用户。用户登录所必需的用户数据在credentials对象中传入。通过认证的用户的令牌传入在响应中。
  • username (string) — 用户名,例如John,或邮箱地址,例如email@address.com必需
  • password (string) — 用户密码。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.login({
 4  credentials: {
 5    password: 'password123',
 6    username: 'email@address.com'
 7  }
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17// Response with additional fields
18result === {
19  ask_fields: [{
20    confirmation_type: 'code' || 'link'
21    name: 'phone_number'
22    required: false
23    step: 0 // Displays the position of the field in the data retrieval queue.
24    type: 'phone'
25    validation: {} // Custom validation
26  }]
27  login_url: 'https://someurl.com?token=XXXXXXX',
28  token: 'sometoken'
29}

帐户确认

调用描述参数
api.resendEmail(username);额外发送一封帐户验证邮件。要验证帐户,用户应点击邮件中的链接。用户邮箱地址在username对象中传入。响应返回标准代码204。
示例:
Copy
Full screen
Small screen
1// Request
2api.resendEmail({
3  username: "email@address.com"
4}).then((res) => {
5  if (res.code === 204) {
6    console.log("Email resend success");
7  }
8});

免密认证

用户流程:

  1. 用户输入手机号码或邮箱地址。根据其输入的凭据,调用api.phoneGetCodeapi.emailGetCode
  2. 服务器收到该数据并将包含验证码的邮件或短信发送给用户。如初始化代码时传入了disableConfirmByLink=true(该参数禁用通过邮件中的链接进行登录验证),则使用api.getConfirmCode调用在用户点击链接后进行自动跳转。
  3. api.phoneGetCodeapi.emailGetCode调用返回operation_id参数,用于通过api.loginWithPhoneCodeapi.loginWithEmailCode调用验证手机号码或邮箱地址。
  4. 邮箱地址或手机号码验证成功后,返回带token参数的URL。该参数用于对额外用户数据的请求中。

调用描述参数
api.phoneGetCode({ phone_number, link_url, isOauth2 });向手机号码发送验证码。响应中返回用于确认手机号码的operation_id参数。
  • phone_number (string) — 用于免密认证的手机号码。
  • link_url (string) — 确认URL。
  • isOauth2 (boolean) — 是否对用户使用基于OAuth 2.0协议的认证。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.phoneGetCode({
 4  phone_number: '+somenumber',
 5  link_url: 'https://someurl.com',
 6  isOauth2: true
 7}).then((res) => {
 8  result = res;
 9})
10
11// Response
12result === {
13  operation_id: '2334j255fdf13d515fgd1'
14}
调用描述参数
api.phoneGetCode({ phone_number, link_url, isOauth2 });向邮箱地址发送验证码。响应中返回用于确认邮箱地址的operation_id参数。
  • email (string) — 用于免密认证的邮箱地址。
  • link_url (string) — 确认URL。
  • isOauth2 (boolean) — 是否对用户使用基于OAuth 2.0协议的认证。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.emailGetCode({
 4  email: 'email@address.com',
 5  link_url: 'https://someurl.com',
 6  isOauth2: true
 7}).then((res) => {
 8  result = res;
 9})
10
11// Response
12result === {
13  operation_id: '2334j255fdf13d515fgd1'
14}
调用描述参数
api.getConfirmCode({ cancelToken, login, operation_id });获取验证码,以在用户点击链接后进行自动重定向。
  • cancelToken (string) — 结束会话的唯一令牌。必需
  • login (string) — 用户手机号码或邮箱地址。必需
  • operation_id (string) — 在当前会话中确认用户手机号码或邮箱地址的唯一标识符。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3const axiosCancelToken = Axios.CancelToken.source();
 4
 5api.getConfirmCode({
 6  cancelToken: axiosCancelToken,
 7  login: '+somenumber' || 'email@address.com',
 8  operation_id: '334j255fdf13d515fgd1'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  code: 'string'
16}
17
18// If the waiting time has elapsed, returns:
19result === {
20  error: {
21    code: '010-050',
22    description: 'Deadline exceeded.'
23  }
24}
25
26// If you no longer need to wait for verification through the link you can close the request waiting period:
27axiosCancelToken.cancel();
调用描述参数
api.loginWithPhoneCode({ phone_number, code, operation_id, isOauth2 });确认手机号码。响应返回带token参数的URL。该参数用于对额外用户数据的请求中。
  • phone_number (string) — 用于免密认证的手机号码。
  • code (string) — 通过短信发送的手机验证码。
  • operation_id (string) — 用于在当前会话中确认用户手机号的唯一标识符。
  • isOauth2 (boolean) — 是否对用户使用基于OAuth 2.0协议的认证。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.loginWithPhoneCode({
 4  phone_number: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17
18// Response with additional fields
19result === {
20  ask_fields: [{
21    confirmation_type: 'code' || 'link'
22    name: 'email'
23    required: false
24    step: 0 // Displays the position of the field in the data retrieval queue.
25    type: 'email'
26    validation: {} // Custom validation
27  }]
28  login_url: 'https://someurl.com?token=XXXXXXX',
29  token: 'sometoken'
30}
调用描述参数
api.loginWithEmailCode({ email, code, operation_id, isOauth2 });确认邮箱地址。响应返回带token参数的URL。该参数用于对额外用户数据的请求中。
  • email (string) — 用于免密认证的手邮箱地址
  • code (string) — 在邮件中发送的验证码。
  • operation_id (string) — 用于在当前会话中确认邮箱地址的唯一标识符。
  • isOauth2 (boolean) — 是否对用户使用基于OAuth 2.0协议的认证。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.loginWithEmailCode({
 4  email: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17// Response with additional fields
18result === {
19  ask_fields: [{
20    confirmation_type: 'code' || 'link'
21    name: 'phone_number'
22    required: false
23    step: 0 // Displays the position of the field in the data retrieval queue.
24    type: 'phone'
25    validation: {} // Custom validation
26  }]
27  login_url: 'https://someurl.com?token=XXXXXXX',
28  token: 'sometoken'
29}

免密情况下的其他字段请求

用户流程:

  1. 成功认证用户后,api.loginWithEmailCodeapi.loginWithPhoneCode调用返回可在应用中一个单独表单里显示的一组字段,额外收集用户的手机号码和邮箱地址。您也可以通过执行api.getAskFields调用来获取该字段列表。
  2. 用户输入手机号码或邮箱地址。执行api.ask
  3. 服务器收到数据并向手机号码或邮箱地址发送验证码。如初始化代码时传入了disableConfirmByLink=true参数(该参数禁用通过邮件中的链接进行登录验证),则使用api.getConfirmCode调用在用户点击链接后进行自动重定向。
  4. api.ask调用返回operation_id参数,用于通过api.loginWithPhoneCodeapi.loginWithEmailCode调用验证手机号码或邮箱地址。
  5. 数据验证成功后,返回用于重定向已认证用户的URL。

调用描述参数
api.getAskFields(token);获取额外请求的字段列表。
  • token (string) — 用户JWT。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.getAskFields({
 4  token: 'sometoken'
 5}).then((res) => {
 6  result = res;
 7})
 8
 9// Response
10result === [
11  {
12    confirmation_type: 'code' || 'link'
13    name: 'phone_number' || 'email'
14    required: false
15    step: 0 // Displays the position of the field in the data retrieval queue.
16    type: 'phone' || 'email'
17    validation: {} // Custom validation
18  }
19]
调用描述参数
api.ask({ fields, token, link_url });发送额外用户数据,即手机号码或邮箱地址。响应中返回用于验证指定的手机号码或邮箱地址的operation_id参数。如不要求验证,则响应中返回用于重定向已认证用户的URL和token参数。
  • fields (object) — 传入用户手机号码或邮箱地址的对象。必需
  • token (string) — 用户JWT。必需
  • link_url (string) — 确认URL。
手机号码发送示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.ask({
 4  fields: {  
 5    phone_number: '+somenumber'
 6  },
 7  link_url: 'https://someurl.com',
 8  token: 'sometoken'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  error: {
16    code: '003-014'
17    description: 'Confirm phone number.'
18    details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
19  }
20}
21
22// Response without confirmation
23result === {
24  redirect_url: '<login_url>?token=<token>'
25}

邮箱地址发送示例:

Copy
Full screen
Small screen
 1let result
 2// request
 3api.ask({
 4  fields: {  
 5    email: 'email@address.com'
 6  },
 7  link_url: 'https://someurl.com',
 8  token: 'sometoken'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  error: {
16    code: '003-011'
17    description: 'Confirm email.'
18    details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
19  }
20}
21
22// Response without confirmation
23result === {
24  redirect_url: '<login_url>?token=<token>'
25}
调用描述参数
api.getConfirmCode({ cancelToken, login, operation_id });获取验证码,以在用户点击链接后自动重定向。
  • cancelToken (string) — 结束会话的唯一令牌。必需
  • login (string) — 用户手机号码或邮箱地址。必需
  • operation_id (string) — 在当前会话中确认用户手机号码或邮箱地址的唯一标识符。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3const axiosCancelToken = Axios.CancelToken.source();
 4
 5api.getConfirmCode({
 6  cancelToken: axiosCancelToken,
 7  login: '+somenumber' || 'email@address.com',
 8  operation_id: '334j255fdf13d515fgd1'
 9}).then((res) => {
10  result = res;
11})
12
13// Response
14result === {
15  code: 'string'
16}
17
18// If the waiting time has elapsed, returns:
19result === {
20  error: {
21    code: '010-050',
22    description: 'Deadline exceeded.'
23  }
24}
25
26// If you no longer need to wait for verification through the link you can close the request waiting period:
27axiosCancelToken.cancel();
调用描述参数
api.loginWithPhoneCode({ phone_number, code, operation_id, isOauth2 });确认手机号码。响应返回带token参数的URL。该参数用于对额外用户数据的请求中。
  • phone_number (string) — 用于免密认证的手机号码。
  • code (string) — 通过短信发送的手机验证码。
  • operation_id (string) — 用于在当前会话中确认用户手机号的唯一标识符。
  • isOauth2 (boolean) — 是否对用户使用基于OAuth 2.0协议的认证。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.loginWithPhoneCode({
 4  phone_number: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17
18// Response with additional fields
19result === {
20  ask_fields: [{
21    confirmation_type: 'code' || 'link'
22    name: 'email'
23    required: false
24    step: 0 // Displays the position of the field in the data retrieval queue.
25    type: 'email'
26    validation: {} // Custom validation
27  }]
28  login_url: 'https://someurl.com?token=XXXXXXX',
29  token: 'sometoken'
30}
调用描述参数
api.loginWithEmailCode({ email, code, operation_id, isOauth2 });确认邮箱地址。响应返回带token参数的URL。该参数用于对额外用户数据的请求中。
  • email (string) — 用于免密认证的手邮箱地址
  • code (string) — 向邮箱地址发送的验证码。
  • operation_id (string) — 用于在当前会话中确认用户邮箱地址的唯一标识符。
  • isOauth2 (boolean) — 是否对用户使用基于OAuth 2.0协议的认证。必需
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api.loginWithEmailCode({
 4  email: 'email@address.com',
 5  code: '3423',
 6  operation_id: '334j255fdf13d515fgd1',
 7  isOauth2: true
 8}).then((res) => {
 9  result = res;
10})
11
12// Response
13result === {
14  login_url: 'https://someurl.com?token=XXXXXXX'
15}
16
17// Response with additional fields
18result === {
19  ask_fields: [{
20    confirmation_type: 'code' || 'link'
21    name: 'phone_number'
22    required: false
23    step: 0 // Displays the position of the field in the data retrieval queue.
24    type: 'phone'
25    validation: {} // Custom validation
26  }]
27  login_url: 'https://someurl.com?token=XXXXXXX',
28  token: 'sometoken'
29}

密码重置

用户流程:

  1. 应用程序打开用户输入邮箱地址或用户名的表单。执行api.reset调用。
  2. 服务器向用户发送验证邮件。
  3. 用户点击邮件中的链接,打开输入新密码的表单。
  4. 用户输入新密码。执行api.set调用。

调用描述参数
api.reset(username);重置密码并确认该操作。要确认重置密码,用户应点击邮件中的链接。用户名或用户邮箱地址传入在username对象中。响应中返回204代码。
  • username (string) — 用户名,例如John,或邮箱地址,例如email@address.com必需
示例:
Copy
Full screen
Small screen
1let result
2// Request
3api.reset({
4  username: 'John'
5}).then((res) => {
6  res.code === 204;
7})
调用描述参数
api.set({ new_password, reset_code, user_id });设置新密码并确认该操作。要确认重置密码,用户应点击邮件中的链接。响应中返回204代码。
  • new_password (string) — 用户输入的新密码。必需
  • reset_code (string) — 用于对发送了密码更改请求的用户进行验证的验证码。该验证码在服务器侧生成,并传入用户点击邮件中的链接重定向到的URL中。必需
  • user_id (string) —用户标识符。在服务器侧生成,并传入用户点击邮件中的链接重定向到的URL中。必需
示例:
Copy
Full screen
Small screen
1let result
2// Request
3api.set({
4  new_password: 'newpass',
5  reset_code: '3423',
6  user_id: '324324234'
7}).then((res) => {
8  res.code === 204;
9})

单点登录

注:
请参阅单点登录的说明了解详细信息。
参数类型描述
api.checkUserAuthSSO();
检查用户是否通过单点登录授权。如成功,则返回一个一次性code
示例:
Copy
Full screen
Small screen
 1let result
 2// Request
 3api
 4  .checkUserAuthSSO()
 5  .then(res => {
 6    result === res;
 7  });
 8
 9result === {
10  code: "examplecode"
11}
调用描述参数
api.userAuthSSOWithRedirect(loginUrl);检查用户是否通过单点登录授权。如成功,用户将被重定向至该URL(即生成的包含一个授权码的loginUrl)。
  • loginUrl (string) — 在进行SSO检查后将用户重定向到的URL。必须与发布商帐户您的登录管理器项目 > 常规设置URL部分中指定的回调URL一致。如果有多个用于用户重定向的URL,此参数为必需。
示例:
Copy
Full screen
Small screen
1// Request
2api
3  .userAuthSSOWithRedirect(
4    loginUrl: 'some-redirect-url.com'
5  )
6  .then(res => {
7    res.code === 302;
8  });
调用描述参数
api.logout(token, session);根据session参数将用户从系统中登出并删除用户会话。
  • token (string) — 用户JWT。必需
  • session (string) — 显示如何将用户从系统中登出以及删除其会话。必需。可以是:
    • sso — 只删除SSO用户会话。
    • all — 删除SSO用户会话和所有访问令牌及更新。
示例:
Copy
Full screen
Small screen
1// Request
2api
3  .logout(
4    token: 'exampleToken',
5    session: 'sso' | 'all'
6  )
7  .then(res => {
8    res.code === 204;
9  });
参数类型描述
api.clearSSO();
从当前用户设备中删除单点登录Cookie文件。如调用成功,则在响应中返回204代码。
示例:
Copy
Full screen
Small screen
1// Request
2api
3  .clearSSO()
4  .then(() => {
5    // Success
6  });
本文对您的有帮助吗?
谢谢!
我们还有其他可改进之处吗? 留言
非常抱歉
请说明为何本文没有帮助到您。 留言
感谢您的反馈!
我们会查看您的留言并运用它改进用户体验。
上次更新时间: 2025年9月19日

发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。

报告问题
我们非常重视内容质量。您的反馈将帮助我们做得更好。
请留下邮箱以便我们后续跟进
感谢您的反馈!
无法发送您的反馈
请稍后重试或发送邮件至doc_feedback@xsolla.com与我们联系。