Referência de plugins

Manifesto, ganchos, permissões e todas as funções disponíveis.

Esta página lista tudo que um plugin pode declarar e chamar. Para um passo a passo, veja Criar um plugin.

Estrutura de pastas#

%APPDATA%\Altibooth2\plugins\
    meu-plugin\
        plugin.json        <- manifesto
        principal.js       <- código
    estado.json            <- quem está ligado e o que foi configurado

O Altibooth lê duas pastas: a de fábrica, em plugins\ ao lado do Altibooth2.exe, e a do dono da cabine, em %APPDATA%\Altibooth2\plugins\. Com o mesmo id nas duas, vale a do dono da cabine. Atualizar o programa repõe a pasta de fábrica, então copie para a sua pasta o plugin que você for alterar.

O estado.json fica fora da pasta do plugin de propósito: trocar a versão do plugin não apaga a configuração de quem já usava.

Manifesto (`plugin.json`)#

Campo	Tipo	Descrição
`id`	texto	Identificador único. Vira nome de pasta e chave de estado.
`nome`	texto	Nome mostrado na tela de Plugins.
`versao`	texto	Versão do plugin.
`autor`	texto	Quem fez.
`descricao`	texto	O que ele faz. Aparece ao abrir o cartão.
`principal`	texto	Arquivo JavaScript, dentro da pasta.
`permissoes`	lista	Veja abaixo.
`configuracoes`	lista	Campos de configuração.

Campos de configuração#

Cada item de configuracoes vira um campo no formulário do plugin:

Chave	Descrição
`chave`	Nome para ler o valor com `altibooth.config("chave")`.
`nome`	Rótulo do campo.
`tipo`	`texto`, `numero`, `senha`, `booleano` ou `opcao`.
`padrao`	Valor inicial.
`opcoes`	Lista de valores, só para o tipo `opcao`.
`ajuda`	Frase curta de apoio, opcional.

Campos senha são protegidos no Windows (DPAPI, por conta de usuário) e não aparecem em logs.

Permissões#

Nome	Dá direito a
`sessao`	acompanhar e segurar o início de uma sessão
`tela`	desenhar por cima da tela da cabine
`rede`	falar com a internet
`arquivos`	ler e gravar dentro da pasta do próprio plugin e em `altibooth.dados`
`impressao`	acompanhar e cancelar impressão
`eventos`	ler a lista de eventos e as fotos da sessão

O que não for pedido não existe: altibooth.rede fica undefined para quem não pediu rede. A tela de Plugins mostra ao dono da cabine, em português, o que cada plugin pediu.

Ganchos#

Declare no principal.js só os que interessarem. O Altibooth chama os que existem.

Gancho	Quando
`aoCarregar()`	O plugin foi carregado, na abertura do programa.
`aoDescarregar()`	O programa está fechando.
`antesDaSessao()`	Alguém tocou para começar. O plugin pode segurar.
`aoCancelarCobranca(motivo)`	A sessão foi liberada por outro caminho no meio da sua cobrança, por exemplo um voucher lido. Desfaça a tentativa e saia da tela sem recado.
`aoReembolsar(motivo, sessao)`	A cabine não entregou esta sessão (a impressão falhou). Devolva o dinheiro dela.
`aoComecarSessao(eventoId, sessao)`	A sessão começou. `sessao` é o código dela.
`aoTerminarSessao(eventoId, fotos)`	A sessão terminou. `fotos` é a quantidade.
`aoTirarFoto(caminho, indice)`	Uma foto foi feita.
`antesDeImprimir(caminho)`	Vai imprimir. Devolva `false` para cancelar.
`aoSairDaTela()`	A tela da cabine foi fechada.
`aoMudarConfig()`	O dono da cabine clicou em Guardar.

API#

Tudo fica no objeto global altibooth.

Geral#

