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
Note
This tutorial doesn’t cover the setting up personalized promotions. You can set up personalized promotions in the same way as item catalog personalization when using Xsolla Login to authorize users.

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).

Note
You can:
  • Create a JSON schema for user attributes and only pass the attributes specified in this JSON schema. To do this, in the JSON schema, specify false in the additionalProperties object. The specified attributes are automatically validated.
  • Create a JSON schema for user attributes and pass both the attributes specified in the JSON schema and additional attributes not mentioned in the JSON schema. To do this, in the JSON schema, specify true in the additionalProperties object. The attributes specified in the JSON schema are automatically validated.
  • Not create a JSON schema for user attributes. In this case, you can pass any attributes, and attributes validation is not performed.
For item catalog personalization, we recommend that you specify attributes and their types in the JSON schema within the properties object to ensure attribute keys and values are automatically validated.

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

There are several ways to add attributes to a user:

  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.
Note
  • 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.
Note
We recommend creating server attributes that are read-only. To do this, pass the parameter values “attr_type”: “server” and “read_only”: “true”.

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.

Note
The Medium Crystal Set and MyTestGame names are provided as examples. You can configure catalog personalization using the items and attributes in your project.
Further are considered options for creating attributes on the Xsolla side (user authorization via Xsolla Login) and on the partner side (user authorization via Pay Station Access Token). For the Pay Station Access Token option, you can proceed directly to creating the catalog display rule.

Creating the attributes schema

Add a JSON schema with attributes corresponding to the game name and purchase count. To do this, specify the following in the 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 example:
Copy
Full screen
Small screen

{
	"$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.
Note

Parameter names in API methods may vary across different products:

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:

Copy
Full screen
Small screen
{
  "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
  1. 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.
  1. Check the rule, activate it, and save it.

Getting the token

Getting Xsolla Login JWT

Get a token for a user to whom you added the game attribute with the value MyTestGame.
You can get Xsolla Login JWT after successful user authorization on the client or server side without user involvement. To do this, use one of the following Xsolla Login authorization 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:

Copy
Full screen
Small screen

{
  "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

To get the item catalog, call the Get virtual items list method, using either Xsolla Login User JWT or Pay Station Access Token for authorization.

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


You can test the response when getting the item catalog if the attribute value does not match the specified in the rule. For testing, you can pass the attributes directly when getting the token using the Auth by custom ID method.
Note
This method can be used only for users authorized via Auth by custom ID method.
Get the user JWT using the Auth by custom ID method and pass the game attribute with the value OtherGame in the attributes array:
Copy
Full screen
Small screen
"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:

Copy
Full screen
Small screen

"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 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:

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.
Last updated: October 3, 2024

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!