Este guia detalha a integração de funcionalidades essenciais para o desevnolvimento de mini-jogos na plataforma Alipay, focando no uso da API do objeto my.

Preparação do Ambiente de Desenvolvimento

1. Ferramenta de Desenvolvimento Alipay

• Baixe e instale a ferramenta de desenvolvimento de mini-aplicativos Alipay.
• Crie um novo projeto de mini-jogo.
• Configure as informações básicas do seu jogo.

2. Solicitação de Permissões

• Solicite as permissões de mini-jogo na Plataforma Aberta Alipay.
• Configure permissões de pagamento e acesso a informações do usuário.
• Obtenha o AppID e outros parâmetros necessários.

Implementação de Funcionalidades Principais

1. Autenticação de Usuário

A autenticação é crucial para identificar o usuário. Utilizamos my.getAuthCode para obter um código de autorização, que é a base para a validação da identidade do usuário.

async function autenticarUsuario() {
 try {
   console.log('Iniciando autenticação de usuário no mini-jogo Alipay...');
   
   const resultadoAutenticacao = await new Promise((resolve, reject) => {
     my.getAuthCode({
       scopes: 'auth_base', // Utiliza escopo de autorização básico
       success: function(res) {
         console.log('my.getAuthCode - Sucesso:', res);
         resolve({
           codigoAutorizacao: res.authCode || '',
           escoposSucesso: res.authSuccessScopes || [],
           escoposFalha: res.authErrorScopes || {},
           codigo: res.authCode || '' 
         });
       },
       fail: function(err) {
         console.error('my.getAuthCode - Falha:', err);
         reject(err);
       }
     });
   });

   if (resultadoAutenticacao && resultadoAutenticacao.codigo) {
     console.log('Autenticação bem-sucedida. Código de autorização:', resultadoAutenticacao.codigo);
     // Envie este código para o seu servidor para validação
     // O servidor pode retornar um ID de usuário após a verificação
     return {
       sucesso: true,
       codigoAutorizacao: resultadoAutenticacao.codigo,
       mensagem: 'Autenticação realizada com sucesso'
     };
   } else {
     return {
       sucesso: false,
       mensagem: 'Falha na autenticação'
     };
   }
 } catch (error) {
   console.error('Erro na autenticação Alipay:', error);
   return {
     sucesso: false,
     mensagem: 'Erro durante a autenticação'
   };
 }
}
 

2. Processamento de Pagamentos

O pagamento é uma fonte de receita vital. A função my.requestGamePayment é utilizada para implementar esta funcionalidade. É importante verificar a compatibildiade da versão do Alipay antes de prosseguir.

// Função para comparar versões de software
function compararVersao(versaoAtual, versaoComparacao) {
 const v1 = versaoAtual.split('.').map(Number);
 const v2 = versaoComparacao.split('.').map(Number);
 const tamanho = Math.max(v1.length, v2.length);
 
 for (let i = 0; i < tamanho; i++) {
   const n1 = v1[i] || 0;
   const n2 = v2[i] || 0;
   if (n1 > n2) return 1;
   if (n1 < n2) return -1;
 }
 return 0;
}

// Obtém informações do sistema
function obterInfoSistema() {
 return my.getSystemInfoSync();
}