Item	Descrição
`altibooth.versao`	Versão do Altibooth.
`altibooth.idioma`	Idioma em uso.
`altibooth.log(texto)`	Escreve no log do programa.
`altibooth.config(chave)`	Valor que o dono da cabine escolheu.
`altibooth.aTempo(ms, funcao)`	Executa a função depois de `ms` milissegundos.
`altibooth.uuid()`	Gera um identificador único.
`altibooth.recado(qual)`	Texto de recado configurado pelo dono da cabine (por exemplo `"pagamento"`).
`altibooth.eventos()`	Lista `[{id, nome}]`. Precisa de `eventos`.

`altibooth.sessao`#

Item	Descrição
`evento`	Id do evento.
`eventoNome`	Nome do evento.
`chave`	Chave de acesso usada, quando houver.
`valor`	Preço da sessão em centavos. Só leitura.
`jaPago`	`true` quando a sessão veio de voucher ou chave: não há o que cobrar.
`segurar()`	Trava o início da sessão.
`liberar()`	Solta a sessão.
`recusar(motivo)`	Cancela a tentativa e mostra o motivo.
`cabineLivre()`	`true` se a cabine está parada na tela inicial e dá para desenhar.

`altibooth.tela`#

mostrar(desenho) desenha um painel por cima da tela da cabine. fechar() remove. Campos do desenho:

Campo	Descrição
`titulo`	Texto grande.
`texto`	Texto de apoio.
`qr`	Conteúdo de um QR code, desenhado pelo programa.
`imagem`	Nome de um arquivo de imagem dentro da pasta do plugin.
`botoes`	Lista `[{texto, aoClicar}]`.
`aoTocar`	Função chamada no toque em qualquer área do painel.
`valor`, `colunas`, `separador`, `rodape`	Layout de cobrança: um valor em cima e até duas colunas (`titulo`, `figura`, `qr`) lado a lado.

Chamar mostrar de novo substitui o painel atual.

`altibooth.rede.pedir(pedido, aoResponder)`#

Faz uma requisição HTTP. Precisa de rede.

altibooth.rede.pedir({
    url: "https://exemplo.com/api",
    metodo: "POST",                       // padrão GET
    corpo: "{\"a\":1}",
    cabecalhos: { "Content-Type": "application/json" },
    tempoLimiteMs: 10000
}, function (r) {
    // r.ok, r.codigo, r.corpo, r.erro
});

Redirecionamentos não são seguidos.

`altibooth.arquivo`#

Lê e grava dentro da pasta do plugin: ler(nome), gravar(nome, conteudo) e existe(nome). Recusa caminho absoluto e qualquer tentativa de sair da pasta, inclusive por ... Precisa de arquivos.

`altibooth.dados`#

Mesmas funções de arquivo, mas numa pasta gravável por usuário, separada da pasta de instalação. Gravações são atômicas. Use para o que precisa sobreviver a atualizações do plugin.

Ciclo de vida#

Ligar e desligar vale na próxima abertura do programa. A tela avisa e oferece Reiniciar agora. Cada plugin roda num motor de script próprio, e destruí-lo com o programa em uso é a parte frágil, por isso a troca espera a abertura seguinte.
Configuração vale na hora: o plugin recebe aoMudarConfig().
Erro de sintaxe no carregamento aparece na tela de Plugins com arquivo e linha, e o plugin não liga.
Erro dentro de um gancho cala o plugin na hora (nenhum gancho dele é chamado de novo) e ele nasce desligado na abertura seguinte. O motivo fica no log.

O que um plugin não alcança#

A licença do Altibooth.
A cobrança Stripe do Altibooth (chaves, recibo e conta da nuvem). O preço da sessão aparece em altibooth.sessao.valor somente para leitura, para um processador externo cobrar o mesmo valor configurado.
Programas do computador. Plugins são JavaScript dentro do Altibooth, não executam arquivos nem carregam DLL.

Plugins que acompanham o programa#

AltiPag: cobra a sessão por Pix, com QR na tela, pela API do Mercado Pago.
Boas-vindas e agradecimento: tela antes e depois de cada sessão. Serve de exemplo.

Os dois nascem desligados. O código de cada um está na pasta do plugin, e o do Boas-vindas é um bom ponto de partida.

AnteriorCriar um plugin PróximaSolução de problemas