Personalización del catálogo de artículos

Este tutorial muestra cómo:

• personalizar el catálogo usando atributos creados en su lado (para socios que utilizan el Token de acceso a Pay Station para autorizar a los usuarios)
• especificar las reglas de validación de atributos en el esquema JSON y agregar atributos al usuario en el lado de Xsolla (para los socios que utilizan Xsolla Login para autorizar a los usuarios)
• crear una regla de visualización del catálogo
• obtener el catálogo de artículos para un usuario con diferentes valores de atributos

Requisitos previos

Antes de comenzar, asegúrese de que:

• Ha creado un catálogo de artículos internos del juego o claves del juego, para los que se establecerá la personalización.
• Ha explorado la sección User attributes (Atributos de usuario) para los socios que utilizan Xsolla Login para autorizar a los usuarios).
• Ha añadido usuarios en la configuración de su proyecto de Login en la sección User database > Users, para los que puede agregar atributos (para socios que utilizan Xsolla Login para autorizar usuarios).

Personalización mediante el Token de acceso a Pay Station para autorizar a los usuarios

Si utiliza un Token de acceso a Pay Station para autorizar a los usuarios, puede transmitir attributes (atributos) al obtener el token. En este caso, haga lo siguiente para establecer la personalización:

1. Crear atributos en su sistema.
2. Agregar atributos a los usuarios en su sistema.
3. Implementar la lógica de actualización de los valores de atributo cuando cambian para un usuario en el juego.
4. Crear una regla de visualización de catálogo con sus atributos.
5. Transmitir los atributos cuando obtenga el Token de acceso a Pay Station.
6. Utilice el token recibido en los métodos para solicitar el catálogo de artículos.

Personalización a través de Xsolla Login para autorizar a los usuarios

Si emplea Xsolla Login para autorizar a los usuarios, tiene que:

1. Crear un esquema JSON para los atributos de usuario en el lado de Xsolla y especificar los atributos dentro de ese esquema (opcional).

2. Agregue atributos a los usuarios y actualice los valores de los atributos mediante Login API.
3. Cree reglas de visualización del catálogo con los atributos creados.
4. Implemente la obtención del JWT de un usuario. Puede encontrar una lista de métodos para obtener un JWT en este ejemplo.
5. Use el token recibido en los métodos para solicitar el catálogo de artículos.

Hay varias formas de agregar atributos a un usuario:

• Use los métodos de actualización de atributos:
  • Actualizar los atributos del usuario desde el servidor
  • Actualizar los atributos de solo lectura del usuario desde el servidor

1. Use estos métodos para agregar atributos a un usuario y actualizar los valores de atributo. Para personalizar el catálogo, se deben mantener actualizados los valores del atributo: actualice los valores de atributo en Xsolla cuando cambien para el usuario en el juego.

1. Ejemplo: Un usuario alcanza un nuevo nivel, termina una misión o realiza una compra.

1. Puede actualizar los valores de un solo atributo y de varios atributos de forma simultánea. La excepción son los atributos especificados como requeridos en el esquema JSON: si no se especifican los valores de atributo requeridos, no podrá llamar a los métodos API de actualización de atributos.

• Transmita directamente los valores actualizados de atributo al autorizar al usuario si utiliza el método Auth by custom ID. En este método, puede transmitir una matriz con los valores actuales de los atributos del usuario.

Ejemplo de establecimiento de la personalización

Este ejemplo muestra cómo establecer la personalización del catálogo: el artículo Paquete de cristales mediano solo se muestra a los usuarios que han comprado el juego MyTestGame.

Crear el esquema de atributos

• Atributo “game” con el tipo “string”: el nombre del juego que compra el usuario. El atributo “game” está definido como obligatorio. No podrá llamar a los métodos de actualización de atributos si no transmite el atributo “game”.

• Atributo “purchase_number” con el tipo “integer”: número de compras del usuario.

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

Agregar atributos a un usuario

Agregue atributos a un usuario desde la base de datos de usuarios usando el método Update user’s read-only attributes from server (Actualizar atributos del usuario de solo lectura desde el servidor).

En el método Update user’s read-only attributes from the server debe especificar:

• Token de servidor.
• Valores de atributo de usuario.
• user_id: el identificador de usuario especificado en la configuración de su proyecto de Login en la Cuenta del editor, en la sección User database > Users.
• publisher_id: ID de comerciante especificado:
  • En la sección Company settings > Company.
  • En la URL de la barra de direcciones del navegador de cualquier página de Cuenta del editor. La URL tiene el siguiente formato: https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
• publisher_project_id: ID del proyecto que puede encontrar en su Cuenta del editor junto al nombre del proyecto.

Obtenga previamente el token de servidor usando el método Generate JWT.

Después, proceda a usar el método Update user’s read-only attributes from the server (Actualizar los atributos de solo lectura del usuario desde el servidor).

El cuerpo de la solicitud con una matriz de attributes tiene el siguiente formato:

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

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

A raíz de la ejecución de la solicitud, el usuario que no tiene ningún atributo, ahora tiene atributos con los valores especificados:

Creación de una regla de visualización de catálogos

Establezca una regla para mostrar el artículo Paquete de cristales mediano solo a los usuarios que hayan comprado el juego MyTestGame.

Para ello:

1. En Cuenta del editor, vaya a Store > Catalog management > Catalog display rules.
2. Haga clic en Create rule y rellene los campos obligatorios:
   1. clave del atributo en el campo User attribute - game
   2. tipo - string
   3. operador de comparación - equal to
   4. valor - MyTestGame

3. Especifique el artículo que debe mostrarse si se cumple la condición. En el siguiente ejemplo, se muestra el Paquete de cristales mediano para los usuarios que poseen el juego MyTestGame.

4. Verifiquee la regla, actívela y guárdela.

Obtener el token

Obtener el JWT de Xsolla Login.

• Autenticación mediante nombre de usuario y contraseña
• Autenticación mediante proveedor de red social
• Autenticación sin contraseña vía correo electrónico
• Autenticación sin contraseña vía número de teléfono
• Autenticación mediante ID de dispositivo
• Autenticación mediante ID personalizado
• y otros métodos para obtener el token de usuario del grupo de métodos JWT o OAuth 2.0

Obtener Token de acceso a Pay Station

Consiga el Token de acceso a Pay Station con el atributo requerido. Para ello, debe transmitir “game”: “MyTestGame” en el objeto attributes en el método Create token (Crear token).

Ejemplo de cuerpo de solicitud:

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

Obtención del catálogo de artículos

Obtención del catálogo de artículos mediante el JWT de Xsolla Login

Obtenga el catálogo usando el token del usuario al que añadió el atributo del game con el valor MyTestGame. Para ello, especifique lo siguiente en el método Obtener lista de artículos virtuales:

• el JWT de usuario obtenido en el encabezado de la autorización
• el ID del proyecto en la Cuenta del editor como parámetro de ruta

La respuesta incluye tres artículos:

• Clave del Imperio
• Paquete de cristales pequeño
• Paquete de cristales mediano, para los cuales la regla de personalización no está configurada

"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
  }
]

El método Obtener lista de artículos virtuales con el token obtenido devuelve dos artículos: Clave del Imperio y Paquete de cristales pequeño. El Paquete de cristales mediano, al que se le ha aplicado una regla de personalización, no se incluye en la respuesta.

Para hacer una comparación, transmita ahora el atributo del game con el valor MyTestGame.

Esta es la matriz de attributes en el método Auth by custom ID para el usuario con el juego 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
  }
]

Especifique el token obtenido cuando solicite el catálogo de artículos en el método Obtener lista de artículos virtuales.

Como consecuencia, el Paquete de cristales mediano se incluye en la respuesta:

Obtener el catálogo de artículos mediante el Token de acceso a Pay Station

Para obtener el catálogo de artículos personalizados, debe especificar lo siguiente en el método Get virtual items list:

• el Token de acceso a Pay Station obtenido en el encabezado de la autorización
• el ID del proyecto en Cuenta del editor como parámetro de ruta

La respuesta incluye tres artículos:

• Clave del Imperio
• Paquete de cristales pequeño
• Paquete de cristales mediano, para los cuales la regla de personalización no está configurada

Puede probar la respuesta cuando obtenga el catálogo de artículos si el usuario no tiene el atributo de game con el valor MyTestGame.

Cuando reciba el Token de acceso a Pay Station, elimine el objeto attributes y vuelva a solicitar el catálogo de artículos usando el método Obtener lista de artículos virtuales. Ahora, la respuesta ya no incluye el Paquete de cristales mediano: