Как использовать API-методы Login Widget SDK
Вы можете работать с API-методами Login Widget SDK отдельно от виджета, если хотите:
- использовать собственный дизайн виджета;
- реализовать только часть сценария работы виджета.
Примечание
Список методов для этой возможности ограничен.
Инициализация кода
Чтобы использовать API-методы Login Widget SDK без виджета, подключите указанный ниже код инициализации в тег <body>
:
Copy
<script>
const api = new XsollaLogin.Api({
projectId: 'someProjectId'
});
</script>
Код инициализации при использовании npm-пакета:
Copy
import XsollaLogin from '@xsolla/login-sdk';
const api = new XsollaLogin.Api({
projectId: 'someProjectId'
});
В коде инициализации передаются следующие параметры:
Параметр | Тип | Описание |
---|---|---|
projectId | string | ID варианта авторизации из Личного кабинета. Обязательный. |
fullLocale | string | Язык интерфейса и регион в формате <language code>_<country code> , где:
Параметр влияет на сортировку социальных сетей по частоте использования в указанном регионе, а также на выбор языка для писем, отправляемых пользователям. |
callbackUrl | string | URL-адрес, с которым работает сервер Xsolla Login при успешной авторизации или регистрации. |
emailTemplate | string | Название проекта, от имени которого отправляются письма пользователям при авторизации. |
payload | string | Дополнительные данные, которые могут передаваться в коде. Добавляются в JWT пользователя при успешной авторизации. |
with_logout | boolean | Отзывать ли предыдущие токены при новой авторизации. Значение по умолчанию — false . |
clientId | string | ID клиентского приложения. Передается, если в приложении используется авторизация по протоколу OAuth 2.0. |
scope | string | Дополнительная информация, которую приложение запрашивает об аккаунте пользователя. Передается, если в приложении используется авторизация по протоколу OAuth 2.0. Возможные значения:
|
state | string | Дополнительная верификация пользователя, например, для предотвращения CSRF-атак. Должен содержать не менее 8 символов. |
redirectUrl | string | URL-адрес, на который перенаправляется пользователь после подтверждения аккаунта, успешной аутентификации или подтверждения сброса пароля. |
disableConfirmByLink | boolean | Отключать ли подтверждение беспарольной авторизации по email-адресу или номеру телефона по ссылке в письме. Значение по умолчанию — false . |
is_oauth2 | boolean | Использовать ли способ аутентификации пользователя по протоколу OAuth 2.0. Значение по умолчанию — false . |
Методы API
Вы можете использовать без виджета следующие API-методы Login Widget SDK:
- Регистрация пользователя по паролю
- Авторизация по паролю
- Подтверждение учетной записи
- Беспарольная авторизация
- Дозапрос полей без пароля
- Сброс пароля
- Сквозная аутентификация (Single Sign-On)
Регистрация пользователя по паролю
Метод | Описание | Параметры |
---|---|---|
api.signup(userInfo); | Регистрация нового пользователя. В объекте userInfo передаются данные о пользователе при регистрации. В ответе возвращается токен зарегистрированного пользователя. |
|
Copy
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 передаются данные о пользователе, необходимые для авторизации. В ответе возвращается токен авторизованного пользователя. |
|
Copy
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. |
|
Copy
let result
// Request
api.resendEmail({
username: 'email@address.com'
}).then((res) => {
res.code === 204;
})
Беспарольная авторизация
Сценарий пользователя:- Пользователь вводит телефон или email-адрес. В зависимости от введенных данных вызывается метод
api.phoneGetCode
илиapi.emailGetCode
. - Сервер получает данные и отправляет на номер телефона или email-адрес сообщение с кодом. Если при инициализации кода был передан параметр
disableConfirmByLink=true
, который отключает подтверждение авторизации по ссылке в письме, для автоматического перенаправления пользователя после перехода по ссылке используется методapi.getConfirmCode
. - Метод
api.phoneGetCode
илиapi.emailGetCode
возвращает параметрoperation_id
, который используется для подтверждения номера телефона или email-адреса с помощью методовapi.loginWithPhoneCode
илиapi.loginWithEmailCode
. При успешном подтверждении номера телефона или email-адреса возвращается URL-адрес с параметромtoken
, который используется в запросах дополнительных данных о пользователе.
Метод | Описание | Параметры |
---|---|---|
api.phoneGetCode({ phone_number, link_url, isOauth2 }); | Отправка кода подтверждения на номер телефона. В ответе возвращается параметр operation_id , который используется для подтверждения номера телефона. |
|
Copy
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-адреса. |
|
Copy
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 }); | Ожидание кода подтверждения для автоматического перенаправления пользователя после перехода по ссылке. |
|
Copy
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 , который используется в запросах дополнительных данных о пользователе. |
|
Copy
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 , который используется в запросах дополнительных данных о пользователе. |
|
Copy
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
возвращает массив с полями, которые можно отображать в приложении в отдельной форме и дополнительно собирать номер телефона или email-адрес пользователя. Список полей также можно получить с помощью вызова отдельного методаapi.getAskFields
. - Пользователь вводит номер телефона или email-адрес. Вызывается метод
api.ask
. - Сервер получает данные и отправляет на номер телефона или email-адрес сообщение с кодом. Если при инициализации кода был передан параметр
disableConfirmByLink=true
, который отключает подтверждение авторизации по ссылке в письме, для автоматического перенаправления пользователя после перехода по ссылке используется методapi.getConfirmCode
. - Метод
api.ask
возвращает параметрoperation_id
, который используется для подтверждения данных с помощью методовapi.loginWithPhoneCode
илиapi.loginWithEmailCode
. При успешном подтверждении данных возвращается URL-адрес, который используется для редиректа на авторизованного пользователя.
Метод | Описание | Параметры |
---|---|---|
api.getAskFields(token); | Получение списка полей для дозапроса. |
|
Copy
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 , который используется для редиректа на авторизованного пользователя. |
|
Copy
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
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 }); | Ожидание кода подтверждения для автоматического перенаправления пользователя после перехода по ссылке. |
|
Copy
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 , который используется в запросах дополнительных данных о пользователе. |
|
Copy
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 , который используется в запросах дополнительных данных о пользователе. |
|
Copy
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'
}
Сброс пароля
Сценарий пользователя:- Приложение открывает форму, в которой пользователь вводит email-адрес или имя пользователя. Вызывается метод
api.reset
. - Сервер отправляет пользователю письмо с подтверждением.
- Пользователь переходит по ссылке в письме и открывает форму для ввода нового пароля.
- Пользователь вводит новый пароль. Вызывает метод
api.set
.
Метод | Описание | Параметры |
---|---|---|
api.reset(username); | Сброс пароля с подтверждением действия. Чтобы подтвердить сброс пароля, пользователь должен перейти по ссылке в письме. В объекте username передается имя или email-адрес пользователя. В ответе возвращается код 204 . |
|
Copy
let result
// Request
api.reset({
username: 'John'
}).then((res) => {
res.code === 204;
})
Метод | Описание | Параметры |
---|---|---|
api.set({ new_password, reset_code, user_id }); | Установка нового пароля с подтверждением действия. Чтобы подтвердить установку нового пароля, пользователь должен перейти по ссылке в письме. В ответе возвращается код 204 . |
|
Copy
let result
// Request
api.set({
new_password: 'newpass',
reset_code: '3423',
user_id: '324324234'
}).then((res) => {
res.code === 204;
})
Сквозная аутентификация (Single Sign-On)
Примечание
Подробная информация о сквозной аутентификации представлена в инструкции.
Параметр | Тип | Описание |
---|---|---|
api.checkUserAuthSSO(); | Проверка входа пользователя в систему через сервис. В случае успеха возвращается одноразовый код авторизации code . |
Copy
let result
// Request
api
.checkUserAuthSSO()
.then(res => {
result === res;
});
result === {
code: "examplecode"
}
Метод | Описание | Параметры |
---|---|---|
api.userAuthSSOWithRedirect(loginUrl); | Проверка входа пользователя в систему через сервис. В случае успеха происходит перенаправление на URL-адрес — сгенерированный loginUrl с кодом авторизации. |
|
Copy
// Request
api
.userAuthSSOWithRedirect(
loginUrl: 'some-redirect-url.com'
)
.then(res => {
res.code === 302;
});
Метод | Описание | Параметры |
---|---|---|
api.logout(token, session); | Вывод пользователя из системы и удаление пользовательской сессии в соответствии со значением параметра session . |
|
Copy
// Request
api
.logout(
token: 'exampleToken',
session: 'sso' | 'all'
)
.then(res => {
res.code === 204;
});
Параметр | Тип | Описание |
---|---|---|
api.clearSSO(); | Удаление файлов cookie сквозной аутентификации с текущего устройства пользователя. В случае успеха возвращается код 204 . |
Copy
// Request
api
.clearSSO()
.then(() => {
// Success
});
Была ли статья полезна?
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.