SDK de nivel empresarial para Unreal Engine / Cómo usar Pay Station en combinación con la autenticación de PlayFab
  Volver a Documentos

SDK de nivel empresarial para Unreal Engine

Cómo usar Pay Station en combinación con la autenticación de PlayFab

Si ya ha implementado la autenticación de usuario en su aplicación usando PlayFab, puede generar un token de pago en el lado de PlayFab y, luego, transmitirlo al lado del cliente de la aplicación para abrir la interfaz de pago.

Al usar esta opción de integración, debe implementar de forma independiente la lógica para determinar el país y la moneda del usuario para abonar la compra.

Flujo de integración:

  1. Crear un proyecto.
  1. Regístrese en Cuenta del editor y cree un nuevo proyecto. Necesitará el ID del proyecto creado para los pasos posteriores.

  1. Establecer un catálogo:
    • Cree un catálogo de artículos en el lado de Xsolla. Puede agregar artículos manualmente o importarlos desde Google Play o PlayFab.
    • Implemente la obtención y visualización del catálogo en el lado del cliente de la aplicación usando el kit SDK.

  1. Establecer la compra de un artículo:
    • Cree un pedido con los datos del usuario y del artículo en el lado del cliente de la aplicación usando el script de PlayFab Cloud.
    • Implemente la apertura de la interfaz de pago en el lado del cliente de su aplicación usando el kit SDK.

  1. Establecer un seguimiento del estado del pedido.

Aviso

Para finalizar la integración y empezar a aceptar pagos reales, deberá firmar un acuerdo de concesión de licencia con Xsolla.

Puede firmar el acuerdo de licencia en cualquier paso de la integración, pero tenga en cuenta que el proceso de revisión puede tardar hasta 3 días laborables.

Crear proyecto

Registrarse en Cuenta del editor

Cuenta del editor es la herramienta fundamental para configurar las funciones de Xsolla, así como para operar con los análisis y las transacciones.

Los datos sobre la empresa y su aplicación indicados durante el registro se usarán para crear un borrador de acuerdo de licencia con Xsolla y para generar recomendaciones sobre las soluciones que se adaptan a sus necesidades. Puede modificar los datos después, pero si facilita los datos correctos al registrarse, se acelerará el proceso de firma del acuerdo de licencia.

Para registrarse, acceda a Cuenta del editor y cree una cuenta.

Nota

La contraseña de Cuenta del editor puede estar compuesta por letras del alfabeto latino, números y caracteres especiales y debe contener al menos:

  • 8 caracteres
  • un dígito
  • una letra mayúscula
  • y una letra minúscula

Para maximizar la seguridad de su contraseña, le recomendamos:

  • cambiar su contraseña al menos una vez cada 90 días
  • utilizar una contraseña nueva que no coincida con las 4 últimas contraseñas de su cuenta
  • utilizar una contraseña única que no coincida con contraseñas empleadas en ningún otro lugar
  • no almacenar su contraseña en un lugar de fácil acceso
  • utilizar gestores de contraseñas para almacenar su contraseña

Cuenta del editor utiliza la autenticación de dos factores y envía un código de confirmación siempre que se produce un intento de autenticación.

Crear proyecto en Cuenta del editor

Si tiene varias aplicaciones, recomendamos crear un proyecto independiente para cada una de ellas. A partir de los datos especificados durante la creación del proyecto, Xsolla genera recomendaciones sobre soluciones que se adaptan a sus necesidades.

Para crear un nuevo proyecto:

  1. Abra Cuenta del editor.
  2. En el menú lateral, haga clic en Create project.

  1. Introduzca el nombre de su proyecto en inglés (obligatorio).

Nota
Cuando haya creado el proyecto, puede añadir idiomas adicionales y los nombres de proyecto traducidos en la sección Project settings.

  1. Seleccione una o varias plataformas de lanzamiento de su juego (obligatorio).
  2. Agregue un enlace a su juego. Si su juego aún no tiene sitio web, agregue un enlace al código fuente que incluya información sobre el juego (obligatorio).
  3. Seleccione el motor del juego.
  4. Seleccione las opciones de monetización que utiliza o prevé utilizar.
  5. Especifique si el juego ya se ha lanzado. Si el juego aún no se ha lanzado, especifique la fecha de lanzamiento prevista.
  6. Haga clic en Create project. Podrá ver una página con los productos de Xsolla que le recomendamos.

Durante el proceso de integración, debe proporcionar el ID del proyecto que se encuentra en su Cuenta del editor junto al nombre del proyecto.

Establecer catálogo

Crear artículos en Cuenta del editor

Aviso

Tiene que crear un catálogo en el lado de Xsolla. Puede agregar artículos manualmente o importarlos desde Google Play o PlayFab. Cuando haga importaciones desde Google Play, puede importar un máximo de 100 artículos cada vez.

Estas instrucciones indican los pasos para la configuración básica de un artículo virtual. Más tarde, podrá agregar otros artículos a su catálogo (moneda virtual, lotes y claves del juego), crear grupos de artículos, establecer campañas promocionales, precios regionales, etc.

Para agregar un artículo virtual con la configuración básica al catálogo:

  1. Abra su proyecto en Cuenta del editor.
  2. Haga clic en Store en el menú lateral.
  3. En el panel Virtual items, haga clic en Connect.
  4. En el menú desplegable, seleccione Create item.

  1. Establezca la configuración básica del artículo en los siguientes campos:
    • Image (opcional)
    • SKU (ID único del artículo)
    • Item name
    • Description (opcional)

  1. Especificar el precio del artículo:
    1. Establezca el conmutador Price in real currency en On.
    2. En el campo Default currency, cambie la moneda (opcional) y especifique el precio del artículo.
    3. Si cambió la moneda en el campo Default currency, seleccione la misma moneda en el campo Price in real currency.

Nota
Para cerciorarse de que las llamadas API para recuperar el catálogo funcionan correctamente, asegúrese de que la moneda por defecto y la lista de monedas en las que se definen los precios coinciden para todos los artículos.

  1. Cambie el estado del artículo a Available.

  1. Haga clic en Create item.

Instalar y configurar el SDK

  1. Descargar el lanzador de Epic Games.
  2. Crear un nuevo proyecto de Unreal Engine.

  1. Descargue e instale el SDK:
    1. Para descargar e instalar el SDK desde Unreal Engine Marketplace:
      1. Acceda a la página del SDK en Unreal Engine Marketplace.
      2. Haga clic en Open in Launcher.

      1. Vaya al lanzador de Epic Games.

      1. Haga clic en Install to Engine.Abra su proyecto de Unreal Engine en Unreal Editor.
      2. Vaya a la sección de Settings > Plugins > Installed > Xsolla SDK. Marque la casilla Enabled y haga clic en Restart Now para guardar la configuración y volver a cargar Unreal Editor.

    1. Para descargar e instalar el SDK desde GitHub:
      1. Descargue el paquete con el SDK para su versión del motor.
      2. Descomprima el paquete.
      3. Mueva la carpeta del SDK al directorio plugins presente en la raíz de su proyecto de Unreal Engine.

  1. Vaya a Settings > Project Settings > Plugins > Xsolla Settings > General.
  2. En el campo Project ID, especifique el ID del proyecto que puede encontrarse en Cuenta del editor junto al nombre de su proyecto.

Visualizar el catálogo en el lado del cliente de la aplicación

Nota

En estas instrucciones, se usa el método SDK GetVirtualItems para obtener una lista de artículos virtuales. También puede obtener información sobre los artículos del catálogo utilizando otros métodos del SDK.

Para ver un tutorial paso a paso sobre la creación de una página de catálogo, consulte la sección Visualización de catálogo de artículos.

Crear clase para artículos del catálogo

  1. En Content Browser, vaya al directorio Content.
  2. Invoque el menú contextual y seleccione Blueprint Class.

  1. En la sección All Classes, seleccione Object y pulse en Select.

  1. Especifique StoreItemData como el nombre de la clase.
  2. Abra el plano técnico de la clase creada.
  3. En el panel My Blueprint, haga clic en Add New y seleccioneVariable.
  4. En el panel Details:

    1. Especifique StoreItem en el campo Variable Type.
    2. Marque las casillas Instance Editable y Expose on Spawn.

  1. Guarde y cierre el plano técnico de StoreItemData.

Crear widget de artículos de catálogo

  1. En Content Browser, vaya al directorio Content. Invoque el menú contextual y seleccione User Interface > Widget Blueprint.
  2. Especifique StoreItem como nombre del plano técnico.
  3. Abra el plano técnico creado.
  4. En el panel Hierarchy, invoque el menú contextual del elemento CanvasPanel. Seleccione Replace With > Overlay.

