Авторизация / Как использовать API-методы Login Widget SDK
 На главную

Авторизация

  • Руководство по интеграции

  • Возможности

  • Инструкции

  • Расширения

  • Справочники

    • Как использовать API-методы Login Widget SDK

    Содержание

    Вы можете работать с API-методами Login Widget SDK отдельно от виджета, если хотите:

    • использовать собственный дизайн виджета;
    • реализовать только часть сценария работы виджета.

    Note
    Список методов для этой возможности ограничен.

    Инициализация кода

    Чтобы использовать API-методы Login Widget SDK без виджета, подключите указанный ниже код инициализации в тег <body>:

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

      Код инициализации при использовании npm-пакета:

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

        В коде инициализации передаются следующие параметры:

        ПараметрТипОписание
        projectId
        		stringID варианта авторизации из Личного кабинета. Обязательный.
        fullLocale
        		stringЯзык интерфейса и регион в формате <language code>_<country code>, где:
        • language code — код языка в формате ISO 639-1;
        • country code — код страны в формате ISO 3166-1 alpha-2.
        Поддерживаются следующие языки: арабский (ar_AE), болгарский (bg_BG), чешский (cz_CZ), немецкий (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
        		stringURL-адрес, с которым работает сервер Авторизации Иксолла при успешной авторизации или регистрации.
        emailTemplate
        		stringНазвание проекта, от имени которого отправляются письма пользователям при авторизации.
        payload
        		stringДополнительные данные, которые могут передаваться в коде. Добавляются в JWT пользователя при успешной авторизации.
        with_logout
        		booleanОтзывать ли предыдущие токены при новой авторизации. Значение по умолчанию — false.
        clientId
        		stringID клиентского приложения. Передается, если в приложении используется авторизация по протоколу OAuth 2.0.
        scope
        		stringДополнительная информация, которую приложение запрашивает об аккаунте пользователя. Передается, если в приложении используется авторизация по протоколу OAuth 2.0. Возможные значения:
        • email — дополнительный запрос email-адреса пользователя при авторизации через социальные сети;
        • offline — автоматическое обновление JWT после истечения срока действия;
        • playfab — дополнительная передача параметра SessionTicket в JWT, если данные о пользователях хранятся в PlayFab.
        Вы также можете задавать свои параметры. Сервер Авторизации Иксолла их не обрабатывает, но возвращает в JWT.
        state
        		stringДополнительная верификация пользователя, например, для предотвращения CSRF-атак. Должен содержать не менее 8 символов.
        redirectUrl
        		stringURL-адрес, на который перенаправляется пользователь после подтверждения аккаунта, успешной аутентификации или подтверждения сброса пароля.
        booleanОтключать ли подтверждение беспарольной авторизации по email-адресу или номеру телефона по ссылке в письме. Значение по умолчанию — false.
        is_oauth2
        		booleanИспользовать ли способ аутентификации пользователя по протоколу OAuth 2.0. Значение по умолчанию — false.

        Методы API

        Вы можете использовать без виджета следующие API-методы Login Widget SDK:

        Регистрация пользователя по паролю

        МетодОписаниеПараметры
        api.signup(userInfo);Регистрация нового пользователя. В объекте userInfo передаются данные о пользователе при регистрации. В ответе возвращается токен зарегистрированного пользователя.
        • email (string) — email-адрес пользователя. Обязательный.
        • 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-адрес, например, 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 передается email-адрес пользователя. В ответе возвращается код 204.
            • username (string) — email-адрес пользователя, например, email@address.com. Обязательный.

            Пример:

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

              Беспарольная авторизация

              Сценарий пользователя:

              1. Пользователь вводит телефон или email-адрес. В зависимости от введенных данных вызывается метод api.phoneGetCode или api.emailGetCode.
              2. Сервер получает данные и отправляет на номер телефона или email-адрес сообщение с кодом. Если при инициализации кода был передан параметр disableConfirmByLink=true, который отключает подтверждение авторизации по ссылке в письме, для автоматического перенаправления пользователя после перехода по ссылке используется метод api.getConfirmCode.
              3. Метод api.phoneGetCode или api.emailGetCode возвращает параметр operation_id, который используется для подтверждения номера телефона или email-адреса с помощью методов api.loginWithPhoneCode или api.loginWithEmailCode. При успешном подтверждении номера телефона или email-адреса возвращается URL-адрес с параметром token, который используется в запросах дополнительных данных о пользователе.

              МетодОписаниеПараметры
              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 });Отправка кода подтверждения на email-адрес. В ответе возвращается параметр operation_id, который используется для подтверждения email-адреса.
                • email (string) — email-адрес для авторизации без пароля.
                • 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) — номер телефона или email-адрес пользователя. Обязательный.
                  • operation_id (string) — уникальный идентификатор, который используется для подтверждения номера телефона или email-адреса в данной сессии. Обязательный.

                  Пример:

                  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 });Подтверждение номера телефона. В ответе возвращается URL-адрес с параметром token, который используется в запросах дополнительных данных о пользователе.
                    • 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 });Подтверждение email-адреса. В ответе возвращается URL-адрес с параметром token, который используется в запросах дополнительных данных о пользователе.
                      • email (string) — email-адрес для авторизации без пароля.
                      • code (string) — код, который приходит на email-адрес.
                      • operation_id (string) — уникальный идентификатор, который используется для подтверждения email-адреса в данной сессии.
                      • 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.loginWithEmailCode или api.loginWithPhoneCode возвращает массив с полями, которые можно отображать в приложении в отдельной форме и дополнительно собирать номер телефона или email-адрес пользователя. Список полей также можно получить с помощью вызова отдельного метода api.getAskFields.
                        2. Пользователь вводит номер телефона или email-адрес. Вызывается метод api.ask.
                        3. Сервер получает данные и отправляет на номер телефона или email-адрес сообщение с кодом. Если при инициализации кода был передан параметр disableConfirmByLink=true, который отключает подтверждение авторизации по ссылке в письме, для автоматического перенаправления пользователя после перехода по ссылке используется метод api.getConfirmCode.
                        4. Метод 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 });Отправка дополнительных данных о пользователе — номера телефона или email-адреса. В ответе возвращается параметр operation_id, который используется для подтверждения указанного номера телефона или email-адреса. Если подтверждение не требуется, в ответе возвращается URL-адрес с параметром token, который используется для редиректа на авторизованного пользователя.
                          • fields (object) — объект, в котором передаются данные о пользователе: номер телефона или email-адрес. Обязательный.
                          • 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>'
}

                            Пример с отправкой email-адреса:

                            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) — номер телефона или email-адрес пользователя. Обязательный.
                              • operation_id (string) — уникальный идентификатор, который используется для подтверждения номера телефона или email-адреса в данной сессии. Обязательный.

                              Пример:

                              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 });Подтверждение номера телефона. В ответе возвращается URL-адрес с параметром token, который используется в запросах дополнительных данных о пользователе.
                                • 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 });Подтверждение email-адреса. В ответе возвращается URL-адрес с параметром token, который используется в запросах дополнительных данных о пользователе.
                                  • email (string) — email-адрес для авторизации без пароля.
                                  • code (string) — код, который приходит на email-адрес.
                                  • operation_id (string) — уникальный идентификатор, который используется для подтверждения email-адреса в данной сессии.
                                  • 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. Приложение открывает форму, в которой пользователь вводит email-адрес или имя пользователя. Вызывается метод api.reset.
                                    2. Сервер отправляет пользователю письмо с подтверждением.
                                    3. Пользователь переходит по ссылке в письме и открывает форму для ввода нового пароля.
                                    4. Пользователь вводит новый пароль. Вызывает метод api.set.

                                    МетодОписаниеПараметры
                                    api.reset(username);Сброс пароля с подтверждением действия. Чтобы подтвердить сброс пароля, пользователь должен перейти по ссылке в письме. В объекте username передается имя или email-адрес пользователя. В ответе возвращается код 204.
                                    • username (string) — имя пользователя, например, John или email-адрес, например, 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;
})

                                        Сквозная аутентификация (Single Sign-On)

                                        Note
                                        Подробная информация о сквозной аутентификации представлена в инструкции.
                                        ПараметрТипОписание
                                        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) — URL-адрес для перенаправления пользователя после проверки аутентификации пользователя (SSO). Должен быть идентичен Callback 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;
  });

                                              Была ли статья полезна?
                                              Спасибо!
                                              Что может сделать страницу еще лучше? Сообщение
                                              Жаль, что так произошло
                                              Расскажите, почему статья не была полезна. Сообщение
                                              Спасибо за обратную связь!
                                              Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
                                              Оценить страницу
                                              Оценить страницу
                                              Что может сделать страницу еще лучше?

                                              В другой раз

                                              Спасибо за обратную связь!
                                              Последнее обновление: 21 октября 2021

                                              Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

                                              Сообщите о проблеме
                                              Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
                                              Укажите email-адрес, чтобы мы могли связаться с вами
                                              Спасибо за обратную связь!