How to connect JSON with widget settings

The widget settings are contained in the following JSON files:

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:

Copy
Full screen
Small screen
<script>
const xl = new XsollaLogin.Widget({
  // Other settings
  settingsJSON: "url_string",
  socialsJSON: "url_string",
  themeJSON: "url_string"
});
</script>

Main settings

The main widget settings are:

The template of the settingsJSON file:

Copy
Full screen
Small screen
{
  "authorization_methods": {
    // Authorization methods
  },
  "registration_fields": {
    // Registration fields
  },
  "email_validation": {
    // Settings for email validation
  }

  // Other widget settings
}

Authorization methods

The authorization_methods object contains an array with available authorization methods. The login page is displayed according to the passed settings.

Note
At least one method should be passed to the array. Every method cannot be represented in an array more than once.

Available authorization methods:

  • email — authorization by an email address and password. The parameter is passed by default if there is no authorization_methods object with a definite list of methods.
  • social — social login. The parameter is passed by default if there is no authorization_methods object with a definite list of methods.
  • username — authorization by a username and password.
  • phone — authorization by the phone number and an SMS code.
  • passwordless-email-code — authorization by an email address and a code sent in an email.

Example:

Copy
Full screen
Small screen
{
  "authorization_methods": {
    ["email", "phone"]
  }

  // Other widget settings
}

Registration fields

The registration_fields object contains an array of fields that are displayed on the registration page of the widget.

ParameterTypeDescription
email
emailUser email address.
username
stringUser account.
password
passPassword.
password_confirm
passPassword confirmation.
given-name
stringUser name.
family-name
stringUser family name.
nickname
stringUser nickname.
bday
dateBirthdate.
gender
stringGender.
country-name
selectCountry.
platform
multi-selectPlatform.
promo_email_agreement
booleanConsent to receive promo materials.
Note
The array must contain at least one field. The fields are displayed according to the order in which they are passed to the array.

Additionally, you can specify the following parameters to a field:

  • required (boolean) — whether the field is required.
  • default_value (array) — an array of default values (for a list of countries or platforms).
  • validation (object) — validation parameters:
    • allowed_characters (string) — allowed characters for the field. Separated by a comma in the list as the regular expression values.
    • max_length (number) — maximum number of characters.
    • min_length (number) — minimum number of characters.
    • regexps (array with strings) — a regular expression for validating the entered value.

Example:

Copy
Full screen
Small screen
{
  // Other widget settings

  "registration_fields": [
    {
      "name": "username",
      "required": false,
      "type": "str",
      "validation": {
        "allowed_characters": "A-Z, a-z, 0-9",
        "max_length": 16,
        "min_length": 5,
        "regexps": ["^.{5,16}$"]
      }
    },
    { "name": "email", "required": true, "type": "email", "validation": {} },
    { "name": "bday", "required": true, "type": "date", "validation": {} },
    {
      "name": "platform",
      "default_value": ["MacOS", "Nintendo Switch", "Steam"],
      "required": false,
      "type": "multi-select",
      "validation": {}
    },
    {
      "name": "country-name",
      "default_value": ["US", "GB", "DE"],
      "required": false,
      "type": "select",
      "validation": {}
    },
    { "name": "password", "required": true, "type": "pass", "validation": {} },
    {
      "name": "password_confirm",
      "required": false,
      "type": "pass",
      "validation": {}
    },
    {
      "name": "promo_email_agreement",
      "required": false,
      "type": "bool",
      "validation": {}
    }
  ]
}

Email address validation

The email_validation object contains the se_xsolla_email_validator parameter that validates data entered in the email field.

ParameterTypeDescription
use_xsolla_email_validator
booleanWhether to use the additional validation of data entered in the email field. If true, an email address is validated on the front-end and back-end sides with features like SMTP, RFC, and Greylist. If false, the email address is validated on the front-end side only. false by default.

Example:

Copy
Full screen
Small screen
{
  // Other widget settings

  "email_validation": {
    "use_xsolla_email_validator": true
  }
}

Additional settings

Additional settings are passed in the JSON object root of the settingsJSON file.

ParameterTypeDescription
can_register
booleanWhether to enable registration for users. true by default.
can_reset_password
booleanWhether to enable password reset for users. true by default.
stringLink to the user policy consent.
stringLink to the cookie policy.
privacy_policy
stringLink to the privacy policy.
tos_url
stringLink to the terms of use.
game_name
stringName of a project or game. Displayed in some authorization methods.

Example:

Copy
Full screen
Small screen
{{
  // Other widget settings

  "can_register": true,
  "can_reset_password": true,
  "cookie_policy": "https://someurl.com"
}

Social networks settings

For social login, the following parameters are passed in the socialsJSON file:

  • list of regions
  • parameters and types of social networks for every region

The template of the socialsJSON file:

Copy
Full screen
Small screen
{
  "1": {
    "primary": [
      // Array of social networks for primary type
    ],
    "secondary": [
      // Array of social networks for secondary type
    ]
  },
  "2": {
    "primary": [
      // Array of social networks for primary type
    ],
    "secondary": [
      // Array of social networks for secondary type
    ]
  },
  "3": {
    "primary": [
      // Array of social networks for primary type
    ],
    "secondary": [
      // Array of social networks for secondary type
    ]
  },
  "4": {
    "primary": [
      // Array of social networks for primary type
    ],
    "secondary": [
      // Array of social networks for secondary type
    ]
  },
  "5": {
    "primary": [
      // Array of social networks for primary type
    ],
    "secondary": [
      // Array of social networks for secondary type
    ]
  },
  "6": {
    "primary": [
      // Array of social networks for primary type
    ],
    "secondary": [
      // Array of social networks for secondary type
    ]
  }
}

Every region has a number:

  • 1 — Europe
  • 2 — China
  • 3 — North and South Korea
  • 4 — CIS
  • 5 — North and South America
  • 6 — the rest of the world

The type of a social network is defined for every region. There are 2 types of social networks: primary (primary) and secondary (secondary). The primary social networks are displayed as a big button and are more visible on the widget page. The secondary social networks are displayed as small buttons and are less visible.

Every type of a social network contains an array of objects:

ParameterTypeDescription
name
stringName of a social network. Available options: amazon, apple, baidu, battlenet, china_telecom, discord, email, epicgames, facebook, github, google, google-plus, instagram, kakao, linkedin, mailru, microsoft, msn, naver, ok, paradox, paypal, pinterest, qq, reddit, steam, slack, twitch, twitter, vimeo, vk, wechat, weibo, xbox, yahoo, yandex, youtube.
jwt
stringLink for opening a social network if the JWT authorization is used.
oauth2
stringLink for opening a social network if the OAuth 2.0 protocol-based authorization is used.
Note
Every social network should be represented in an array at least once. The array can be empty.

Example:

Copy
Full screen
Small screen
{
  "1": {
    "primary": [{
      "name": "google",
      "jwt": "https://login.xsolla.com/api/social/google/login_redirect",
      "oauth2": "https://login.xsolla.com/api/oauth2/social/google/login_redirect"
    }],
    "secondary": [{
        "name": "facebook",
        "jwt": "https://login.xsolla.com/api/social/facebook/login_redirect",
        "oauth2": "https://login.xsolla.com/api/oauth2/social/facebook/login_redirect"
      },
      {
        "name": "twitter",
        "jwt": "https://login.xsolla.com/api/social/twitter/login_redirect",
        "oauth2": "https://login.xsolla.com/api/oauth2/social/twitter/login_redirect"
      }
    ]
  },
  "2": {
    "primary": [{
      "name": "wechat",
      "jwt": "https://login.xsolla.com/api/social/wechat/login_redirect",
      "oauth2": "https://login.xsolla.com/api/oauth2/social/wechat/login_redirect"
    }],
    "secondary": [{
        "name": "facebook",
        "jwt": "https://login.xsolla.com/api/social/facebook/login_redirect",
        "oauth2": "https://login.xsolla.com/api/oauth2/social/facebook/login_redirect"
      },
      {
        "name": "twitter",
        "jwt": "https://login.xsolla.com/api/social/twitter/login_redirect",
        "oauth2": "https://login.xsolla.com/api/oauth2/social/twitter/login_redirect"
      },
      {
        "name": "steam",
        "jwt": "https://login.xsolla.com/api/social/steam/login_redirect",
        "oauth2": "https://login.xsolla.com/api/oauth2/social/steam/login_redirect"
      }
    ]
  }

  // More regions
}

Theme settings

The widget theme settings include:

  • widget color and size settings
  • rounding settings (the rounding object)
  • widget background settings (the background object)
  • header settings (the header object)
  • widget tabs settings (the tabs object)
  • social networks display settings (the primary_socials and secondary_socials objects)
  • scene settings (the scene object)
  • The template of the themeJSON file:

    Copy
    Full screen
    Small screen
    {
      // Color and size settings
    
      "header": {
        // Header settings
      },
      "background": {
        // Widget background settings
      },
      "rounding": {
        // Rounding settings
      },
      "tabs": {
        // Tab settings
      },
      "primary_socials": {
        // Display settings for the primary social networks
      },
      "secondary_socials": {
        // Display settings for the secondary social networks
      },
      "scene": {
        // Scene settings
      }
    }

    Widget color and size

    The color and size of the widget are passed in the JSON object root of the themeJSON file.

    ParameterTypeDescription
    primary_color
    stringPrimary widget color (color of buttons and active input fields borders) in the RGB or HEX format. Default value is #0073F7.
    secondary_color
    stringSecondary widget color (color of inactive input fields) in the RGB or HEX format. Default value is #DADADA.
    error_color
    stringError texts color in the RGB or HEX format. Default value is #EB002F.
    text_color
    stringMain text color in the RGB or HEX format. Default value is #000000.

    Example:

    Copy
    Full screen
    Small screen
    {
      // Other theme settings
    
      "primary_color": "#708090",
      "secondary_color": "#4682B4"
    }

    Rounding

    The rounding object contains parameters of rounding for different widget elements. The property applies to all four corners simultaneously.

    ParameterTypeDescription
    inputs
    stringRounding in pixels for active fields. Default value is 6px.
    buttons
    stringRounding in pixels for buttons. Default value is 100px.
    widget
    stringRounding in pixels for the widget. Default value is 6px.

    Example:

    Copy
    Full screen
    Small screen
    {
      // Other theme settings
    
      "rounding": {
        "inputs": "8px",
        "widget": "8px"
    
      }
    }

    Background

    The background object contains the widget background parameters.

    ParameterTypeDescription
    color
    stringBackground color in the RGB or HEX format. Default value is #FFFFFF.
    image
    objectBackground image. The object contains a link to the image and opacity settings. The default opacity value is 1.

    Example:

    Copy
    Full screen
    Small screen
    {
      // Other theme settings
    
      "background": {
        "color": "#708090",
        "image": {
          "url": "https://someurl.com",
          "opacity": "3"
        }
      }
    }

    Header

    The header object contains the parameters of the widget header — an area above all widget fields.

    ParameterTypeDescription
    image
    objectHeader background image. The object contains a link to the image, opacity settings, and the background image size. The default opacity value is 1.
    Available values of the background image size correspond with the values of the background-size CSS property (cover by default).

    Example:

    Copy
    Full screen
    Small screen
    {
      // Other theme settings
    
      "header": {
        "image": {
          "url": "https://someurl.com",
          "opacity": "3",
          "size": "cover"
        }
      }
    }

    Tabs

    The tabs object contains a hide parameter. This parameter manages the display of registration or authorization tabs on the widget.

    ParameterTypeDescription
    hide
    booleanWhether to hide the authorization or registration tabs on a widget. Use the true value to, for example, temporarily hide the registration tab or display registration and authorization pages separately. Default value is false.

    Example:

    Copy
    Full screen
    Small screen
    {
      // Other theme settings
    
      "tabs": {
        "hide": true
      }
    }

    Social networks display

    The primary_socials and secondary_socials objects contain the hide parameter that manages the display of primary and secondary social networks on a widget.

    ParameterTypeDescription
    hide
    booleanWhether to hide social networks. Default value is false.

    Example:

    Copy
    Full screen
    Small screen
    {
      // Other theme settings
    
      "primary_socials": {
        "hide": true
      },
      "secondary_socials": {
        "hide": false
      }
    }

    Scene

    The scene object contains parameters for a scene — an area around the widget.

    ParameterTypeDescription
    color
    stringBackground color in the RGB or HEX format. Default value is #FFFFFF.
    image
    objectBackground image. The object contains a link to the image, opacity settings, and the background image size. Available values of the background image size correspond with the values of the background-size CSS property (cover by default).

    Example:

    Copy
    Full screen
    Small screen
    {
      // Other theme settings
    
      "scene": {
        "color": "#708090",
        "image": {
          "url": "https://someurl.com",
          "size": "cover"
        }
      }
    }

    Was this article helpful?
    Thank you!
    Is there anything we can improve? Message
    We’re sorry to hear that
    Please explain why this article wasn’t helpful to you. Message
    Thank you for your feedback!
    We’ll review your message and use it to help us improve your experience.
    Rate this page
    Rate this page
    Is there anything we can improve?

    Don’t want to answer

    Thank you for your feedback!
    Last updated: September 29, 2021

    Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!