Scripts de gatilho

Neste artigo você vai aprender a usar scripts nos componentes do dispositivo de emissão de tickets. Um script é um pequeno código JavaScript que o totem executa quando algo acontece com o componente, como quando o cidadão toca em um botão ou quando um campo precisa ser validado.

Com scripts, é possível mostrar avisos ao cidadão, consultar sistemas externos, guardar informações e decidir para qual tela o totem deve ir.

Onde criar um script

1. Abra Configuração → Canais → Presencial → Editor de dispositivo de emissão e entre no dispositivo desejado.
2. Selecione um componente na tela, como botão, texto, imagem, campo de texto ou teclado numérico.
3. No painel de propriedades, abra a seção Script.
4. Clique em Adicionar gatilho, informe o nome do gatilho e escolha o evento em que o script deve executar.
5. Clique em Editar script, escreva o código e confirme.
6. Salve o dispositivo. Use o modo Testar para validar o comportamento antes de enviar a configuração ao totem real.

Eventos disponíveis

O evento Validar permite bloquear o avanço do cidadão quando o valor digitado não é aceito.

O que o script pode usar

Todo script recebe um contexto com os objetos abaixo. Eles estão disponíveis diretamente pelo nome e não é necessário importar nada.

O script é executado como uma função assíncrona. Por isso, é possível usar await para aguardar respostas de http e alert.

vars — variáveis do totem

Leia uma variável usando:

vars.nomeDaVariavel

Grave uma variável usando:

vars.nomeDaVariavel = valor

O que o script gravar em vars permanece disponível para os próximos scripts e é enviado ao fluxo de atendimento vinculado ao componente.

As variáveis também podem ser criadas sem script, na seção Variáveis do componente. No campo de texto, o valor digitado pelo cidadão é guardado na variável informada em Nome da variável e fica disponível para os scripts e para o fluxo.

http — chamadas externas

Todas as chamadas devolvem status e body. Quando a resposta não é de sucesso, a chamada gera um erro com status e body. Use try/catch para tratar esse cenário.

alert — avisos na tela

navigation — ir para outra tela

Grave em navigation.go o nome exato de uma tela do dispositivo.

navigation.go = 'Tela Agradecimento';

Quando o script termina, o totem vai para essa tela. Se o nome não corresponder a nenhuma tela existente, o totem permanece onde está.

Regra do valor de retorno

O valor devolvido pelo script com return controla o que acontece em seguida.

Por isso, a convenção recomendada é terminar scripts de clique com return true; e, na validação, devolver o texto do erro quando o valor informado não for aceito.

Exemplos práticos

1. Mostrar uma mensagem de boas-vindas e navegar

Gatilho Clique em um botão:

alert.success('Bem-vindo!', 'Seu atendimento foi solicitado.');
navigation.go = 'Tela Agradecimento';
return true;

2. Validar o que o cidadão digitou

Gatilho Validar em um campo de texto ou teclado numérico. O valor digitado chega em input.value:

if (!input.value || input.value.trim().length < 5) {
  return 'Digite um código com pelo menos 5 caracteres.';
}

return true;

Enquanto o retorno for um texto, o totem mostra o aviso e não avança. Quando o valor é aceito, o script devolve true.

3. Guardar o valor digitado para usar no fluxo

Gatilho Validar em um campo de código:

if (!input.value || input.value.trim() === '') {
  return 'Informe o código de atendimento.';
}

vars.codigoDigitado = input.value.trim();
return true;

A variável codigoDigitado passa a ficar disponível para outros scripts e para o fluxo de atendimento vinculado ao componente.

4. Consultar um sistema externo antes de continuar

Gatilho Clique em um botão de consulta:

try {
  const resposta = await http.post('https://api.suaorganizacao.gov.br/consulta', {
    codigo: vars.codigoDigitado
  });

  vars.nomeCidadao = resposta.body.nome;
  vars.temAtendimento = resposta.body.encontrado;

  if (resposta.body.encontrado) {
    navigation.go = 'Tela Confirmacao';
  } else {
    alert.error('Atendimento não localizado', 'Confira o código e tente novamente.');
  }

  return true;
} catch (erro) {
  alert.error('Falha na consulta', 'Tente novamente em instantes.');
  return false;
}

5. Pedir confirmação antes de agir

Gatilho Clique em um botão de cancelamento:

const resposta = await alert.question('Deseja realmente cancelar este atendimento?', {
  title: 'Confirmação',
  confirm: 'Sim, cancelar',
  cancel: 'Voltar'
});

if (!resposta.isConfirmed) {
  return false;
}

navigation.go = 'Tela Inicial';
return true;

6. Navegação condicional por tipo de atendimento

Gatilho Clique em um botão que decide o caminho:

if (vars.preferencial === true) {
  navigation.go = 'Tela Preferencial';
} else {
  navigation.go = 'Tela Geral';
}

return true;

7. Contador de toques em uma tela

Gatilho Clique em uma imagem ou texto usado como botão:

vars.tentativas = (vars.tentativas || 0) + 1;

if (vars.tentativas >= 3) {
  alert.error('Muitas tentativas', 'Procure um atendente no balcão.');
  navigation.go = 'Tela Inicial';
  return false;
}

return true;

Como combinar scripts e ações do componente

Ao acionar um componente, o totem executa, nesta ordem:

1. Gatilhos com script — na ordem cadastrada. O primeiro que falhar interrompe a execução.
2. Fluxo de atendimento vinculado ao componente.
3. Ações configuradas do componente, como gravar variáveis, navegar, emitir evento e reiniciar.

Na prática, use o script para decidir e preparar dados, principalmente por meio de vars e navigation.go. Use as ações do componente para comportamentos fixos, como tela de destino, valores de variáveis e reinicialização.

Quando o script definir navigation.go, a navegação definida pelo script prevalece no destino.

Testando os scripts

• Use o botão Testar do editor para abrir a pré-visualização e executar a configuração atual, incluindo os scripts.
• Durante o teste, o painel Debug mostra a resolução, as variáveis em uso e os eventos acionados. Isso ajuda a verificar se o script gravou os valores esperados em vars.
• Teste também em um dispositivo real antes de publicar a configuração.

Boas práticas

• Termine scripts de clique com return true quando a execução puder continuar. Sem retorno, o totem interrompe as ações do componente silenciosamente.
• Use mensagens de erro curtas e claras na validação, pois são exibidas diretamente ao cidadão.
• Use try/catch em chamadas http e trate as falhas para evitar que o cidadão fique preso na tela.
• Use nomes de tela exatos ao definir navigation.go. O nome precisa corresponder à tela cadastrada.
• Não coloque segredos no script, como chaves de API e senhas. O script é executado no navegador do totem e pode ser lido por quem tiver acesso ao dispositivo.
• Prefira as ações configuráveis quando não houver condição envolvida. Use scripts principalmente para decisões e operações que dependem de dados.
• Valide os valores antes de usá-los. input.value pode estar vazio e uma variável pode ainda não existir.