Sistema de Itens e Loja de Pagamentos da Plataforma

Este sistema fornece uma solução unificada de gerenciamento de itens pagos para a plataforma de jogos, suportando funções como compra, distribuição e estatísticas de itens para jogos standalone, implementando as funcionalidades de compra, consulta, adição/redução de itens e distribuição acionada pelo progresso do jogo.

• Funcionalidades principais: Compra de itens, Consulta de posse, Operações de adição/redução, Monitoramento de alterações, Distribuição acionada pelo progresso do jogo.

1. Funcionalidades de Gerenciamento no Backend para Desenvolvedores

• Os desenvolvedores podem criar manualmente dados de itens através do backend, com suporte para upload de tabelas (tabela de unidades de itens) e ícones de itens.
• Itens pagos para a loja atualmente suportam apenas criação manual.
• Suporta a criação de até 5000 entradas de dados de itens.
• Atualmente suporta apenas jogos do tipo compra única e compras internas (in-app purchases).
• Itens criados precisam passar por aprovação; após aprovados, entram no estado ativado por padrão.

Funcionalidades de Gerenciamento de Itens:

‌ID do Item‌: Identificador único, não modificável após a criação.
‌Nome e Ícone do Item‌: Usados para exibição no frontend.
‌Ícone do Item‌: Suporta alteração manual da imagem do Ícone.
‌Regras de Criação de Itens: Suporta seleção entre Item de Jogo e Item Pago para Loja.
Restrições do Item: Suporta configuração de limites para distribuição aos jogadores através da plataforma, como limite de quantidade diária, limite de quantidade total ou sem limite.
‌Estoque de Itens‌: Pode optar por inserir uma quantidade ou não definir limite.
Configuração de Valor do Item:
Item Gratuito (Atividades da Plataforma): Compatível com distribuição em atividades da plataforma.
Compra Paga (Compra Paga): Compatível com compra paga na loja de itens.
Valorado em Dólares Americanos (USD) por padrão.
O preço unitário do item suporta precisão de até 0.0001 USD.
O valor mínimo de entrada para itens pagos na loja é 1 USD.

Sugestão

• Primeiro registre as unidades de itens, depois insira manualmente os itens para compra paga na loja; suporta selecionar um ou múltiplos itens para formar um produto conjunto para venda.
• Quando um item é configurado como gratuito, a plataforma pode optar por distribuí-lo aos jogadores de acordo com os planos de operação; será entregue ao personagem do jogador no jogo quando ele entrar.

2. Integração do SDK de Itens

Descrição das Interfaces Principais

Nome da Interface	Assinatura do Método	Descrição da Funcionalidade
Abrir Janela de Compra	openBuyGameItemsDialog(level: number)	Abre uma janela de diálogo de compra de itens da loja através da UI funcional dentro do jogo.
Obter Itens Possuídos	getUserGameItems(): GameItem[]	Consulta a lista atual de itens do jogador ao entrar no jogo (inclui ID e quantidade).
Adicionar Item	addGameItem(itemId: string, amount: number)	Distribui itens durante o progresso do jogo (compatível com cenários como compras, recompensas de fases, conclusão de missões, etc.).
Reduzir Item	subtractGameItem(itemId: string, amount: number)	Consome itens (cenários de uso ou consumo durante o progresso do jogo, a quantidade após a dedução não será negativa).
Subscrever para Notificações de Alteração	subscribeGameItemChange(callback: (res: GameItemChange) => void)	Método de callback executado quando o pagamento de um item pago da loja é concluído.

Formatos de Dados Chave

• ​**GameItem (Informação do Item)**​: { itemId: string, amount: number }
• ​**GameItemChange (Informação de Alteração)**​: { itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 Obter Lista de Itens Possuídos

// Obter a lista de itens possuídos pelo jogador (chamado durante a inicialização do jogo)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('Itens possuídos:', items);

2.2 Abrir Janela de Compra de Itens

// Abrir janela de compra de itens
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 Adicionar Item

// Adicionar item (ID: 3232addasdda3aa2, quantidade: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 Reduzir Item

// Reduzir item (ID: 3232addasdda3aa2, quantidade: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 Subscrever para Notificações de Alteração de Itens

// Subscrever para notificações de alteração de itens
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('Alteração de item:', res);
});

2.6 Fluxo Completo de Compra de Itens Pagos

// 1. Iniciar compra de item pago (ID do produto: item_gold_100, corresponde ao item de 100 moedas de ouro)
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('Pedido criado com sucesso, número do pedido:', orderNo);
  } catch (err) {
    console.error('Falha ao criar pedido:', err);
    alert('Falha ao iniciar compra, por favor tente novamente mais tarde');
  }
}

// 2. Subscrever para notificação de pagamento bem-sucedido (chamado durante a inicialização do jogo)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('Pagamento bem-sucedido, detalhes do pedido:', order);
  if (order.status === 'success') {
    // 3. Distribuir o item correspondente (ID do produto: item_gold_100 corresponde ao ID do item: 3232addasdda3aa2)
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. Notificar a plataforma da entrega (deve ser chamado, caso contrário o estado do pedido ficará anômalo)
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('Compra de 100 moedas de ouro bem-sucedida, foram enviadas para a mochila!');
  }
});

// 3. Cenário de exceção: Consultar detalhes do pedido (por exemplo, se o item não for recebido após o pagamento)
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('Consulta de detalhes do pedido:', order);
    if (order.status === 'success') {
      // Re-distribuir item
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('Falha ao consultar pedido:', err);
  }
}

2.7 Distribuição de Itens Acionada pelo Progresso do Jogo (Exemplo: Recompensa por Concluir Fase)

// Concluir a fase 10 aciona a distribuição de itens (inclui lógica de deduplicação para evitar resgates repetidos)
function onLevel10Clear() {
  // Jogo standalone: usar armazenamento local para registrar o estado de distribuição
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('A recompensa desta fase já foi resgatada, não pode ser resgatada novamente');
    return;
  }

  // Distribuir item (ID: 3232addasdda3aa2, quantidade: 10)
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // Registrar estado de distribuição
  localStorage.setItem('level10_award_issued', 'true');
  alert('Fase 10 concluída com sucesso! Ganhou 10 itens de recompensa');
}