如何使用Login Widget SDK API调用

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

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

代码初始化

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

Copy

Full screen

Small screen

<script>
const api = new XsollaLogin.Api({
  projectId: 'someProjectId'
});
</script>

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

Copy

Full screen

Small screen

import XsollaLogin from '@xsolla/login-sdk';
const api = new XsollaLogin.Api({
  projectId: 'someProjectId'
});

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

参数	类型	描述
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）、捷克语（cz_CZ）、英语（en_XX）、德语（de_DE）、西班牙语（es_ES）、法语（fr_FR）、希伯来语（he_IL）、意大利语（it_IT）、日语（ja_JP）、汉语（ko_KR）、波兰语（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

let result
// Request
api.signup({
  userInfo: {
    email: 'email@address.com',
    fields: {
      nickname: 'Johny'
    },
    password: 'password123',
    username: 'John'
  }
}).then((res) => {
  result = res;
})

// Response
result === {
  login_url: 'https://someurl.com?token=XXXXXXX'
}

使用密码登录

调用	描述	参数
api.login(credentials)；	通过密码认证用户。用户登录所必需的用户数据在`credentials`对象中传入。通过认证的用户的令牌传入在响应中。	`username` (string) — 用户名，例如`John`，或邮箱地址，例如`email@address.com`。必需。 `password` (string) — 用户密码。必需。

示例：

Copy

Full screen

Small screen

let result
// Request
api.login({
  credentials: {
    password: 'password123',
    username: 'email@address.com'
  }
}).then((res) => {
  result = res;
})

// Response
result === {
  login_url: 'https://someurl.com?token=XXXXXXX'
}

// Response with additional fields
result === {
  ask_fields: [{
    confirmation_type: 'code' || 'link'
    name: 'phone_number'
    required: false
    step: 0 // Displays the position of the field in the data retrieval queue.
    type: 'phone'
    validation: {} // Custom validation
  }]
  login_url: 'https://someurl.com?token=XXXXXXX',
  token: 'sometoken'
}

帐户确认

调用	描述	参数
api.resendEmail(username)；	额外发送一封帐户验证邮件。要验证帐户，用户应点击邮件中的链接。用户邮箱地址在`username`对象中传入。响应返回标准代码204。	`username` (string) — 用户邮箱地址，例如`email@address.com`。必需。

示例：

Copy

Full screen

Small screen

let result
// Request
api.resendEmail({
  username: 'email@address.com'
}).then((res) => {
  res.code === 204;
})

免密认证

用户流程：

用户输入手机号码或邮箱地址。根据其输入的凭据，调用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

let result
// Request
api.phoneGetCode({
  phone_number: '+somenumber',
  link_url: 'https://someurl.com',
  isOauth2: true
}).then((res) => {
  result = res;
})

// Response
result === {
  operation_id: '2334j255fdf13d515fgd1'
}

调用	描述	参数
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

let result
// Request
api.emailGetCode({
  email: 'email@address.com',
  link_url: 'https://someurl.com',
  isOauth2: true
}).then((res) => {
  result = res;
})

// Response
result === {
  operation_id: '2334j255fdf13d515fgd1'
}

调用	描述	参数
api.getConfirmCode({ cancelToken, login, operation_id });	获取验证码，以在用户点击链接后进行自动重定向。	`cancelToken` (string) — 结束会话的唯一令牌。必需。 `login` (string) — 用户手机号码或邮箱地址。必需。 `operation_id` (string) — 在当前会话中确认用户手机号码或邮箱地址的唯一标识符。必需。

示例：

Copy

Full screen

Small screen

let result
// Request
const axiosCancelToken = Axios.CancelToken.source();

api.getConfirmCode({
  cancelToken: axiosCancelToken,
  login: '+somenumber' || 'email@address.com',
  operation_id: '334j255fdf13d515fgd1'
}).then((res) => {
  result = res;
})

// Response
result === {
  code: 'string'
}

// If the waiting time has elapsed, returns:
result === {
  error: {
    code: '010-050',
    description: 'Deadline exceeded.'
  }
}

// If you no longer need to wait for verification through the link you can close the request waiting period:
axiosCancelToken.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

