OAuth 2.0 uses short-lived tokens with long-term authorization (refresh tokens) instead of long-lived tokens. A refresh token allows users to stay in your application for an extended period of time without needing to re-enter their username and password. This eliminates the risk of compromising user authentication data.

Set up OAuth 2.0 for authorization:

• via username or email and password
• via social networks

If this option is enabled, user registration and authentication is carried out by calling the Register a new user and JWT auth by username and password API methods. The Login Android SDK provides the same methods for OAuth 2.0 authorization as for JWT token authorization.

To configure OAuth 2.0 authorization:

1. Set up OAuth 2.0 authentication for Login project in your Publisher Account.
2. Initialize the library.

Set up OAuth 2.0 authentication for Login project in your Publisher Account

1. Go to your Publisher Account.
2. Click Open in the Login block and go to Login projects.
3. Click Open and set up in the Login project block.
4. Go to General settings > Authorization.
5. Click Connect in the OAuth 2.0 authentication block.
6. Specify OAuth 2.0 redirect URIs and click Connect.
7. Copy and save the Client ID.

Initialize the library

To initialize the library, add the following line to your Android project source code, specifying the following parameters:

• login-project-id — Login ID found in Publisher Account > Login settings > Login ID.
• oauth2-client-id — Client ID received when setting up OAuth 2.0 in Publisher Account.

val loginConfig = LoginConfig.OauthBuilder()
                .setProjectId("login-project-id")
                .setOauthClientId("oauth2-client-id")
                .build()

XLogin.init(applicationContext, loginConfig)

The following methods are implemented in Login Android SDK to work with refresh tokens:

• XLogin.refreshToken — refreshes the token.
• XLogin.getToken — returns the current token.
• XLogin.isTokenExpired — returns true if the token is expired.

Native authentication allows players to log in to your application via installed applications that use social network accounts. Currently, Android SDK has implemented native authentication via the following social networks:

• Google
• Facebook

To configure native authentication:

1. For native authentication via Facebook, create your Facebook developer account and a new app.
2. Set up the application page in your Facebook developer account.
3. For native authentication via Google, set up the project in Google API Console.
4. Set up social networks for the Login project in your Publisher Account.
5. Open build.gradle file of your application and add the following lines to the dependencies section where <version_number> is the required version of the Android SDK:

implementation 'com.xsolla.android:login-facebook:<version_number>'
implementation 'com.xsolla.android:login-google:<version_number>'

6. Initialize the Login library with the following parameters:
   • facebook_id — App ID from the Facebook developer account.
   • google_id — Client ID for web application from the Google API Console.

val loginConfig = LoginConfig.JwtBuilder()
                .setProjectId("login-project-id")
                .setCallbackUrl("your-callback-url")
                .setSocialConfig(XLogin.SocialConfig(facebookAppId = "facebook_id", googleServerId =  "google_id"))
                .build()

XLogin.init(applicationContext, loginConfig)

// OR

val loginConfig = LoginConfig.OauthBuilder()
                .setProjectId("login-project-id")
                .setOauthClientId("oauth2-client-id")
                .setCallbackUrl("your-callback-url")
                .setSocialConfig(XLogin.SocialConfig(facebookAppId = "facebook_id", googleServerId =  "google_id"))
                .build()

XLogin.init(applicationContext, loginConfig)

Set up application page in your Facebook developer account

1. Go to project settings in the Facebook developer account.
2. Go to Settings > Basic.
3. Click Add Platform and select Android.
4. Specify the Package name of your Android app for the Google Play Package Name.
5. Specify a fully qualified class name of the default Activity for Class Name.
6. Generate a hash key and specify it as a Key Hashes.
7. Click Save Changes.

For further native authentication configuration, you will need App ID and App Secret found in project settings in Settings > Basic section.

Set up project in Google API Console

1. Go to Google API Console.
2. Click New Project.
3. Specify Project name and Location and click Save.
4. Go to the created project and click OAuth consent screen in the side menu.
5. Select External option and click Create.
6. Specify the necessary parameters and click Save.
7. Click Credentials in the side menu.
8. Create an OAuth 2.0 client for your Android app:
   1. Click Create credentials and select OAuth client ID.
   2. Specify Android as the Application type.
   3. Specify Name.
   4. Specify Package name of your Android app as a Package name.
   5. Get the SHA-key.
   6. Specify SHA-key generated in the previous step SHA-key as a SHA-1 certificate fingerprint.
   7. Click Create.
   8. Click OK.
9. Create an OAuth 2.0 client for the web application:
   1. Click Create credentials and select OAuth client ID.
   2. Specify Web application as the Application type.
   3. Specify Name.
   4. Click Add URI in the Authorized redirect URIs section and specify https://login.xsolla.com/api/social/oauth2/callback URI.
   5. Click Create.
   6. Click OK.

For further native authentication configuration, you will need Client ID and Client Secret found in settings of the Client ID for the web application.

Set up social networks for Login project in your Xsolla Publisher Account

1. Go to your Publisher Account.
2. Click Open in the Login block and go to Login projects.
3. Click Open and set up in the Login project block.
4. Go to Social connections.
5. To set up authentication via Facebook:
   1. Click Edit in the Facebook block and change status to Disconnected.
   2. Specify the App ID from the Facebook developer account as Application ID.
   3. Specify App Secret from the Facebook developer account as Application Secret.
   4. Click Connect.
6. To set up authentication via Google:
   1. Click Edit in the Google block and change status to Disconnected.
   2. Specify the Client ID for a web application from the Google API Console as Application ID.
   3. Specify the Client Secret for a web application from the Google API Console as Application Secret.
   4. Click Connect.

Token invalidation allows for improved security of user authentication data in your application. If the option is enabled, a new token replaces the old one that becomes invalid every time the user authenticates.

When using the Login Unity SDK, invalidation of the existing token and generation of a new one is made by calling Auth by username and password and Auth via social network API methods, if the with_logout parameter has the 1 value.

To use token invalidation in your Android project, you need to pass the withLogout = true parameter in the XLogin.authenticate, XLogin.startSocialAuth, and XLogin.finishSocialAuth methods.

You can use attributes to manage additional information about the users of your application. The user attribute is a key-value pair. The Login SDK supports the following types of attributes:

• User-editable attributes. The values for this type of attributes are entered by a user or specified according to the in-game logics on the client side. For example: the name and character stats, game difficulty level, etc.

• Read-only attributes. The values for this type of attributes are entered and edited on the server side of your application. We recommend you use them for configuration of game character stats or user parameters that shouldn’t be changed a lot. For example: use them for the chance to get a bonus, game character key parameters, user categories, etc.

To manage user attributes, use the following SDK methods:

• XLogin.getUsersAttributesFromClient — gets a list of attributes for a specific user. Get user’s attributes from client and Get user’s read-only attributes from client API methods are used alongside the SDK method.
• XLogin.updateUsersAttributesFromClient — updates and creates attributes of a specific user. The Update user’s attributes from client API method is used alongside the SDK method.

When working with read-only attributes, you can use a server token or a Publisher Account token for authorization.

To get the Publisher Account token:

1. Enter your Publisher Account.
2. Go to the cookie files viewpage via the developers’ tools in your browser.
3. Copy the value from the pa-v4-token parameter and paste it to the Authorization header.

Users can configure the following data from a user account:

• public profile data:
  • avatar
  • nickname

• personal user data:
  • name and surname
  • birthdate
  • gender
  • phone number
  • email

You can manage the user account via the API methods. The Login Android SDK has the following methods implemented:

• XLogin.getCurrentUserDetails — gets the user’s data.
• XLogin.updateCurrentUserDetails — updates the user’s data.

