如何使用Login Widget SDK API调用

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

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

注:
并非所有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>格式的界面语言和区域,其中:支持以下语言:阿拉伯语(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。
      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。
          示例:
          Copy
          Full screen
          Small screen
            let result
            // Request
            api.resendEmail({
              username: 'email@address.com'
            }).then((res) => {
              res.code === 204;
            })
            

            免密认证

            用户流程:
            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
              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'
                      }
                      

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

                      用户流程:
                      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
                        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'
                                  }
                                  

                                  密码重置

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

                                              报告问题
                                              我们非常重视内容质量。您的反馈将帮助我们做得更好。
                                              请留下邮箱以便我们后续跟进
                                              感谢您的反馈!