let result
// Request
api.loginWithPhoneCode({
  phone_number: 'email@address.com',
  code: '3423',
  operation_id: '334j255fdf13d515fgd1',
  isOauth2: true
}).then((res) => {
  result = res;
})

// Response
result === {
  login_url: 'https://someurl.com?token=XXXXXXX'
}


// Response with additional fields
result === {
  ask_fields: [{
    confirmation_type: 'code' || 'link'
    name: 'email'
    required: false
    step: 0 // Displays the position of the field in the data retrieval queue.
    type: 'email'
    validation: {} // Custom validation
  }]
  login_url: 'https://someurl.com?token=XXXXXXX',
  token: 'sometoken'
}

调用	描述	参数
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

let result
// Request
api.loginWithEmailCode({
  email: 'email@address.com',
  code: '3423',
  operation_id: '334j255fdf13d515fgd1',
  isOauth2: true
}).then((res) => {
  result = res;
})

// Response
result === {
  login_url: 'https://someurl.com?token=XXXXXXX'
}

// Response with additional fields
result === {
  ask_fields: [{
    confirmation_type: 'code' || 'link'
    name: 'phone_number'
    required: false
    step: 0 // Displays the position of the field in the data retrieval queue.
    type: 'phone'
    validation: {} // Custom validation
  }]
  login_url: 'https://someurl.com?token=XXXXXXX',
  token: 'sometoken'
}

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

用户流程：

成功认证用户后，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

let result
// Request
api.getAskFields({
  token: 'sometoken'
}).then((res) => {
  result = res;
})

// Response
result === [
  {
    confirmation_type: 'code' || 'link'
    name: 'phone_number' || 'email'
    required: false
    step: 0 // Displays the position of the field in the data retrieval queue.
    type: 'phone' || 'email'
    validation: {} // Custom validation
  }
]

调用	描述	参数
api.ask({ fields, token, link_url });	发送额外用户数据，即手机号码或邮箱地址。响应中返回用于验证指定的手机号码或邮箱地址的`operation_id`参数。如不要求验证，则响应中返回用于重定向已认证用户的URL和`token`参数。	`fields` (object) — 传入用户手机号码或邮箱地址的对象。必需。 `token` (string) — 用户JWT。必需。 `link_url` (string) — 确认URL。

手机号码发送示例：

Copy

Full screen

Small screen

let result
// Request
api.ask({
  fields: {  
    phone_number: '+somenumber'
  },
  link_url: 'https://someurl.com',
  token: 'sometoken'
}).then((res) => {
  result = res;
})

// Response
result === {
  error: {
    code: '003-014'
    description: 'Confirm phone number.'
    details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
  }
}

// Response without confirmation
result === {
  redirect_url: '<login_url>?token=<token>'
}

邮箱地址发送示例：

Copy

Full screen

Small screen

let result
// request
api.ask({
  fields: {  
    email: 'email@address.com'
  },
  link_url: 'https://someurl.com',
  token: 'sometoken'
}).then((res) => {
  result = res;
})

// Response
result === {
  error: {
    code: '003-011'
    description: 'Confirm email.'
    details: { operation_id: 'BPaBScLM44GesoOYSxT5I8QfgIrTSURd' }
  }
}

// Response without confirmation
result === {
  redirect_url: '<login_url>?token=<token>'
}

调用	描述	参数
api.getConfirmCode({ cancelToken, login, operation_id });	获取验证码，以在用户点击链接后自动重定向。	`cancelToken` (string) — 结束会话的唯一令牌。必需。 `login` (string) — 用户手机号码或邮箱地址。必需。 `operation_id` (string) — 在当前会话中确认用户手机号码或邮箱地址的唯一标识符。必需。

示例：

Copy

Full screen

Small screen

let result
// Request
const axiosCancelToken = Axios.CancelToken.source();

api.getConfirmCode({
  cancelToken: axiosCancelToken,
  login: '+somenumber' || 'email@address.com',
  operation_id: '334j255fdf13d515fgd1'
}).then((res) => {
  result = res;
})

// Response
result === {
  code: 'string'
}

// If the waiting time has elapsed, returns:
result === {
  error: {
    code: '010-050',
    description: 'Deadline exceeded.'
  }
}