// Implementa a funcionalidade de pagamento no jogo
async function processarPagamentoJogo(informacoesPedido) {
 try {
   const infoSistema = obterInfoSistema();
   console.log('Versão do Alipay:', infoSistema.version);
   
   // O recurso de pagamento requer a versão 10.3.90 ou superior do Alipay
   if (compararVersao(infoSistema.version || "0", "10.3.90") <= 0) {
     console.log('Pagamento não suportado nesta versão.');
     return {
       sucesso: false,
       mensagem: 'O Alipay atual não suporta pagamentos. Por favor, atualize seu aplicativo.'
     };
   }
   
   console.log('Iniciando processo de pagamento no mini-jogo Alipay:', informacoesPedido);
   
   // Monta os parâmetros de pagamento
   const parametrosPagamento = {
     buyQuantity: informacoesPedido.quantidade_compra, 
     customId: informacoesPedido.id_pedido,        
     extraInfo: {
       ext: informacoesPedido.ext                 
     }
   };

   console.log('Parâmetros de pagamento Alipay:', parametrosPagamento);

   // Chama a API de pagamento do Alipay
   await new Promise((resolve, reject) => {
     my.requestGamePayment({
       ...parametrosPagamento,
       success: function() {
         console.log('Pagamento Alipay concluído com sucesso.');
         resolve({
           sucesso: true,
           mensagem: 'Pagamento realizado com sucesso',
           idPedido: informacoesPedido.id_pedido
         });
       },
       fail: function(res) {
         console.log('Pagamento Alipay falhou:', res);
         
         // Tratamento para restrições de menores
         if (res.error == 15215) {
           my.showModal({
             title: 'Aviso',
             content: 'Devido às regulamentações sobre a prevenção do vício em jogos online para menores, o Alipay restringe recargas para menores. Por favor, verifique suas configurações.',
             showCancel: false,
             confirmText: 'Entendi',
             success: function() {
               reject({
                 sucesso: false,
                 mensagem: 'Restrição para menores',
                 codigoErro: res.error
               });
             }
           });
           return;
         }
         
         reject({
           sucesso: false,
           mensagem: `Pagamento falhou: ${res.errorMessage || res.error || 'Erro desconhecido'}`,
           codigoErro: res.error
         });
       }
     });
   });
   
 } catch (error) {
   console.error('Erro no processamento do pagamento Alipay:', error);
   return {
     sucesso: false,
     mensagem: 'Erro ao processar pagamento'
   };
 }
}
 

3. Verificação de Segurança de Texto

Para garantir um ambiente seguro, implementamos a verificação de conteúdo gerado pelo usuário.

// Verifica a segurança do texto
async function verificarSegurancaTexto(texto, idUsuario) {
 try {
   console.log('Iniciando verificação de texto para Alipay:', texto);
   
   // Chama sua API de backend para verificação
   const resposta = await fetch('/api/verificacao-texto', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
       terceiro_uid: idUsuario,
       conteudo: texto,
       canal: 'zfb'
     })
   });
   
   const resultado = await resposta.json();
   console.log('Resposta da verificação de texto Alipay:', resultado);
   
   // Assume que o código 0 indica aprovação
   const seguro = resultado.code === 0;
   console.log('Resultado da verificação de texto Alipay:', seguro);
   
   return seguro;
 } catch (error) {
   console.error('Erro na verificação de texto Alipay:', error);
   return false; // Em caso de erro, considera-se inseguro por padrão
 }
}

// Exemplo de uso
async function enviarMensagemChat(mensagem, idUsuario) {
 const seguro = await verificarSegurancaTexto(mensagem, idUsuario);
 if (seguro) {
   console.log('Mensagem enviada com sucesso.');
 } else {
   my.showToast({
     content: 'A mensagem contém conteúdo sensível. Por favor, revise.',
     type: 'none'
   });
 }
}
 

4. Relatório de Informações de Personagem

É necessário reportar periodicamente as informações do personagem do jogador para fins operacionais.

let ultimoTimestampNivel = 0; // Limita a frequência de relatórios de nível

// Reporta informações do personagem
async function reportarInfoPersonagem(infoPersonagem) {
 try {
   console.log('Reportando informações de personagem para Alipay:', infoPersonagem);
   
   // Limitação de frequência para relatórios de nível (apenas um por minuto)
   if (infoPersonagem.tipo_dado === 3) { // 3 indica relatório de nível
     const agora = Date.now();
     if (agora - ultimoTimestampNivel < 60000) {
       console.log('Relatório de nível limitado pela frequência. Aguardando...');
       return { sucesso: false, mensagem: 'Aguardando...' };
     }
     ultimoTimestampNivel = agora;
   }

   // Chama a API de backend para reportar
   const resposta = await fetch('/api/reportar-personagem', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
       ...infoPersonagem,
       canal: 'zfb'
     })
   });
   
   const resultado = await resposta.json();
   console.log('Resultado do relatório de personagem:', resultado);
   
   return resultado;
 } catch (error) {
   console.error('Erro ao reportar informações de personagem Alipay:', error);
   return { sucesso: false, mensagem: 'Erro no relatório' };
 }
}

// Exemplo de uso
async function aoSubirNivelJogador(novoNivel) {
 await reportarInfoPersonagem({
   tipo_dado: 3,        
   id_personagem: 'jogador_001',
   nome_personagem: 'Nome do Jogador',
   nivel_personagem: novoNivel,
   id_servidor: 'servidor_001',
   nome_servidor: 'Nome do Servidor'
 });
}
 

Uso Comum de APIs

1. Exibição de Mensagens

// Exibe um popup modal
function mostrarAlerta(titulo, conteudo) {
 my.showModal({
   title: titulo,
   content: conteudo,
   showCancel: false,
   confirmText: 'OK',
   success: function() {
     console.log('Usuário confirmou o alerta.');
   }
 });
}

// Exibe uma notificação Toast
function mostrarToast(mensagem) {
 my.showToast({
   content: mensagem,
   type: 'none',
   duration: 2000
 });
}
 

2. Armazenamento de Dados

// Salva dados no armazenamento local
function salvarDadosJogo(chave, dados) {
 my.setStorage({
   key: chave,
   data: dados,
   success: function() {
     console.log('Dados salvos com sucesso.');
   },
   fail: function(err) {
     console.error('Falha ao salvar dados:', err);
   }
 });
}

// Carrega dados do armazenamento local
function carregarDadosJogo(chave) {
 return new Promise((resolve, reject) => {
   my.getStorage({
     key: chave,
     success: function(res) {
       resolve(res.data);
     },
     fail: function(err) {
       reject(err);
     }
   });
 });
}
 

3. Requisições de Rede

// Realiza uma requisição HTTP
async function requisicaoHttp(url, dados) {
 try {
   const resposta = await new Promise((resolve, reject) => {
     my.request({
       url: url,
       method: 'POST',
       data: dados,
       header: {
         'Content-Type': 'application/json'
       },
       success: function(res) {
         resolve(res);
       },
       fail: function(err) {
         reject(err);
       }
     });
   });
   
   return resposta.data;
 } catch (error) {
   console.error('Falha na requisição de rede:', error);
   throw error;
 }
}
 

Melhores Práticas de Tratamento de Erros

1. Verificação de Compatibilidade de API

// Verifica se uma API é suportada
function verificarSuporteAPI(nomeAPI) {
 if (my.canIUse(nomeAPI)) {
   return true;
 } else {
   console.warn(`O ambiente atual não suporta ${nomeAPI}.`);
   return false;
 }
}

// Exemplo de uso
if (verificarSuporteAPI('showActionSheet')) {
 my.showActionSheet({
   itemList: ['Opção 1', 'Opção 2', 'Opção 3'],
   success: function(res) {
     console.log('Usuário selecionou:', res.tapIndex);
   }
 });
} else {
 // Implementar fallback
 console.log('showActionSheet não suportado. Usando método alternativo.');
}
 

2. Captura de Exceções

// Tratamento unificado de erros
function tratarErro(erro, contexto) {
 console.error(`Erro em ${contexto}:`, erro);
 
 // Opcionalmente, reporte o erro para um serviço de monitoramento
 // reportarErro(erro, contexto);
 
 // Exiba uma mensagem amigável ao usuário
 my.showToast({
   content: 'Ocorreu um erro. Por favor, tente novamente.',
   type: 'none'
 });
}

// Exemplo de uso
try {
 await autenticarUsuario();
} catch (erro) {
 tratarErro(erro, 'Autenticação de Usuário');
}
 

Dicas de Debugging

1. Saída de Logs

// Logs para ambiente de desenvolvimento
const DEBUG_ATIVO = true;

function logDebug(mensagem, dados) {
 if (DEBUG_ATIVO) {
   console.log(`[DEBUG] ${mensagem}`, dados);
 }
}

// Exemplo de uso
logDebug('Iniciando autenticação de usuário', { timestamp: Date.now() });