Pular para o conteúdo principal

Jogos Mini

Acessando o Jogo Mini como uma Recompensa​

info

Para esta seção, o processo será descrito usando o SDK em typescript. Se você tiver alguma dúvida, não hesite em entrar em contato com seu Representante de Sucesso do Cliente ou solicitar ajuda em um de nossos canais de suporte.

Assim que o usuário tiver cumprido os requisitos para ganhar o jogo mini (concluído uma missão, ganho um torneio, subido de nível, etc.), o jogo é oferecido como recompensa.

Para verificar seu status, você pode usar o método getPlayerRewards do RewardsProcessor.

const { RewardsProcessor } = GamanzaEngageWebClientSDK.getInstance();

const response = await RewardsProcessor.getPlayerRewards({
  limit: 25,
  page: 2,
  playerId: payload.playerId,
  rewardType: RewardTypeEnum.MINI_GAME,
  status: [
    RewardStatusEnum.IN_PROGRESS,
    RewardStatusEnum.PENDING,
    RewardStatusEnum.BOUNCED,
  ],
});

Isso retornará uma lista paginada das recompensas do tipo "mini_game" que se parece com isso

{"docs":[{"_id":"68e6c87e1b9f805ed842fe9d","status":"in_progress","playerId":"Ryder_Kuvalis","date":"2025-10-08T20:24:30.686Z","source":"missions","activation":"automatic","group":{"groupId":"c1e8809d-3454-41e9-baed-4830e894c3fb","totalItems":1},"earnedReward":{"type":"mini_game","expirationValidityTime":{"timeType":"any_time"},"termsAndConditions":[],"miniGameOfferId":"68e56c07797e15c526c1adc2","miniGameOfferName":"INTERNAL NAME","translations":[{"description":"EXTERNAL DE","language":"DE"},{"description":"EXTERNAL EN","language":"EN"},{"description":"EXTERNAL FR","language":"FR"}],"brandId":"default","uniqueIdentifier":"3d34d199-5786-4b53-9359-cac4f3c4ab6d"},"metadata":{"missionId":"68e56c773eb477da71682570","bundleId":"68e56cb83eb477da71682660","missionDescription":"Mini Game Test","missionBundleExternalDetails":[],"rewardId":"68e56c773eb477da71682575","bundleStateId":"68e6c804799a173bff889ec3","missionStateId":"68e6c804799a173bff889ec5"},"trigger":"on-missions-complete","createdAt":"2025-10-08T20:24:30.690Z","updatedAt":"2025-10-08T20:24:30.701Z","__v":0,"id":"68e6c87e1b9f805ed842fe9d"}],"totalDocs":3,"limit":100,"totalPages":1,"page":1,"pagingCounter":1,"hasPrevPage":false,"hasNextPage":false,"prevPage":null,"nextPage":null}
info

A chave metadata vai variar dependendo da fonte da recompensa. Neste exemplo, a recompensa foi concedida através de uma missão, portanto, os metadados relacionados à missão.

Reivindicando o Jogo Mini​

Existe uma Bandeira de Recurso dentro das Configurações chamada "As recompensas são ativadas pelos jogadores?" que determina o primeiro status das recompensas fornecidas.

  • Se a bandeira estiver Ativada: as recompensas terão o status "não reivindicado" e precisarão ser reivindicadas para serem concedidas ao jogador.

  • Se a bandeira estiver Desativada: as recompensas serão reivindicadas automaticamente assim que forem ganhas.

Para reivindicar um jogo mini, você pode chamar o método playerClaimRewardsByGroupId (você pode encontrar o groupId dentro do objeto Reward sob group.groupId)

const { RewardsProcessor } = GamanzaEngageWebClientSDK.getInstance();

const response = await RewardsProcessor.playerClaimRewardsByGroupId(groupId);

Entregando o Jogo​

Para entregar o jogo, você precisará gerar uma URL exclusiva. Para isso, o jogo deve estar em um estado jogável (in_progress, bounced), caso contrário, você receberá uma resposta de erro.

Use o método generatePlayerMiniGameRewardLaunchUrl do SDK para isso, todos os parâmetros estão disponíveis dentro da resposta rewards que você obteve anteriormente.

const { MiniGames } = GamanzaEngageWebClientSDK.getInstance();

const myGame = docs[0].earnedReward;

const result = await MiniGames.generatePlayerMiniGameRewardLaunchUrl(
  myGame.miniGameOfferId,
  uniqueIdentifier
);

if (result.ok) {
  const url = result.data.url;
}

A URL recebida é composta por uma URL principal e um parâmetro de token.

atenção

Não modifique o token, pois ele é necessário pelo jogo para carregar corretamente.

  • Esse URL pode ser usado em qualquer navegador ou iframe para acessar a oferta do jogo e jogar o jogo!
MinijogoMinijogo

  • O token tem expiração de 1 hora, portanto não é ideal gerá-lo com antecedência, ele deve ser gerado no momento em que o jogador quiser jogar.

  • O URL contém alguns dados codificados que o jogo precisa para ser iniciado, incluindo a URL da API que ele precisa chamar para carregar suas configurações e enviar os resultados, certifique-se de ter a URL correta configurada em suas configurações de administrador em Recursos Principais → API Frontend:

    MinijogoMinijogo

Suporte a múltiplos idiomas​

O Minijogo consome uma lista de traduções de texto do backend. O jogo pode ser iniciado usando qualquer um dos idiomas disponíveis usando um parâmetro de consulta no URL do jogo: ?lang=EN

  • Quando nenhuma consulta de idioma estiver presente, o idioma padrão é definido como Inglês

  • Usamos o padrão ISO 639-1, que usa códigos de duas letras. Você pode encontrar a lista aqui

  • Você pode ver os idiomas disponíveis na resposta à solicitação de inicialização, dentro do objeto de skin

  • Para adicionar um novo idioma aos disponíveis, entre em contato com o Suporte ao Cliente. (Essas traduções poderão ser editadas pelo portal de administração em uma próxima atualização!)

Reivindicando recompensas do jogo​

Após concluir com sucesso um jogo, o jogador será apresentado à opção de Reivindicar ou Recusar suas recompensas. Uma vez reivindicadas, elas serão movidas para o inventário do jogador.

Reivindicar MinijogoReivindicar Minijogo

Se recusadas, as recompensas não ficarão acessíveis ao jogador, mas os administradores poderão ver o status recusado no Cartão do Jogador.

Itens recusados em Minhas RecompensasItens recusados em Minhas Recompensas

Se o jogador fechar o jogo antes de reivindicar suas recompensas ou perder a conexão, as recompensas permanecerão não reivindicadas no banco de dados e podem ser reivindicadas manualmente por um administrador por meio do cartão do jogador ou da API usando o groupId das recompensas como parâmetro (da mesma forma que você reivindica o Minijogo quando premiado)

const { RewardsProcessor } = GamanzaEngageWebClientSDK.getInstance();

const response = await RewardsProcessor.playerClaimRewardsByGroupId(groupId);
Opção de Reivindicação Manual em Minhas RecompensasOpção de Reivindicação Manual em Minhas Recompensas

Fechando o jogo​

Assim que as Recompensas forem Reivindicadas ou Recusadas, o jogo apresentará ao jogador um botão "Fechar Jogo", este botão se comporta de maneira diferente dependendo de como o jogo foi iniciado:

  • Se o jogo for lançado dentro de um iFrame, ele sinalizará seu pai com uma mensagem "GAME_OVER", que pode ser usada para fechar ou destruir o iFrame, aqui está um exemplo de um aplicativo React ouvindo a mensagem:
useEffect(() => {
  const handleMessage = (event: MessageEvent) => {
    if (event.data?.type === "GAME_OVER") {
      // Lógica para destruir o iFrame fica aqui
    }
  };
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []);

  • Se o jogo estiver em uma janela do navegador autônoma, ele chamará window.close() que fechará a janela ou aba se

    • Foi aberto usando window.open()
    • Foi aberto via conteúdo da web