• XLogin.getCurrentUserEmail — gets the user’s email address.
• XLogin.getCurrentUserPhone — gets the user’s phone number.
• XLogin.updateCurrentUserPhone — updates the user’s phone number.
• XLogin.deleteCurrentUserPhone — deletes the user’s phone number.
• XLogin.uploadCurrentUserAvatar — changes the user’s avatar.
• XLogin.deleteCurrentUserAvatar — deletes the user’s avatar.

You can see the examples of the method calls in the demo project.

The friend system allows your users to find each other and set up social connections. The SDK supports the following functionality:

• search by nickname
• get the list of friends from social networks
• manage the friend list, send invitations, add and remove friends, block users, etc.
• manage personal data via the user account

To implement the friend system, you should have the user account functionality in your application. Methods of working with this system use the following parameters from the user account:

• user ID
• avatar
• nickname

Users should specify the nickname to ensure the friend system works correctly. Implement the following nickname specification logics:

• Use the name that was used for registration via login and password as a nickname.
• Implement the nickname request during social authentication or platform accounts.

SDK methods

The Login Android SDK has the following methods of working with the friend system:

• XLogin.getCurrentUserFriends — updates the locally cached user friends data. The Get friends API method is used alongside the SDK method.

• XLogin.updateCurrentUserFriend — updates the status of the user’s social connections. The Update friends API method is used alongside the SDK method. The social connections status is affected by the following actions:
  • send or cancel a friend request
  • accept or decline a friend request
  • delete the user from the friend list
  • block or unblock the user

• XLogin.updateCurrentUserFriend — updates the status of the user’s social connections. The Update friends API method is used alongside the SDK method. The social connections status is affected by the following actions:
  • send or cancel a friend request
  • accept or decline a friend request
  • delete the user from the friend list
  • block or unblock the user

• XLogin.getSocialFriends — updates the locally cached data of user’s friends from a social network. The Get user’s friends API method is used alongside the SDK method.

• XLogin.getUserPublicInfo — gets data from the user’s public profile. The Get user public profile API method is used alongside the SDK method.

• XLogin.searchUsersByNickname — searches for the user by nickname. The Search users by nickname API method is used alongside the SDK method.

• XLogin.startSocialAccountLinking — generates an intent to open a social network authorization window to link an account to a user account. The Link social network to user's account API method is used alongside the SDK method.

Implementing a friends system for social networks

To let users interact with friends from social networks in your application, configure the storage of friend data on the Xsolla side:

1. Go to your Publisher Account.
2. Click Open in the Login block and go to Login projects.
3. Click Open and set up in the Login project block.
4. Go to General settings > Authentication.
5. Set the Store friends from social networks toggle to On.
6. Save changes.

To make friends from the social network available to the player in the application, implement the following logic in your application:

1. Link a social network to a player's account using the XLogin.createSocialAccountLinkingIntent method.

Example:

startActivityForResult(
         XLogin.createSocialAccountLinkingIntent(context, socialNetwork),
         RC_LINKING
 )

2. Update your friends list using the XLogin.updateSocialFriends method. The Update user’s friend API method is used alongside the SDK method.
3. Get a list of friends from a linked social network using the XLogin.getSocialFriends method. The Get user’s friends API method is used alongside the SDK method.

You can return users to your application after they pay for in-game purchases via an external browser. To do this, set up deep links:

1. Go to Xsolla Publisher Account.
2. Go to your project and click Open in the Pay Station block.
3. Go to Settings.
4. Specify the required parameters in the Redirect policy section and click Save.
5. Add the Return URL configured in Publisher Account to the strings.xml file of application module as shown in the example. An example is given for a Return URL with the value myapp://example.com/payment.

<string name="xsolla_payments_redirect_scheme">myapp</string>
<string name="xsolla_payments_redirect_host">example.com</string>
<string name="xsolla_payments_redirect_path_prefix">/payment</string>

To get new users to your application and increase sales, you can implement coupon promotions. When redeeming a coupon, the user may receive one of the following rewards:

