如何使用Login Widget SDK API调用

如有以下需求，可在登录小组件之外单独使用Login Widget SDK 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>`格式的界面语言和区域，其中： `language code` — 符合ISO 639-1标准的语言代码。 `country code` — 符合ISO 3166-1 alpha-2标准的国家/地区代码。支持以下语言：阿拉伯语(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。
disableConfirmByLink	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。	`username` (string) — 用户邮箱地址，例如`email@address.com`。必需。

示例：

Copy

Full screen

Small screen

1let result
2// Request
3api.resendEmail({
4  username: 'email@address.com'
5}).then((res) => {
6  res.code === 204;
7})

免密认证

用户流程：

用户输入手机号码或邮箱地址。根据其输入的凭据，调用api.phoneGetCode或api.emailGetCode。
服务器收到该数据并将包含验证码的邮件或短信发送给用户。如初始化代码时传入了disableConfirmByLink=true（该参数禁用通过邮件中的链接进行登录验证），则使用api.getConfirmCode调用在用户点击链接后进行自动跳转。
api.phoneGetCode或api.emailGetCode调用返回operation_id参数，用于通过api.loginWithPhoneCode或api.loginWithEmailCode调用验证手机号码或邮箱地址。
邮箱地址或手机号码验证成功后，返回带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}

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

用户流程：

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

密码重置

用户流程：

应用程序打开用户输入邮箱地址或用户名的表单。执行api.reset调用。
服务器向用户发送验证邮件。
用户点击邮件中的链接，打开输入新密码的表单。
用户输入新密码。执行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年8月29日

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

代码初始化
API调用
用户使用密码进行注册
使用密码登录
帐户确认
免密认证
免密情况下的其他字段请求
密码重置
单点登录

Your browser is not supported. Please try a different browser

如何使用Login Widget SDK API调用

代码初始化

projectId

fullLocale

callbackUrl

emailTemplate

payload

with_logout

clientId

scope

state

redirectUrl

disableConfirmByLink

is_oauth2

API调用

用户使用密码进行注册

使用密码登录

帐户确认

免密认证

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

密码重置

单点登录

api.checkUserAuthSSO();

api.clearSSO();