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:

- Connecting SDK
- Widget 2.0 preview
- Integrating widget 2.0
- Step 1: Initializing widget 2.0
- Step 2: Choosing widget 2.0 placing
- Enabling fullscreen mode
- Adding a block on the page
- Using additional features
- Customizing widget 2.0 style
- Tracking widget 2.0 events
- Opening widget 2.0
- Closing widget 2.0
- Connecting OAuth 2.0 protocol
- Opening widget 2.0 pages
- Registration page
- Social authentication page
- Password reset page
- Login
- Integrating login API
- Connecting JSON with widget settings

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
``shell script
npm i @xsolla/login-sdk
`
* If the package is not connected, add the following code to the tag of the HTML-page where the widget will be placed:
`html

`

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:

`http request
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:
- Initializing widget 2.0
- Choosing widget 2.0 placing

$3

Add the widget initialization code to the tag.
`html

`

Version for npm:
`js
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 _ 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 (cs_CZ), German (de_DE), Spanish (es_ES), French (fr_FR), Hebrew (he_IL), Indonesian (id_ID), Italian (it_IT), Japanese (ja_JP), Khmer (km_KM), Korean (ko_KR), Lao (lo_LO), Burmese (my_MY), Nepali (ne_NE), Filipino (ph_PH), 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), Tagalok (ph_XX), Nepali (ne_XX), Burmese (my_XX), Lao (lo_XX), Khmer (km_XX), Indonesian (id_XX)
Also used for sorting social networks by the frequency of use in the chosen region.

------------------------------------------------------------------
###### popupBackgroundColor
     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 9000.

--------------------------------------------------------------------------------

$3

Choose the widget placing on the website start page:
- Enabling fullscreen mode
- Adding a block on the page

#### Enabling fullscreen mode

Add the button with the on-click event and the xl.open() function to the site.

`html



Fullscreen widget
`

Add the code for inserting the widget into the block.
!! Please use the same id for both div & querySelector !!

`html

`

Version for npm:
`js
xl.mount('xl_auth');

const showFullscreen = () => {
const myDiv = document.querySelector('#xl_auth');
myDiv.style.display = 'block';

xl.open();
}
`

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 tag and set the block ID.
`html



`

Add the code for inserting the widget into the block.
`html

`

Version for npm:
`js
xl.mount('xl_auth');
`

Using additional features

If you have already integrated Login, you can also try additional features of Xsolla Login widget:
- Babka Login Popup on a new window
- Customizing widget 2.0 style
- Tracking widget 2.0 events
- Connecting OAuth 2.0 protocol
- Prioritize Apple ID social login
- Opening widget 2.0 pages




$3

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:
1. Go to the Customization page in Publisher Account.
2. Move your mouse cursor to the editing area and click Customize. It will open the widget builder.


3. Set up the widget style and click Publish.


---
NOTE

After publication, the widget will be changed for all the projects it was connected to.

---

$3

You can collect widget statistics on the following events:
- Opening widget 2.0
- Closing widget 2.0
- Size changing

To start tracking the event, initialize and process the action as described below.

#### Opening widget 2.0

`js
xl.on(xl.events.Open, function () {
console.log('user has opened the widget');
});
`

#### Closing widget 2.0

`js
xl.on(xl.events.Close, function () {
console.log('user has closed the widget');
});
`

#### Widget 2.0 size changing

`js
xl.on(xl.events.Dimensions, function(e) {
// Event will contain height and width data in pixels
const { height, width } = e.dimensions;
console.log('Height: ', height);
console.log('Width: ', width);
})
`

If you would like to change your container based on these values,
we also recommend to add CSS transitions
to make resizing smoother.

`css
.widget-container {
transition: height 300ms ease-out 0s;
}
`

$3

Xsolla Login widget supports the OAuth 2.0 protocol-based user authentication. Follow the Connecting OAuth 2.0 instruction to set it up.

$3

You can show Apple ID social login option at the first position by enabling the parameter below:

`js
import { Widget } from '@xsolla/login-sdk';
const xl = new Widget({
appleIdPriority: true
});
`

$3

You can open Xsolla Login widget on other pages, in addition to the authentication (Login) page.

There are two ways of opening Login widget page:
1. Before initializing - Login widget will open a selected page instead of Login page (default)
2. After initializing - Login widget will switch current page to the selected page. Login widget must be already initialized.

The following pages are available:
* Registration
* Social authentication
* Password reset
* Login

#### Registration page

Before the widget initialization:
`js
const pages = XsollaLogin.WidgetPages;

const xl = new XsollaLogin.Widget({
// Other settings
page: pages.SignUpPage
});
`

After the widget initialization:
`js
const pages = XsollaLogin.WidgetPages;
const page = pages.SignUpPage;
xl.setPage(page);
`

#### Social authentication page

Before the widget initialization:
`js
const pages = XsollaLogin.WidgetPages;

const xl = new XsollaLogin.Widget({
// Other settings
page: pages.SocialsPage
});
`

After the widget initilization:
`js
const pages = XsollaLogin.WidgetPages;
const page = pages.SocialsPage;
xl.setPage(page);
`

#### Password reset page

Before the widget initialization:
`js
const pages = XsollaLogin.WidgetPages;

const xl = new XsollaLogin.Widget({
// Other settings
page: pages.ResetPasswordPage
});
`

After the widget initilization:
`js
const pages = XsollaLogin.WidgetPages;
const page = pages.ResetPasswordPage;
xl.setPage(page);
`

#### Login page

Before the widget initilization: no action required, since it is a default page.

After the widget initilization:
`js
const pages = XsollaLogin.WidgetPages;
const page = pages.LogInPage;
xl.setPage(page);
`


Integrating login API

You can work with the Login widget SDK API calls separately from the Login widget if you want to:
* use your own widget design
* partly implement the Login widget flow

Detailed information is provided in the instruction.

Connecting JSON with widget settings

The widget settings are contained in the following JSON files:

* settingsJSON — main settings
* socialsJSON — social login settings
* themeJSON` — theme settings

You can reuse the settings in the files and display the same widget on different settings. The settings URL is specified in the widget initialization code. To connect JSON with widget settings, follow the instruction.