Item catalog personalization

This tutorial shows how to:

• personalize the catalog using attributes created on your side (for partners who use the Pay Station Access Token to authorize users)
• specify the attribute validation rules in JSON schema and add attributes to the user on the Xsolla side (for partners who use the Xsolla Login to authorize users)
• create catalog display rule
• get the item catalog for a user with different attributes values

Prerequisites

Before you start, make sure that:

• You created a catalog of in-game items or game keys, for which personalization will be configured.
• You explored the User attributes section (for partners who use Xsolla Login to authorize users).
• You added users in the settings of your Login project in the User database > Users section, for whom you can add attributes (for partners who use Xsolla Login to authorize users).

Personalization using Pay Station Access Token to authorize users

If you use a Pay Station Access Token to authorize users, you can pass attributes when getting the token. In this case, do the following to set up personalization:

1. Create attributes in your system.
2. Add attributes to users in your system.
3. Implement logic to update attribute values when they change for a user in the game.
4. Create catalog display rules with your attributes.
5. Pass the attributes when getting the Pay Station Access Token.
6. Use the received token in the methods for requesting the item catalog.

Personalization using Xsolla Login to authorize users

If you use Xsolla Login to authorize users, you need to:

1. Create a JSON schema for user attributes on Xsolla’s side and specify the attributes within it (optional).

2. Add attributes to users and update attribute values using the Login API.
3. Create catalog display rules with the created attributes.
4. Implement getting a user's JWT. You can find a list of methods for getting a JWT in this example.
5. Use the received token in the methods for requesting the item catalog.

There are several ways to add attributes to a user:

• Use attribute update methods:
  • Update user’s attributes from server
  • Update user’s read-only attributes from server

1. Use these methods to add attributes to a user and update attribute values. To personalize the catalog, it is necessary to keep attribute values updated: Update attribute values in Xsolla when they change for the user in the game.

1. Example: A user reaches a new level, completes a quest, or makes a purchase.

1. You can update the values of both a single attribute and multiple attributes simultaneously. The exception is attributes specified as required in the JSON schema — without specifying required attribute values, you will not be able to call the attribute update API methods.

• Pass the actual attribute values directly when authorizing the user if you use the Auth by custom ID method. In this method, you can pass an array with the current values of user attributes.

Example of personalization setting up

This example shows how to set up catalog personalization: the Medium crystal set item is displayed only to users who have purchased the game MyTestGame.

Creating the attributes schema

• Attribute “game” with type “string” — the name of the game the user purchases. The “game” attribute is marked as required. You cannot call attribute update methods if you do not pass the “game” attribute.

• Attribute “purchase_number” with type “integer” — number of user purchases.

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Example",
	"description": "JSON Schema description.",
	"properties": {
		"game": {
			"description": "Name of the game played by a user.",
			"type": "string"
		},
		"purchase_number": {
			"description": "The number of purchases the user made.",
			"type": "integer"
		}
	},
	"additionalProperties": false,
	"required": [
		"game"
	],
	"type": "object"
}

Adding attributes to a user

Add attributes to a user from the user database using the Update user’s read-only attributes from server method.

In the Update user’s read-only attributes from the server method, you must specify:

• Server token.
• User attribute values.
• user_id — the user identifier specified in the settings of your Login project in the Publisher Account in the User database > Users section.
• publisher_id — merchant ID specified:
  • in the Company settings > Company section.
  • in the URL in the browser address bar on any Publisher Account page. The URL has the following format: https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
• publisher_project_id — Project ID what you can find in your Publisher Account next to the name of the project.

Preliminarily get the server token using the Generate JWT method.

Then, proceed to the Update user’s read-only attributes from the server method.

The request body with an array of attributes has the following format:

{
  "attributes": [
    {
      "key": "game",
      "permission": "private",
      "value": "MyTestGame"
    },
 {   
     "key": "purchase_number",
      "permission": "private",
      "value": "30"
    }

  ],
  "publisher_id": 000000,
  "publisher_project_id": 000000
}

As a result of executing the request, the user who does not have any attributes now has attributes with the specified values:

Creating a catalog display rule

Set up a rule to display the Medium Crystal Set item only to users who have purchased the MyTestGame.

To do this:

1. In Publisher Account, go to Store > Catalog management > Catalog display rules.
2. Click Create rule and complete the required fields:
   1. attribute key in the User attribute field — game
   2. type — string
   3. comparison operator — equal to
   4. value — MyTestGame

3. Specify the item that should be displayed if the condition is met. In the example below, the Medium Crystal Set is displayed for users that own the MyTestGame.

4. Check the rule, activate it, and save it.

Getting the token

Getting Xsolla Login JWT

• Auth by username and password
• Auth via social provider
• Passwordless auth by email
• Passwordless auth by phone number
• Auth via device ID
• Auth by custom ID
• and other methods for getting user token from the JWT or OAuth.2.0 group of methods

Getting Pay Station Access Token

Get Pay Station Access Token with the required attribute. To do this, you need to pass “game”: “MyTestGame” in the attributes object in the Create token method.

Example request body:

{
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 000001,
    "ui": {
      "size": "medium"
    }
  },
  "user": {
    "email": {
      "value": "email@example.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "attributes": {
      "game": "MyTestGame"
    }
  }
}

Getting the item catalog

Getting the item catalog using Xsolla Login JWT

Get the catalog using the token of the user to whom you added the game attribute with the value MyTestGame. To do this, specify the following in the Get virtual items list method:

• the obtained user JWT in the authorization header
• the project ID in the Publisher Account as a path parameter

The response includes three items:

• Empire Key
• Small crystal pack
• Medium crystal set, for which the personalization rule is configured

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "OtherGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

The Get virtual items list method with the obtained token returns two items: Empire Key and Small crystal pack. The Medium crystal set, which has a personalization rule applied, is not included in the response.

For comparison, now pass the game attribute with the MyTestGame value.

This is the attributes array in the Auth by custom ID method for the user with the game MyTestGame:

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "MyTestGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

Specify the obtained token when requesting the item catalog in the Get virtual items list method.

As a result, the Medium Crystal Set is included in the response:

Getting the item catalog using Pay Station Access Token

To get the personalized items catalog, you need to specify the following in the Get virtual items list method:

• the obtained Pay Station Access Token in the authorization header
• the project ID in the Publisher Account as a path parameter

The response includes three items:

• Empire Key
• Small crystal pack
• Medium crystal set for which the personalization rule is configured

You can test the response when getting the item catalog if the user does not have the game attribute with the MyTestGame value.

When you receive the Pay Station Access Token, delete the attributes object and request the item catalog again using the Get virtual items list method. Now, the response does not include the Medium Crystal Set: