Sistema de Artículos y Tienda de Pagos de la Plataforma

Este sistema proporciona una solución unificada para la gestión de artículos de pago en la plataforma de juegos, compatible con funciones como la compra, distribución y estadísticas de artículos para juegos, implementando las funcionalidades de compra, consulta, adición/reducción de artículos y distribución activada por progreso del juego.

• Funciones principales: Compra de artículos, Consulta de posesión, Operaciones de adición/reducción, Monitoreo de cambios, Distribución activada por progreso del juego.

1. Funciones de Gestión en el Backend para Desarrolladores

• Los desarrolladores pueden crear manualmente datos de artículos a través del backend, compatible con la carga de tablas (tabla de unidades de artículos) e iconos de artículos.
• Los artículos de pago para la tienda actualmente solo admiten creación manual.
• Admite la creación de hasta 5000 entradas de datos de artículos.
• Actualmente solo es compatible con juegos de tipo compra única y compras integradas.
• Los artículos creados deben pasar por una revisión; una vez aprobados, entrarán en estado activado por defecto.

Funciones de Gestión de Artículos:

‌ID del Artículo‌: Identificador único, no modificable después de la creación.
‌Nombre e Icono del Artículo‌: Utilizados para la visualización en el frontend.
‌Icono del Artículo‌: Admite el cambio manual de la imagen del Icono.
‌Reglas de Creación de Artículos: Admite seleccionar entre Artículo de Juego y Artículo de Pago para la Tienda.
Restricciones del Artículo: Admite configurar límites para la distribución a los jugadores a través de la plataforma, como límite de cantidad diaria, límite de cantidad total o sin límite.
‌Inventario de Artículos‌: Se puede optar por ingresar una cantidad o no establecer límite.
Configuración del Valor del Artículo:
Artículo Gratuito (Actividades de la Plataforma): Compatible con la distribución en actividades de la plataforma.
Compra de Pago (Compra Pagada): Compatible con la compra pagada en la tienda de artículos.
Valorado en Dólares Americanos (USD) por defecto.
El precio unitario del artículo admite precisión hasta 0.0001 USD.
El valor mínimo de entrada para artículos de pago en la tienda es 1 USD.

Sugerencia

• Primero registre las unidades de artículos, luego ingrese manualmente los artículos para compra pagada en la tienda; admite seleccionar uno o múltiples artículos para formar un producto conjunto para su venta.
• Cuando un artículo se configura como gratuito, la plataforma puede optar por distribuirlo a los jugadores según los planes de operación; se entregará al personaje del jugador en el juego cuando éste ingrese.

2. Integración del SDK de Artículos

Descripción de las Interfaces Principales

Nombre de la Interfaz	Firma del Método	Descripción de la Función
Abrir Ventana de Compra	openBuyGameItemsDialog(level: number)	Abre un cuadro de diálogo de compra de artículos de la tienda a través de la UI funcional dentro del juego.
Obtener Artículos Poseídos	getUserGameItems(): GameItem[]	Consulta la lista actual de artículos del jugador al ingresar al juego (incluye ID y cantidad).
Añadir Artículo	addGameItem(itemId: string, amount: number)	Distribuye artículos durante el progreso del juego (compatible con escenarios como compras, recompensas de niveles, finalización de misiones, etc.).
Reducir Artículo	subtractGameItem(itemId: string, amount: number)	Consume artículos (escenarios de uso o consumo durante el progreso del juego, la cantidad después de la deducción no será negativa).
Suscribirse a Notificaciones de Cambio	subscribeGameItemChange(callback: (res: GameItemChange) => void)	Método de callback que se ejecuta cuando se completa el pago de un artículo de pago de la tienda.

Formatos de Datos Clave

• ​**GameItem (Información del Artículo)**​: { itemId: string, amount: number }
• ​**GameItemChange (Información de Cambio)**​: { itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 Obtener Lista de Artículos Poseídos

// Obtener la lista de artículos poseídos por el jugador (llamar durante la inicialización del juego)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('Artículos poseídos:', items);

2.2 Abrir Ventana de Compra de Artículos

// Abrir ventana de compra de artículos
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 Añadir Artículo

// Añadir artículo (ID: 3232addasdda3aa2, cantidad: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 Reducir Artículo

// Reducir artículo (ID: 3232addasdda3aa2, cantidad: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 Suscribirse a Notificaciones de Cambio de Artículos

// Suscribirse a notificaciones de cambio de artículos
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('Cambio de artículo:', res);
});

2.6 Flujo Completo de Compra de Artículos de Pago

// 1. Iniciar compra de artículo de pago (ID de producto: item_gold_100, corresponde al artículo de 100 monedas de oro)
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('Pedido creado exitosamente, número de pedido:', orderNo);
  } catch (err) {
    console.error('Error al crear el pedido:', err);
    alert('Error al iniciar la compra, por favor intente nuevamente más tarde');
  }
}

// 2. Suscribirse a notificación de pago exitoso (llamar durante la inicialización del juego)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('Pago exitoso, detalles del pedido:', order);
  if (order.status === 'success') {
    // 3. Distribuir el artículo correspondiente (ID de producto: item_gold_100 corresponde al ID de artículo: 3232addasdda3aa2)
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. Notificar a la plataforma el envío (debe llamarse, de lo contrario el estado del pedido será anómalo)
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('¡Compra de 100 monedas de oro exitosa, han sido enviadas al inventario!');
  }
});

// 3. Escenario de excepción: Consultar detalles del pedido (por ejemplo, si no se recibe el artículo después del pago)
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('Consulta de detalles del pedido:', order);
    if (order.status === 'success') {
      // Re-distribuir artículo
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('Error al consultar el pedido:', err);
  }
}

2.7 Distribución de Artículos Activada por Progreso del Juego (Ejemplo: Recompensa por Pasar un Nivel)

// Pasar el nivel 10 activa la distribución de artículos (incluye lógica de desduplicación para evitar reclamos repetidos)
function onLevel10Clear() {
  // Juego individual: usar almacenamiento local para registrar el estado de distribución
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('La recompensa de este nivel ya ha sido reclamada, no se puede reclamar nuevamente');
    return;
  }

  // Distribuir artículo (ID: 3232addasdda3aa2, cantidad: 10)
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // Registrar estado de distribución
  localStorage.setItem('level10_award_issued', 'true');
  alert('¡Nivel 10 pasado exitosamente! Obtuviste 10 artículos de recompensa');
}