Nota
En Unreal Engine 4.27, CanvasPanel es el componente raíz por defecto para cada widget recientemente creado. Unreal Engine 5 no agrega un componente raíz por defecto, por lo que debe crear un Overlay como componente raíz.

  1. Coloque las primitivas de interfaz de usuario del panel Palette como aparece a continuación. Para la imagen, el título y la descripción de un elemento, marque la casilla Is Variable del panel Details.

  1. Abra una vista Graph.
  2. Haga clic en Class settings.
  3. En el panel Details, vaya a Interfaces > Implemented Interfaces.
  4. Haga clic en Add y seleccione UserObjectListEntry. Es una interfaz estándar UE (de equipo de usuario) que permite que la primitiva de interfaz de usuario implemente un comportamiento normal para el elemento de la lista.

  1. Agregue lógica para el evento OnListItemObjectSet:
    1. En el panel My Blueprint, invoque al menú contextual de la sección Interfaces y seleccione Implement event.

    1. Agregue nodos como se muestra a continuación:

  1. Guarde y cierre el plano técnico de StoreItem.

Crear widget para la página del catálogo

  1. En el Content Browser, vaya al directorio Content y seleccione User Interface > Widget Blueprint en el menú contextual.
  2. Especifique WBP_Store como nombre del plano técnico.
  3. Abra el plano técnico creado.
  4. En el área de visualización de artículos, añada el artículo List View y póngale el nombre de StoreListView.

  1. En el panel Details, en el campo Entry Widget Class, seleccione la clase creada anteriormente para el artículo (StoreItem).
  2. Acceda a la vista Graph.
  3. Vincule la llamada al método del SDK GetVirtualItems al nodo EventConstruct, tal como se muestra en la siguiente figura.

Nota
La matriz de artículos que devuelve Xsolla es un grupo de estructuras de Unreal Engine. Pero los artículos de List View solo pueden recibir matrices de artículos de la clase UObject. Por ello, en el ejemplo se crea una matriz auxiliar de artículos de la clase StoreItemData para transferir correctamente la matriz de artículos.

  1. En el panel My Blueprint, pulse en Add New y seleccione Variable.
  2. En el panel Details:
    1. En el campo Variable Type, seleccione String.
    2. Marque las casillas Instance Editable y Expose on Spawn.
    3. Especifique PlayFabId como su nombre.

  1. Guarde y cierre el widget WBP_Store.
  2. Agregue la lógica de visualización del directorio. Después, aparecerá un ejemplo de implementación de la visualización del directorio tras la autenticación correcta del usuario.

Establecer la compra de artículos

Para crear un pedido con los datos del usuario y del artículo en el lado de Xsolla, agregue al proyecto una función de nube que use la llamada API Create payment token for purchase. Esta llamada devolverá un token de pago, el cual es necesario para abrir la interfaz de pago y hacer una compra.

Limitaciones:

  • Necesita transmitir el país del usuario o la dirección IP del usuario cuando se solicite el token de pago.
  • Si no transmite la moneda en el token, esta se determinaré en función del país.
  • Si transmite la moneda en el token, el usuario paga con esta moneda.

Nota

El proyecto PlayFab debería estar creado y el SDK de PlayFab debería estar ya integrado en su proyecto de Unity.

Los scripts de PlayFab Cloud no admiten directamente funciones con desencadenadores HTTP, por lo que se utilizan Azure Functions para implementar la recepción de webhooks.

Para comenzar a usar funciones de Azure, cree una cuenta de Azure y prepare su entorno de desarrollo. Estas instrucciones describen los pasos que se deben dar en el entorno de desarrollo con la siguiente configuración:

Agregar Cloud Script (script en la nube) a su proyecto

  1. Abra Visual Studio Code y acceda a la pestaña Azure.
  2. En la sección Workspace, haga clic en el icono + y seleccione Create Function.

  1. Seleccione el directorio del nuevo proyecto. Se mostrará un menú para crear un nuevo proyecto con varias opciones de configuración.

  1. Especifique la configuración del nuevo proyecto:
    1. Seleccione un idioma para su proyecto de función: JavaScript.
    2. Seleccione un modelo de programación en JavaScript: model V4.
    3. Seleccione una plantilla para la primera función de su proyecto: HTTP trigger.
    4. Introduzca un nombre de función: getXsollaPaymentToken.
    5. Seleccione cómo le gustaría abrir su proyecto: Open in current window.

  1. En consecuencia, Visual Studio Code generará un proyecto de JS y abrirá el archivo getXsollaPaymentToken.js generado.

  1. Modifique el archivo getXsollaPaymentToken.js:

Copy
Full screen
Small screen
const { app } = require('@azure/functions');

const projectId = ""; //your xsolla project id from publisher account
const apiKey = ""; your api key from publisher account

app.http('getXsollaPaymentToken', {
    methods: ['POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {

      var body = await request.json();

      const userId = body.uid;
      const email = body.email;
      const sku = body.sku;
      const returnUrl = body.returnUrl;

        if (!userId) {
          return {status: 400, body: 'Request body is missing' };
        }

        const payload = {
            user: {
              id: {value: userId},
              name: {
                value: email
              },
              email: {
                value: email
              },
              country: {
                value: 'US',
                allow_modify: false
              }
            },
            purchase: {
              items: [
                {
                  sku: sku,
                  quantity: 1
                }
              ]
            },
            sandbox: true,
            settings: {
              language: 'en',
              currency: 'USD',
              return_url: returnUrl,
              ui: {
                theme: '63295aab2e47fab76f7708e3'
              }
            }
          }

        let url = "https://store.xsolla.com/api/v2/project/" + projectId.toString() + "/admin/payment/token";

        return fetch(
            url,
            {
                method: "POST",
                headers: {
                'Content-Type': 'application/json',
                Authorization: 'Basic ' + btoa(`${projectId}:${apiKey}`)
                },
                body: JSON.stringify(payload)
            },
            )
            .then(xsollaRes => {
            // Handle the response data
                if (xsollaRes.ok) {
                    return xsollaRes.json();
                } else {
                    return { status: 400, body: `HTTP request failed with error: ${xsollaRes.statusText}` };
                }
            })
            .then(data => {
                return { status: 200, body: JSON.stringify(data) };
            })
            .catch(error => {
                return { status: 501, body: `Error = ${error}` };
            });
        }
});

  1. En el script, defina los valores de las siguientes constantes:

    • PROJECT_ID: ID del proyecto que puede encontrar en su Cuenta del editor junto al nombre del proyecto.

    • API_KEY: clave de API. Se muestra en la Cuenta del editor solo una vez cuando se crea, y debe almacenarse en su lado. Puede crear una nueva clave en la siguiente sección:
      • Company settings > API keys
      • Project settings > API keys

Después de agregar el script en la nube, puede probar la llamada de la función getXsollaPaymentToken en el entorno local.

Implementar el script en la nube

  1. En Visual Studio Code vaya a la sección Azure > Resources y pulse en el icono +.
  2. Seleccione Create Function App in Azure como recurso. Aparecerá un menú para crear una nueva aplicación con varias opciones de configuración.
  3. Establezca los ajustes de la aplicación:

    1. Introduzca el nombre para la nueva aplicación de función: XsollaFunctions.
    2. Seleccione una pila de tiempo de ejecución: .NET 8 Isolated.
    3. Seleccione una ubicación para los nuevos recursos (puede escoger cualquier opción).

  1. Espere a que se cree el grupo de recursos.

  1. De la lista de recursos, seleccione el XsollaFunctions, invoque el menú contextual y seleccione Deply to Function App.

Después de agregar el script en la nube, puede probar la llamada de la función getXsollaPaymentToken de forma remota.

Probar el script en la nube

Para probar el script en la nube (de forma local o remota), invoque la función getXsollaPaymentToken usando Postman u otra herramienta. Para ello, haga lo siguiente:

  1. En Visual Studio Code, acceda a la sección Azure > Workspace > Local Project > Functions y pulse en Start debugging to update this list.
  2. Invoque al menú contextual de la función y seleccione Copy Function Url. Cuando haga pruebas de forma local, la URL tendrá este aspecto: http://localhost:7071/api/getXsollaPaymentToken. Cuando haga pruebas de forma remota, tendrá este otro: https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken.

  1. Use la URL copiada para invocar la función con los parámetros especificados. Para invocar una función desde Postman:
    1. Cree una nueva solicitud GET.
    2. Proporcione la URL que copió en el paso 2.
    3. Vaya a la pestaña Body y especifique los parámetros de la solicitud.

Ejemplo de cuerpo de solicitud:

Copy
Full screen
Small screen
{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

   "returnUrl": "https://login.xsolla.com/api/blank"

 }

}
Nota
Puede especificar cualquier valor para el ID de usuario (uid). Como código de artículo (SKU) (sku), especifique el SKU del artículo virtual que agregó previamente a Cuenta del editor.

  1. Pulse en Send. En la respuesta debería recibir JSON con los siguientes parámetros:
    • token - token de pago. Se requiere para abrir la interfaz de pago.
    • order_id - ID del pedido creado. Se requiere para realizar el seguimiento del estado del pedido.

Ejemplo de cuerpo de la respuesta:

Copy
Full screen
Small screen
{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}

Registrar la función para obtener un token de pago en PlayFab

  1. Abra su proyecto en PlayFab.
  2. En el menú lateral, pulse en Automation.
  3. En la sección Register New Cloud Script Function, pulse en Register Function.
  4. Introduzca el nombre de la función: GetXsollaPaymentToken.
  5. Introduzca la URL de la función que copió en Visual Code Studio (consulte los pasos 1-2 de Pruebe el script en la nube).

Crear el pedido y abrir la interfaz de pago en el proyecto de Unreal Engine

  1. Abra su proyecto de Unreal Engine.
  2. Abra el widget WBP_Store.
  3. En el panel Hierarchy, seleccione StoreListView.
  4. En el panel Details, haga clic en el icono + ubicado junto al evento On Clicked.

  1. Vaya a la vista Graph.
  2. Agregue la lógica para crear un objeto PlayfabJsonObject y transmitirle datos para crear un pedido al nodo de OnItemClicked, como aparece a continuación:

  1. Agregue una llamada al método ExecuteFunction. Transmítale el functionName = getXsollaPaymentToken y los parámetros FunctionParameter = PlayfabJsonObject.

Establecer seguimiento del estado del pedido

Se requiere hacer el seguimiento del estado del pedido para garantizar que el pago se realizó correctamente y para conceder artículos al usuario.

Obtener el estado del pedido en el lado del cliente

Para hacer un seguimiento del estado del pedido usando el método del SDK CheckPendingOrder en el lado cliente de la aplicación, transmita los siguientes parámetros al método:

Para obtener información detallada sobre cómo funciona este método, consulte la sección Hacer seguimiento del estado del pedido.

Obtener el estado del pedido en el lado del servidor

Aviso

El SDK le permite hacer un seguimiento del estado del pedido en el lado del cliente de su aplicación. Sin embargo, le recomendamos establecer un controlador del webhook Payment para recibir información del pedido en el back-end de su aplicación. Esto le permite implementar una validación adicional de las compras realizadas.

Para obtener la lista completa de webhooks e información general sobre cómo operar con ellos, consulte la documentación de webhooks.

Para configurar los webhooks en el lado de Xsolla:

  1. Abra su proyecto en Cuenta del editor.
  2. Haga clic en Project settings en el menú lateral y vaya a la sección Webhooks.
  3. En el campo Webhook URL, ingrese la URL a la que Xsolla enviará los webhooks.

Nota

Para probar los webhooks, también puede elegir cualquier sitio web específico, como webhook.site, o una plataforma, como ngrok.

Para hacer pruebas, también puede agregar un script en la nube que simule el procesamiento correcto de webhooks. El código del script está disponible en GitHub.

Para un proyecto real, tiene que agregar una lógica de validación de compra.

  1. Copie y guarde el valor del campo Secret key. Esta clave se genera por defecto y se usa para firmar webhooks. Si desea cambiarla, haga clic en el icono de actualización.
  2. Haga clic en Enable webhooks.

¿Te ha resultado útil este artículo?
¡Gracias!
¿Hay algo en lo que podamos mejorar? Mensaje
Lo sentimos
Por favor, cuéntanos por qué no te ha resultado útil este artículo. Mensaje
¡Gracias por tu mensaje!
Nos ayudará a mejorar tu experiencia.
Última actualización: 4 de Septiembre de 2024

¿Has encontrado una errata u otro error de texto? Selecciona el texto y pulsa Ctrl+Intro.

Informar de un problema
Nos esforzamos por ofrecer contenido de calidad. Tus comentarios nos ayudan a mejorar.
Déjanos tu correo electrónico para que te podamos responder
¡Gracias por tu mensaje!