Pular para o conteúdo principal

Configuração

A configuração deve ter o seguinte formato com os respectivos valores de propriedades (alguns são obrigatórios, outros são opcionais), estes serão especificados mais adiante neste documento:

  const config = {
    init: {...},
    player: {...},
    lookAndFeel: {...},
    translations: [...],
    assets: {...}
  }

1. Inicializar (init <object|obrigatório>))​

  • serviceUrl <string|obrigatório>: URL onde os endpoints virão
  • clientId <string|obrigatório>: este é o token respectivo para acessar a URL do serviço
  • playerIdentityToken <string|obrigatório>: refere-se ao token de identidade do jogador para validar a sessão. Consulte Validar Token de Identidade do Jogador para mais detalhes.
  • playerLocale <string|obrigatório>: idioma do jogador. (Usamos o padrão ISO 639-1, que usa códigos de duas letras. Você pode encontrar a lista aqui)

Exemplo:

init: {
  serviceUrl: 'https://{unique-client-sub-domain-fe-api}.gamanzaengage.com',
  clientId: '8a5cd40a-5e37-45b1-b2e0-9e2fe0921786',
  playerIdentityToken: '{playerSessionID|JWT|IdentityToken}',
  playerLocale: 'de',
},

2. Jogador (player <object|opcional>))​

  • name <string|opcional>: nome do jogador
  • shippingAddress <object|opcional>:
    • city <string|obrigatório>: nome da cidade do jogador
    • country <string|obrigatório>: país do jogador
    • street <string|obrigatório>: nome da rua do jogador
    • streetNumber <string|obrigatório>: número da rua do jogador
    • postalCode <string|obrigatório>: código postal do jogador
    • houseNameOrNumber <string|obrigatório>: nome ou número da casa do jogador
  • playerPhone: <string|obrigatório>: número de telefone do jogador
  • playerEmail: <string|obrigatório>: email do jogador
  • countries?: <string[]|opcional>: países disponíveis para o cliente

Nota: as propriedades shippingAddress e countries são usadas apenas na loja de recompensas, onde o jogador adiciona seu endereço para entrega de recompensas. O formato ISO 3166 deve ser usado. Se nenhum país for especificado, então o menu suspenso mostrará TODOS os países.

Exemplo:

Mostre-me o código!
player: {
  name: 'Jogador Teste',
  shippingAddress: {
    city: 'Alajuela',
    country: 'CR',
    street: 'Rua Teste',
    streetNumber: '23',
    postalCode: '211101',
  },
  countries: ['DE', 'FR', 'IT'],
},

3. Aparência (lookAndFeel <object|opcional>))​

O objeto lookAndFeel permite substituir alguns dos estilos e cores padrão do aplicativo.

  • Tipografia:
    • fontFamily <string|optional>: o padrão é Roboto, Helvetica, Arial, sans-serif. A fontFamily especificada deve estar instalada no computador do jogador para que eles possam vê-la com sucesso.
  • Paleta:
    • primária:
      • principal <string|required>: esta cor pode ser adicionada para destacar as seções principais e os ícones nos widgets

Se você não deseja personalizar os widgets, eles vêm com uma cor roxa padrão (#8743FF):

Cor Padrão 1Cor Padrão 1 Cor Padrão 2Cor Padrão 2 Cor Padrão 3Cor Padrão 3

Exemplo com tipografia e cor principal diferentes:

Mostre-me o código!
lookAndFeel: {
  typography: {
    fontFamily: '"Times New Roman"',
  },
  palette: {
    primary: {
      main: '#C10230',
    },
  },
},
Cor Vermelha 1Cor Vermelha 1 Cor Vermelha 2Cor Vermelha 2 Cor Vermelha 3Cor Vermelha 3

Além disso, se você quiser implementar um tema escuro, tudo o que você precisa fazer é adicionar o mode prop à paleta em lookAndFeel

  • Paleta:
    • mode: <string|optional>: light ou dark

Exemplo com tema escuro e cor principal:

lookAndFeel: {
  ...,
  palette: {
    mode: 'dark',
    primary: {
      main: '#5e9221',
    },
  },
},
Tema Escuro 1Tema Escuro 1 Tema Escuro 2Tema Escuro 2 Tema Escuro 3Tema Escuro 3
OBSERVAÇÃO

Você deve ter cuidado especial ao escolher a cor principal para garantir que os ícones e os textos apareçam corretamente.

Recomendamos experimentar várias cores e navegar pelo seu site antes de escolher a final.

Por exemplo, se você usar o branco como a cor principal com o tema escuro, alguns ícones e textos podem ser perdidos

Cor Branca 1Cor Branca 1 Cor Branca 2Cor Branca 2 Cor Branca 3Cor Branca 3

Outras propriedades customizáveis opcionais são cores de plano de fundo e de texto, e cores para as propriedades error, success e warning:

  • Paleta:
    • plano de fundo:
      • padrão <string|opcional>: este é usado para o plano de fundo principal no corpo
      • papel <string|opcional>: este é usado para o plano de fundo na vitrine de recompensas e nos widgets que precisamos destacar
    • texto:
      • primário <string|opcional>: cor usada para textos primários
      • secundário <string|opcional>: cor usada para textos secundários
    • erro:
      • principal <string|opcional>: essa cor é usada para representar elementos da interface que o usuário deve estar ciente
    • aviso:
      • principal <string|opcional>: essa cor é usada para representar ações potencialmente perigosas ou mensagens importantes
    • sucesso:
      • principal <string|opcional>: essa cor é usada para indicar a conclusão bem-sucedida de uma ação acionada pelo usuário

Exemplo com substituições opcionais:

Mostre-me o código!
lookAndFeel: {
  ...,
  palette: {
    ...,
    primary: {
      main: '#1585d9',
    },
    background: {
      default: '#e3f1fb',
      paper: '#baddf7',
    },
    text: {
      primary: '#004596',
      secondary: '#0362b5',
    },
    error: {
      main: '#e57373',
    },
    success: {
      main: '#81c784',
    },
    warning: {
      main: '#ffb74d',
    },
  },
}
Cor Azul 1Cor Azul 1 Cor Azul 2Cor Azul 2 Cor Azul 3Cor Azul 3

4. Traduções (traduções <array|opcional>))​

Todos os widgets são exibidos em um idioma padrão, que é o Inglês (en). Se você deseja usar outro idioma, você deve especificá-lo e as traduções correspondentes:

  • locale <string|obrigatório>: refere-se ao idioma ao qual as chaves a seguir correspondem (Usamos o padrão ISO 639-1, que usa códigos de duas letras. Você pode encontrar a lista aqui)
  • chaves <object|obrigatório>: estas são as chaves atualmente implementadas como traduções,
NOTAS
  • Algumas traduções incluem algum texto entre chaves duplas. Eles são usados para interpolar valores dinâmicos nas strings traduzidas, então o texto entre as chaves deve ser deixado como está.

Então, se, por exemplo, você estiver adicionando uma tradução em espanhol, ela deve ficar assim:

congratulationsLevelUp: Você alcançou o nível {{level}} agora.

  • Tenha em mente que existem traduções que são compartilhadas entre vários widgets, por exemplo, a loja de recompensas e as missões estão contidas no widget da barra lateral. E existem traduções genéricas que podem ser usadas em todos os widgets

  • Você pode encontrar a lista completa de chaves na seção de traduções.

  • Certifique-se de usar apenas códigos de duas letras para o local (ISO 639-1)

Exemplo:

traduções: [
  {
    locale: 'pt-BR',
    keys: {
      activate: 'Ativar',
      activateBooster: 'Ativar Booster',
      activatedSuccessfully: 'Ativado com sucesso',
      ...
      tryAgain: 'Tente novamente',
      xpPoints: 'Pontos de experiência'
    },
  },
]
IMPORTANTE

Se você alterar o idioma no navegador, certifique-se de atualizar o local configurado nos widgets.

Você pode fazer isso usando as funções reload ou reloadOne passando a prop newLocale

Consulte Métodos Disponíveis para mais detalhes.

5. Ativos (ativos <object|opcional>)​

Este objeto permite que você substitua algumas das imagens padrão nos widgets.

  • avatar_image <string|opcional>: este se refere à imagem do avatar do jogador. O padrão é mostrar a imagem da classificação atual do jogador. Se não houver imagem de classificação, ela recorrerá a esta imagem personalizada.
Imagens padrão:​
Avatar​
Avatar PadrãoAvatar Padrão
Imagens personalizadas:​
assets: {
  avatar_image: "https://e7.pngegg.com/pngimages/799/987/png-clipart-computer-icons-avatar-icon-design-avatar-heroes-computer-wallpaper.png",
}
Avatar​
Avatar PersonalizadoAvatar Personalizado

6. Exibir​

Para exibir corretamente um widget, existem duas propriedades básicas que são sempre necessárias

  • class <string|required>: deve sempre ser gamification_widget
  • data-type <string|required>: deve sempre ser uma dessas opções:
    • avatar
    • points
    • gamification-data
    • reward-shop
    • tokens
    • active-boosters
    • gamification-mechanics
    • my-boosters
    • sidebar
    • badge-level
    • missions
    • tournaments
    • rank-downgrade-minimum-activity 🆕

Exemplos:

<div class="gamification_widget" data-type="avatar"></div>
<div class="gamification_widget" data-type="reward-shop"></div>