• virtual currency package
• game key
• virtual item

For details on the features and limitations of coupon promotions, see the In-Game Store guide.

To work with coupon promotions:

1. Complete the settings in Publisher Account following to the instructions for setting up promotional campaigns with coupons.
2. Implement in-game logic using the following SDK methods:

• XStore.getCouponRewardsByCode — gets a list of items that can be credited to the user when the coupon is redeemed. The Get coupon rewards API method is used alongside the SDK method.
• XStore.redeemCoupon — redeems the coupon code and rewards the user. The Redeem coupon code API method is used alongside the SDK method.

To get new users to your application and increase sales, you can implement a campaign with promo codes. When redeeming a promo code, the user may receive one or more of the following rewards:

• discount that applies to the user’s cart
• bonus items:
  • virtual currency package
  • game key
  • virtual item including a bundle or nonrenewing subscription

For details on the features and limitations of campaigns with promo codes, see the In-Game Store guide.

To work with promo codes:

1. Complete the settings in Publisher Account by following the instructions for setting up a campaign with promo codes.
2. Implement in-game logic using the following SDK methods:

• XStore.getPromocodeRewardsByCode — gets promo code rewards. Allows users to choose one of many items as a bonus. The Get promo code reward API endpoint is used alongside the SDK method.
• XStore.redeemPromocode — redeems promo code. After redeeming a promo code, the user gets free items and/or the price of the cart is decreased. The Redeem promo code API endpoint is used alongside the SDK method.

To get new users to your application and increase sales, you can sell sets of items as bundles for less than the cost of their content.

A bundle may include:

• virtual currency (including the platform-dependent currency)
• package of virtual currency
• game keys for preselected DRMs
• virtual items including nonrenewing subscriptions
• bundles

For details on the features and limitations of bundles, see the In-Game Store guide.

To work with bundles:

1. Complete the settings in Publisher Account by following the instructions for setting up a bundle.
2. Implement in-game logic using the following SDK methods:

• XStore.getBundleList — gets a list of bundles for building a catalog. The Get list of bundles API endpoint is used alongside the SDK method.
• XStore.getBundle — gets a bundle for the specified SKU. The Get specified bundle API endpoint is used alongside the SDK method.

You can integrate Store Android SDK, Payments Android SDK and Inventory Android SDK with your own login system. To do so, you need to implement user authentication in your application via Pay Station access token. See the authentication algorithm in the In-Game Store documentation.

Implement the following logic in your application:

1. On the back-end of your application, implement a method to receive the Pay Station access token using an HTTP POST request. Xsolla API uses basic HTTP authentication. Enter your Merchant ID as a username and API key as a password.

HTTP request:

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Learn more about obtaining a token in the Pay Station documentation.

2. Pass the received Pay Station access token to the XStore.init method.
3. Implement the logic of receiving a new Pay Station access token after its expiration. It is recommended that you get a new token in the background mode, so the user doesn’t have to log in to the application again.

Implement the sale of virtual items and virtual currency outside the game via the in-game store site. The purchased items and currency will be available in the player's inventory.

To integrate your store site with the SDK:

1. Create a store site.
2. Specify the site address of the in-game store in the application code.
3. Implement the logic for your application to work with the store site.

Create a store site

You can create a store site with Site Builder by following the instructions for connecting a store on the site.

If you want to connect a store site that was created using a different solution, follow the instructions for creating a store.

Recommendations for the logic for your application to work with the store site

Follow these recommendations when developing your application:

1. Synchronize the fields of user registration and authorization in your application and in the Login widget on the store site:
   • If a user email and password are used for registration and authorization, set the username equal to the email in the application.

• If you use a username, user email and password for registration and authorization, contact your Account Manager to change the Login widget fields.

2. When navigating to the store site from the application client, implement pass-through user authorization. To do this, the user token must be passed in the URL parameters. An example of authorization is shown in the demo app.