Descripción general

Digital Distribution Hub es una solución que conecta a los desarrolladores de juegos con múltiples socios distribuidores que disponen de sus propias plataformas o ecosistemas para la distribución de juegos, artículos virtuales, moneda virtual, y lotes.

Socios distribuidores: plataformas digitales o ecosistemas que pueden distribuir juegos y artículos internos del juego y tener su propio escaparate y sistema de facturación. Ejemplos de socios distribuidores de Xsolla:

• superaplicaciones que agrupan múltiples servicios
• aplicaciones bancarias
• proveedores de servicios de telecomunicaciones e internet
• quioscos de efectivo
• proveedores de programas de reembolso y recompensas
• mercados de comercio electrónico.

Beneficios para el desarrollador de videojuegos:

• Expandir la audiencia de los juegos a través de una conexión directa con socios distribuidores de rápido crecimiento.
• Aumento de los ingresos mediante la incorporación de juegos a nuevos canales de distribución con una base de usuarios única.
• Fomento de la detectabilidad orgánica en plataformas de terceros a través de anuncios y banners.

Beneficios para el socio distribuidor:

• Aumento de la fidelidad de sus usuarios al ampliar el acceso al contenido del juego. Los usuarios pueden comprar claves del juego, artículos virtuales, moneda virtual y lotes directamente desde la aplicación o el servicio.
• Retención de los usuarios actuales y atracción de nuevos usuarios gracias a la creciente popularidad del sector de los videojuegos.
• Aumentar los ingresos procedentes de la comisión de la venta de claves del juego, artículos virtuales y moneda virtual de los principales editores del sector de los videojuegos.

Cómo funciona

Flujo del usuario cuando compra claves del juego

Flujo del usuario cuando compra artículos virtuales y moneda virtual

Flujo de interacción

1. El desarrollador del juego crea un proyecto en Cuenta del editor y carga las claves del juego, los artículos virtuales, la moneda virtual y los lotes.
2. Un socio distribuidor solicita datos del usuario:
   • al vender juegos - la dirección de correo electrónico del usuario a la que se enviarán las claves y el recibo
   • al vender artículos internos del juego - el ID en el juego del usuario al que se añadirán los artículos y la dirección de correo electrónico del usuario a la que se enviará el recibo.
3. El usuario introduce los siguientes datos en la interfaz del socio distribuidor:
   • para compras de juegos - la dirección de correo electrónico para recibir las claves y el recibo
   • para compras de artículos internos del juego - ID del juego para añadir los artículos al inventario y una dirección de correo electrónico para recibir el recibo.
4. El socio distribuidor llama al método Create user token y transmite la dirección de correo electrónico (obligatoria) y el ID de usuario (obligatorio cuando se venden artículos virtuales, moneda virtual y lotes) como parámetros.
5. Xsolla comprueba si el usuario existe en el juego, si el desarrollador del juego tiene los webhooks establecidos. La configuración de webhooks es obligatoria para la venta de artículos virtuales y moneda virtual, pero opcional para las claves del juego.
6. Xsolla crea un token con los datos del usuario y envía el token al socio distribuidor.
7. El socio distribuidor solicita un catálogo de juegos o de artículos internos del juego.
8. Xsolla devuelve el catálogo solicitado en la respuesta.
9. El socio distribuidor recibe el catálogo y se lo muestra al usuario.
10. El usuario realiza una compra. El socio distribuidor crea una cesta.
11. El socio distribuidor envía la cesta del usuario para crear un pedido.
12. Xsolla devuelve el ID del pedido y el precio de la cesta incluyendo descuentos e impuestos.
13. El socio distribuidor muestra al usuario el coste total de la cesta.
14. Si el usuario continúa con el pago, el socio distribuidor carga el importe en la cuenta del usuario y muestra la página de estado del pago.
15. El socio distribuidor notifica a Xsolla que el pedido ha sido pagado y envía la información de pago.
16. Xsolla notifica la compra al desarrollador del juego.
17. El usuario que ha comprado el juego recibe un correo electrónico con los detalles de la compra y puede activar las claves del juego. Si el usuario compró artículos virtuales o moneda virtual, se añade a su inventario.

Integración en el lado del desarrollador de juegos

Cómo conectar Digital Distribution Hub

1. Conecte Tienda en Cuenta del editor y descargue:
   • claves del juego o lotes de claves del juego, si vende claves de juego
   • artículos virtuales, moneda virtual o lotes, si vende artículos internos del juego
2. Establezca webhooks.
3. Contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com para activar Digital Distribution Hub para su proyecto.

Cómo establecer webhooks

Se requiere la configuración del webhook:

• para validar al usuario y personalizar el catálogo por ID de usuario en el juego
• para validar al usuario y añadir los artículos comprados en el juego a su inventario
• para vincular el ID de transacción en el lado de Xsolla con el ID de transacción en el sistema del desarrollador del juego
• para transmitir parámetros adicionales del usuario en el pedido
• para recibir notificaciones de compra.

Para establecer webhooks:

1. Abra su proyecto en Cuenta del editor.
2. Haga clic en Project settings en el menú lateral y vaya a Webhooks.
3. Ponga el conmutador Webhooks en la posición On.
4. Especifique la URL del webhook.
5. Se genera por defecto una clave secreta para firmar los webhooks del proyecto. Si desea generar una nueva clave secreta, pulse en el icono de actualización.
6. Haga clic en Save settings.

Validación del usuario

Xsolla envía un webhook de User validation para verificar que un usuario existe en el juego. La validación de usuario le permite:

• mostrar un catálogo personalizado para el usuario si usted transmite atributos de usuario en la respuesta
• añadir artículos al inventario del usuario después de la compra.

Para confirmar la recepción del webhook, su servidor debería devolver:

• un código HTTP 204 sin cuerpo de mensaje, si el usuario existe en el juego
• un código HTTP 400 que describa el problema, si no se encontró al usuario especificado o si se ha transmitido una firma no válida.

La lista completa y el mecanismo de los webhooks, ejemplos incluidos, se describen detalladamente en la Referencia de la API.

En respuesta, puede transmitir parámetros de transacción adicionales en el objeto custom_parameters.

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": false,
"properties": {
  "user_attributes": {
    "type": "object",
    "required": false,
    "minProperties": 1,
    "maxProperties": 100,
    "patternProperties": {
      "^[\\w-_.]{1,255}$": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 255
            },
            "minItems": 1,
            "maxItems": 1000
          }
        ]
      }
    },
    "additionalProperties": false
  }
}
}

Ejemplo de respuesta:

{
  "user_attributes": {
    "age": 18,
    "level": 1,
    "game": "WoW",
    "is_baned": false,
    "registration_date": "2022-01-01"
  }
}

Vincular el ID de la transacción

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "notification_type": {
      "type": "string"
    },
    "order_id": {
      "type": "integer"
    },
    "project_id": {
      "type": "integer"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_id": {
            "type": "integer"
          },
          "sku":  {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "type": {
            "type": "string"
          }
        }
      }
    }
  }
}

Ejemplo de solicitud:

{
  "notification_type": "create_external_transaction",
  "order_id": 1,
  "project_id": 51336,
  "user": {
    "external_id": "user_id",
    "email": "public_email@test.com"
  },
  "items": [
    {
      "item_id": 101,
      "sku": "mithril_dagger",
      "quantity": 2,
      "type": "virtual_good"
    }
  ]
}

En respuesta, puede transmitir parámetros de transacción adicionales en el objeto custom_parameters.

Respuesta prevista:

{
  "id": "validation_transaction_info_response.json",
 "$schema": "http://json-schema.org/draft-07/schema#",
 "description": "DDH Project Transaction Info Response",
 "type": "object",
 "additionalProperties": true,
 "properties": {
   "id": {
     "type": "string",
     "minLength": 1
   },
  "custom_parameters": {
     "type": "object",
     "additionalProperties": true,
     "minProperties": 1,
     "maxProperties": 200
   }
 }
}

Ejemplo de respuesta:

{
    "id":"123"
}

Lista de parámetros de webhook para vincular los ID de transacciones:

Notificación de compra

• el webhook de pago que contiene información sobre el pago.
• el webhook del contenido de la cesta, que contiene información sobre los artículos que se añadirán al inventario.

Integración en el lado del socio distribuidor

Si está interesado en integrar Digital Distribution Hub, envíe un correo electrónico al gestor de integración a psbusiness@xsolla.com y obtenga los parámetros necesarios para trabajar con la Digital Distribution Hub API:

• geotype
• project_id
• distribution_hub_id y api_key

Durante la integración, deberá enviar notificaciones sobre los pagos realizados correctamente o las cancelaciones de pago (paso 9). Para procesar correctamente las notificaciones en el lado de Xsolla, informe a su gestor de la dirección IP del servidor desde el que envías las notificaciones. Si la dirección IP cambia, asegúrese de informar al gestor lo antes posible.

1. Visualizar un formulario para introducir:
   • la dirección de correo electrónico del usuario; cuando venda juegos
   • la dirección de correo electrónico del usuario y el ID interno del juego; cuando venda artículos internos del juego.

1. El ID de usuario se utiliza en proyectos que venden artículos virtuales, moneda virtual y lotes con artículos y moneda. En este caso, también es necesario mostrar una sugerencia para que el usuario introduzca el ID que recibió al registrarse en el juego.

1. Ejemplo:

2. Transmitir los datos de usuario recibidos:
   • Dirección de correo electrónico del usuario. Siempre obligatoria.
   • ID del usuario en el juego. Obligatorio para vender artículos internos del juego.

1. Los datos se utilizan para verificar la existencia del usuario en el juego y recibir un token de autorización.

1. Utilice el método Create user token. Transmita los parámetros en la solicitud:

1. En la respuesta se devuelve un token de autorización con los datos del usuario.

3. Importar:
   • catálogo de juegos, utilizando el método Obtener lista de juegos
   • catálogo de artículos virtuales, utilizando el método Obtener artículo virtual
   • catálogo de monedas virtuales, utilizando el método Obtener lista de monedas virtuales
   • catálogo de paquetes con juegos u objetos del juego, utilizando el método Obtener lista de lotes

1. En la solicitud, transmita el token que recibió en el paso 2 y el siguiente parámetro:

4. Muestra el catálogo de juegos y artículos del juego en su escaparate. En la interfaz, implemente la posibilidad de seleccionar:
   • el número de claves del juego y de plataformas de publicación de juegos
   • el número de artículos virtuales
   • el número de unidades de moneda virtual o de paquetes de moneda virtual o con una cantidad fija de moneda
   • el número de lotes

1. Si utiliza una cesta, el número de artículos puede especificarse en la cesta del usuario. Si no utiliza una cesta, la elección del número de artículos puede implementarse en el catálogo.

1. Ejemplo para especificar el número de artículos en la cesta:

1. Ejemplo para especificar el número de artículos del catálogo:

1. Si no utiliza una cesta, vaya al paso 6 y utilice el método Crear pedido con un artículo especificado.

5. Para llenar la cesta, utilice el método Fill the cart with items.

1. El usuario puede añadir y eliminar artículos o cambiar su cantidad en una solo pedido. Puede utilizar los siguientes métodos para actualizar el carrito:
   • método Fill the cart with items cada vez que el usuario cambie el contenido de la cesta
   • métodos para actualizar la cesta y eliminar un artículo:
     • Actualizar artículo de la cesta actual
     • Delete all cart items from current cart
     • Delete cart item from current cart

1. En este caso, utilice Obtener la cesta del usuario actual después de actualizar la cesta.

1. Transmita los siguientes parámetros en las solicitudes para los métodos de llenado y actualización de cestas:

1. Tras llamar al método Fill the cart with items o Obtener la cesta del usuario actual, la respuesta devuelve información actualizada sobre los productos seleccionados: precios antes y después de descuentos y productos de bonificación.

6. Para crear un pedido y pagar los artículos de una cesta, utilice el método Crear pedido con todos los artículos de la cesta actual. Transmita los siguientes parámetros en la solicitud:

1. La respuesta devuelve el ID del pedido y el precio de la cesta, impuestos incluidos.

7. Mostrar el precio total de la cesta al usuario.
8. Cargar a cuenta de los fondos del usuario desde su plataforma. Muestre el estado del pago al usuario.
9. Enviar una notificación de pago. Si el pago fue reembolsado o no se completó, enviar una notificación sobre la cancelación del pago.

1. Para procesar correctamente las notificaciones en el lado de Xsolla, informe a su gestor de Xsolla de la dirección IP del servidor desde el que envía las notificaciones. Si la dirección IP cambia, asegúrese de informar al gestor lo antes posible.