Xsolla Login Widget SDK
The library allows you to use the login widget or Login SDK API methods separately. Currently, SDK supports the following types of authorization:
- via login/password
- via social networks
This page contains:
See Login documentation to find more.
Connecting SDK
Connect Xsolla Login Widget SDK using one of the following methods:
- If the project uses
npm
, launch the console and run
npm i @xsolla/login-sdk
- If the package is not connected, add the following code to the
<head>
tag of the HTML-page where the widget will be placed:
<script src="https://login-sdk.xsolla.com/latest/">
</script>
Widget 2.0 preview
Before you integrate the Xsolla Login widget, you can see it in the preview mode. The preview uses default settings, style, and language. To see it, use the following URL with your own values for query parameters:
https://login-widget.xsolla.com/latest/?projectId={LOGIN_PROJECT_ID}&login_url={CALLBACK_URL}
You can also add the locale
query parameter to the URL. Possible values are available in the preferredLocale parameter.
Integrating widget 2.0
This library allows you to quickly integrate Xsolla Login widget with your website in following steps:
Step 1: Initializing widget 2.0
Add the widget initialization code to the <body>
tag.
<script>
const xl = new XsollaLogin.Widget({
projectId: '[Login ID]',
preferredLocale: 'en_US'
});
</script>
Version for npm
:
import { Widget } from '@xsolla/login-sdk';
const xl = new Widget({
projectId: '[Login ID]',
preferredLocale: 'en_US'
});
projectId
string
Login project ID from Publisher Account. Required.
callbackUrl
string
URL to redirect the user to after registration/authentication/password reset. Must be identical to one of the Callback URL specified in Publisher Account in Login settings. Required if there are several Callback URLs.
You can pass several URLs of the local server to make the widget available to the local build. For example https://localhost:9000
.
payload
string
Your custom data. The value of the parameter will be returned in the user JWT > payload
claim.
preferredLocale
string
Language of the widget interface and region in the <language code>_<country code>
format where:
- language code: language code in the ISO 639-1 format;
- country code: country/region code in the ISO 3166-1 alpha-2 format.
The following locales can be specified: Arabic (ar_AE), Bulgarian (bg_BG), Czech (cz_CZ), German (de_DE), Spanish (es_ES), French (fr_FR), Hebrew (he_IL), Italian (it_IT), Japanese (ja_JP), Korean (ko_KR), Polish (pl_PL), Portuguese (pt_BR), Romanian (ro_RO), Russian (ru_RU), Thai (th_TH), Turkish (tr_TR), Vietnamese (vi_VN), Chinese Simplified (zh_CN), Chinese Traditional (zh_TW).
Also used for sorting social networks by the frequency of use in the chosen region.
string
Widget background color in the fullscreen mode. The value can be in any of the CSS color formats. Default is RGBA(50, 150, 150, 0.1).
iframeZIndex
string
The stack order of the widget in the fullscreen mode. Default is 1000000.
Step 2: Choosing widget 2.0 placing
Choose the widget placing on the website start page:
Enabling fullscreen mode
Add the button with the on-click
event and the xl.show()
function to the site.
<div id="xl_auth" style="display: none"></div>
<button onclick="xl.open()">Fullscreen widget</button>
Add the code for inserting the widget into the block.
<script type="text/javascript">
xl.mount('xl_auth');
</script>
The fullscreen mode is closed by clicking outside the widget area.
Adding a block on the page
Add the block with the widget to the <body>
tag and set the block ID.
<div id="xl_auth" style="height: 700px"></div>
Add the code for inserting the widget into the block.
<script type="text/javascript">
xl.mount('xl_auth');
</script>
Using additional features
If you have already integrated Login, you can also try additional features of Xsolla Login Widget:
Customizing widget 2.0 style
By default, the widget looks like this:
Customize the widget style by changing the following parameters in Publisher Account:
- Roundness
- Text color
- Buttons color
- Background color
To customize:
-
Go to the Customization page in Publisher Account.
-
Move your mouse cursor to the editing area and click Customize. It will open the widget builder.
-
Set up the widget style and click Publish.
NOTE
After publication, the widget will be changed for all the projects it was connected to.
Tracking Widget 2.0 Events
You can collect widget statistics on the following events:
To start tracking the event, initialize and process the action as described below.
Opening widget 2.0
xl.on(xl.events.Open, function () {
console.log('user has opened the widget');
});
Closing widget 2.0
xl.on(xl.events.Close, function () {
console.log('user has closed the widget');
});
Connecting OAuth 2.0 protocol
Xsolla Login widget supports the OAuth 2.0 protocol-based user authentication. Follow the Connecting OAuth 2.0 instruction to set it up.
Opening widget 2.0 pages
You can open Xsolla Login widget on other pages, in addition to the authentication (Login) page. The following pages available to you include:
To open the page, initialize and process the action as described below.
Registration page
const pages = XsollaLogin.WidgetPages;
const page = pages.SignUpPage;
xl.setPage(page);
Social authentication page
const pages = XsollaLogin.WidgetPages;
const page = pages.SocialsPage;
xl.setPage(page);
Password reset page
const pages = XsollaLogin.WidgetPages;
const page = pages.ResetPasswordPage;
xl.setPage(page);
Integrating login API
To be able to use the Login SDK API methods without using a widget, it is possible to initialise in the following way:
Add the API initialization code to the <body>
tag.
<script>
const api = new XsollaLogin.Api({
projectId: '[Login ID]',
});
</script>
Version for npm
:
import { Api } from '@xsolla/login-sdk';
const api = new Api({
projectId: '[Login ID]',
});
The following properties may also be set during initialisation:
projectId
string
Login project ID from Publisher Account. Required.
callbackUrl
string
URL to redirect the user to after registration/authentication/password reset. Must be identical to one of the Callback URL specified in Publisher Account in Login settings. Required if there are several Callback URLs.
You can pass several URLs of the local server to make the widget available to the local build. For example https://localhost:9000
.
payload
string
Your custom data. The value of the parameter will be returned in the user JWT > payload
claim.
fullLocale
string
Language of the widget interface and region in the <language code>_<country code>
format where:
- language code: language code in the ISO 639-1 format;
- country code: country/region code in the ISO 3166-1 alpha-2 format.
The following locales can be specified: Arabic (ar_AE), Bulgarian (bg_BG), Czech (cz_CZ), German (de_DE), Spanish (es_ES), French (fr_FR), Hebrew (he_IL), Italian (it_IT), Japanese (ja_JP), Korean (ko_KR), Polish (pl_PL), Portuguese (pt_BR), Romanian (ro_RO), Russian (ru_RU), Thai (th_TH), Turkish (tr_TR), Vietnamese (vi_VN), Chinese Simplified (zh_CN), Chinese Traditional (zh_TW).
Also used for sorting social networks by the frequency of use in the chosen region.
emailTemplate
string
Used as the name of the project from which emails are sent.
with_logout
boolean
Allows previous tokens to be switched off during a new authorisation.
cdnUrl
string
The default setting is https://cdn.xsolla.net/login-widget/
.
theme
object (Theme)
Widget visual appearance settings.
clientId
string
Customer Id. Transmitted only in case of OAuth 2.0 authorization.
redirectUri
string
URL that the server will handle when authorisation or registration is successful via the OAuth 2.0 method..
responseType
string
Allows you to specify the API response type.
disableConfirmByLink
boolean
Allows you to disable passwordless email/phone number authentication confirmation via a link in an email.
is_oauth2
boolean
Allows you to select how the user is authenticated by OAuth 2.0.
List of API methods
The following are API methods that can be used without the use of a widget:
The properties that must be specified are marked with a *
.
fetchConfig:
Returns a promis in response with the actual object with the widget's global settings.
Also updates the API configuration which could have been set during initialization.
api.fetchConfig()
signup:
Used to register a new user.
let result
api.signup({
userInfo: {
email: "john-email@email.com",
fields: {
nickname: "Johny"
},
password: "password123",
username: "John"
}
}).then((res) => {
result = res;
})
result === {
login_url: "http://someurl.com?token=XXXXXXX"
}
login:
The method is used to authorise a user with a password.
let result
api.login({
credentials: {
password: "password123",
remember_me: false,
username: "John" или 'john@gmail.com'
}
}).then((res) => {
result = res;
})
result === {
ask_fields: [{
confirmation_type: "code" || "link"
name: "phone_number"
required: false
step: 0
type: "phone"
validation: {}
}]
login_url: "http://someurl.com?token=XXXXXXX",
token: "sometoken"
}
result === {
login_url: "http://someurl.com?token=XXXXXXX"
}
agreement:
Sends the European user's consent to the processing of their personal data, indicated on a special page.
let result
api.agreement({
token: 'sometoken',
isAccepted: true,
consentId: 'someid'
}).then((res) => {
result = res;
})
result === {
url: "https://www.someurl.com"
}
otpLogin:
Sends the European user's consent to the processing of their personal data, indicated on a special page.
let result
api.otpLogin({
code: 'sometoken',
remeber_me: false
}).then((res) => {
result = res;
})
result === {
url: "https://www.someurl.com"
}
otpResendCode:
Resets the old otp code.
api.otpResendCode()
resendEmail:
Re-sends an account confirmation email to the user.
To complete the account confirmation, the user must click on the link in the email.
api.resendEmail(
username: 'JohnLogin123@mail.com'
)
Methods and process for passwordless authorising
-
The user enters phone number / email and depending on the type of data entered calls the following methods:
api.phoneGetCode / api.emailGetCode
.
-
The server receives the sent data and sends a message to the phone number / email number with a code (optionally with a link if disableConfirmByLink
was not set to true during API initialization)
-
If link data validation process was enabled, use api.getConfirmCode
(see below) for auto-redirect after following the link.
-
api.phoneGetCode / api.emailGetCode
will return operation_id which will be required for phone number / email number validation.
-
The api.loginWithPhoneCode / api.loginWithEmailCode
methods are used to validate the phone number / email.
-
On successful phone number / email verification returns a URL with the token
as a parameter, which is used in requests for additional user data.
Methods:
phoneGetCode:
let result
api.phoneGetCode({
phone_number: '+somenumber',
link_url: 'https://someurl.com',
isOauth2: true
}).then((res) => {
result = res;
})
result === {
operation_id: '2334j255fdf13d515fgd1'
}
emailGetCode:
let result
api.emailGetCode({
email: 'somemail@gmail.com',
link_url: 'https://someurl.com',
isOauth2: true
}).then((res) => {
result = res;
})
result === {
operation_id: '2334j255fdf13d515fgd1'
}
loginWithPhoneCode:
let result
api.loginWithPhoneCode({
phone_number: 'somemail@gmail.com',
code: '3423',
operation_id: '334j255fdf13d515fgd1',
isOauth2: true
}).then((res) => {
result = res;
})
result === {
ask_fields: [{
confirmation_type: "code" || "link"
name: "email"
required: false
step: 0
type: "email"
validation: {}
}]
login_url: "http://someurl.com?token=XXXXXXX",
token: "sometoken"
}
result === {
login_url: "http://someurl.com?token=XXXXXXX"
}
loginWithEmailCode:
let result
api.loginWithEmailCode({
email: 'somemail@gmail.com',
code: '3423',
operation_id: '334j255fdf13d515fgd1',
isOauth2: true
}).then((res) => {
result = res;
})
result === {
ask_fields: [{
confirmation_type: "code" || "link"
name: "phone_number"
required: false
step: 0
type: "phone"
validation: {}
}]
login_url: "http://someurl.com?token=XXXXXXX",
token: "sometoken"
}
result === {
login_url: "http://someurl.com?token=XXXXXXX"
}
Methods and process for additionally passwordless field querying
-
The user enters phone number / email and depending on the type of data entered calls the following methods api.phoneGetCode / api.emailGetCode
.
-
The server receives the sent data and sends a message to the phone number / email with a code (optionally with a link if disableConfirmByLink
was not set to true during API initialization)
-
If link data validation is enabled, use api.getConfirmCode
(see below) for auto-redirect after following the link.
-
api.phoneGetCode / api.emailGetCode
will return operation_id
which will be required for phone number / email validation.
-
The api.loginWithPhoneCode / api.loginWithEmailCode
methods are used to validate the phone number / email.
Methods:
ask:
A method of data preprocessing that is used after authorisation and, depending on PA settings, allows additional data, such as phone number / email, to be sent.
let result
api.ask({
fields: {
phone_number: "+somenumber"
email: "example@gmail.com"
},
link_url: 'https://someurl.com',
token: 'sometoken'
}).then((res) => {
result = res;
})
result === {
error: {
code: "003-014"
description: "Confirm phone number."
details: { operation_id: "BPaBScLM44GesoOYSxT5I8QfgIrTSURd" }
}
}
result === {
error: {
code: "003-011"
description: "Confirm email."
details: { operation_id: "BPaBScLM44GesoOYSxT5I8QfgIrTSURd" }
}
}
result === {
redirect_url: "<login_url>?token=<token>"
}
getAskFields:
A method that allows you to request the additional fields that are required by the PA settings.
let result
api.getAskFields({
token: 'sometoken'
}).then((res) => {
result = res;
})
result === [
{
confirmation_type: "code" || "link"
name: "phone_number" || "email"
required: false
step: 0
type: "phone" || "email"
validation: {}
}
]
getConfirmCode:
A method which is required if the PA has been selected to prompt for mail retrieval via a link or if the disableConfirmByLink
property was not set to true during widget initialization. It sends a long pooling request that waits for a link from an email sent to the email / phone number. This method uses cancel token to terminate the request prematurely.
let result
const axiosCancelToken = Axios.CancelToken.source();
api.getConfirmCode({
cancelToken: axiosCancelToken,
login: '+343423425252' || 'example@gmail.com'
operation_id: '334j255fdf13d515fgd1',
}).then((res) => {
result = res;
})
result === {
code: "string"
}
result === {
error: {
code: "010-050",
description: "Deadline exceeded."
}
}
axiosCancelToken.cancel();
Methods and process for resetting the password
-
The application opens a form where the user can enter their email address or username.
-
The user enters their email address or username using api.reset
.
-
The server sends the user a confirmation email.
-
The user clicks the link in the email and is taken to a form to set a new password.
-
The user enters the new password and uses api.set
method.
Methods:
reset:
Resets the password of the user specified in username with user confirmation.
api.reset({
username: 'john'
}).then((res) => {
res.code === 204;
})
set:
A confirmation method for resetting the user's password. Resetting the password has a little flow to follow:
api.set({
new_password: 'newpass',
reset_code: '3423',
user_id: '324324234'
}).then((res) => {
res.code === 204;
})