// If you no longer need to wait for verification through the link you can close the request waiting period:
axiosCancelToken.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

let result
// Request
api.loginWithPhoneCode({
  phone_number: 'email@address.com',
  code: '3423',
  operation_id: '334j255fdf13d515fgd1',
  isOauth2: true
}).then((res) => {
  result = res;
})

// Response
result === {
  login_url: 'https://someurl.com?token=XXXXXXX'
}


// Response with additional fields
result === {
  ask_fields: [{
    confirmation_type: 'code' || 'link'
    name: 'email'
    required: false
    step: 0 // Displays the position of the field in the data retrieval queue.
    type: 'email'
    validation: {} // Custom validation
  }]
  login_url: 'https://someurl.com?token=XXXXXXX',
  token: 'sometoken'
}

调用	描述	参数
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

let result
// Request
api.loginWithEmailCode({
  email: 'email@address.com',
  code: '3423',
  operation_id: '334j255fdf13d515fgd1',
  isOauth2: true
}).then((res) => {
  result = res;
})

// Response
result === {
  login_url: 'https://someurl.com?token=XXXXXXX'
}

// Response with additional fields
result === {
  ask_fields: [{
    confirmation_type: 'code' || 'link'
    name: 'phone_number'
    required: false
    step: 0 // Displays the position of the field in the data retrieval queue.
    type: 'phone'
    validation: {} // Custom validation
  }]
  login_url: 'https://someurl.com?token=XXXXXXX',
  token: 'sometoken'
}

密码重置

用户流程：

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

调用	描述	参数
api.reset(username)；	重置密码并确认该操作。要确认重置密码，用户应点击邮件中的链接。用户名或用户邮箱地址传入在`username`对象中。响应中返回`204`代码。	`username` (string) — 用户名，例如`John`，或邮箱地址，例如`email@address.com`。必需。

示例：

Copy

Full screen

Small screen

let result
// Request
api.reset({
  username: 'John'
}).then((res) => {
  res.code === 204;
})

调用	描述	参数
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

let result
// Request
api.set({
  new_password: 'newpass',
  reset_code: '3423',
  user_id: '324324234'
}).then((res) => {
  res.code === 204;
})

单点登录

请参阅单点登录的说明了解详细信息。

参数	类型	描述
api.checkUserAuthSSO();		检查用户是否通过单点登录授权。如成功，则返回一个一次性`code`。

示例：

Copy

Full screen

Small screen

let result
// Request
api
  .checkUserAuthSSO()
  .then(res => {
    result === res;
  });

result === {
  code: "examplecode"
}

调用	描述	参数
api.userAuthSSOWithRedirect(loginUrl);	检查用户是否通过单点登录授权。如成功，用户将被重定向至该URL（即生成的包含一个授权码的`loginUrl`）。	`loginUrl` (string) — 在进行SSO检查后将用户重定向到的URL。必须与发布商帐户中您的登录管理器项目 > 常规设置里URL部分中指定的回调URL一致。如果有多个用于用户重定向的URL，此参数为必需。

示例：

Copy

Full screen

Small screen

// Request
api
  .userAuthSSOWithRedirect(
    loginUrl: 'some-redirect-url.com'
  )
  .then(res => {
    res.code === 302;
  });

调用	描述	参数
api.logout(token, session);	根据`session`参数将用户从系统中登出并删除用户会话。	`token` (string) — 用户JWT。必需。 `session` (string) — 显示如何将用户从系统中登出以及删除其会话。必需。可以是： `sso` — 只删除SSO用户会话。 `all` — 删除SSO用户会话和所有访问令牌及更新。

示例：

Copy

Full screen

Small screen

// Request
api
  .logout(
    token: 'exampleToken',
    session: 'sso' | 'all'
  )
  .then(res => {
    res.code === 204;
  });

参数	类型	描述
api.clearSSO();		从当前用户设备中删除单点登录Cookie文件。如调用成功，则在响应中返回`204`代码。

示例：

Copy

Full screen

Small screen

// Request
api
  .clearSSO()
  .then(() => {
    // Success
  });

感谢您的反馈！

我们会查看您的留言并运用它改进用户体验。

上次更新时间: 2024年1月22日

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

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();