Webhooks e API

O BoothDock Studio pode informar outros programas sobre cada passo de uma sessão (webhooks) e deixar-se controlar por outros programas (API local). Encontra ambos na área de administração em Sistema → Automatização.

No BoothDock Studio 1.4.0 e em versões anteriores, os webhooks ainda se chamam aí «Acionadores».

Os webhooks e a exportação em tempo real só existem no Windows. A API local está disponível a partir da versão 1.4.0 também no iPad e no iPhone.

Utilizações típicas: luzes ou DMX sincronizados com a contagem decrescente, uma sobreposição para stream, um contador à entrada – ou um Stream Deck como comando à distância da cabine.

Configurar webhooks

Introduza um Programa, um Endereço (URL) ou ambos. Em cada evento, a cabine chama os dois:

• Programa – um .exe, .bat ou .cmd. Chamada: programa <evento> <param1> <param2> …. Cada valor chega como argumento próprio, mesmo que contenha espaços. O programa arranca sem janela, na sua própria pasta. Um script do PowerShell (.ps1) é iniciado através de um pequeno .bat colocado à frente.
• Endereço (URL) – http ou https, chamado por GET: https://seu-servidor/hook?event_type=<evento>&param1=…&param2=…. Os valores são codificados para URL; os parâmetros que já constam do seu endereço mantêm-se.

A sessão nunca espera pelo seu webhook: o programa e a chamada correm em paralelo, e uma chamada pode durar no máximo 5 segundos. Enviar teste envia de imediato um session_start – assim verifica a ligação sem iniciar uma sessão.

O programa e o endereço só podem ser definidos diretamente na cabine, não através do Hub: um caminho de programa equivale ao direito de executar algo no computador.

Eventos

Exemplo de um .bat que regista cada evento: echo %DATE% %TIME% %* >> "%~dp0eventos.log"

API local

Outros programas controlam a cabine por HTTP – por exemplo um Stream Deck, um script próprio ou um controlo 360° no telemóvel.

• Ativar: Sistema → Automatização → Ativar API. De fábrica, a API está desligada. Porta 1500, alterável.
• Endereço: http://localhost:1500/api/<comando> (ou 127.0.0.1). De fábrica, a cabine só aceita pedidos deste computador.
• Palavra-passe: 16 caracteres, apresentada na mesma secção – copie-a ou gere uma nova. Envie-a como ?password=…, como cabeçalho X-Api-Password ou como Authorization: Bearer …. Só o ping funciona sem ela.
• Resposta: sempre HTTP 200 com JSON, por exemplo {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Se correu bem, indica-o IsSuccessful; em caso de erro, o motivo está em ErrorMessage. Alguns comandos devolvem também Data.

Uma chamada completa: http://localhost:1500/api/start?mode=print&password=SUA-PALAVRA-PASSE

Controlar a partir da rede (telemóvel, tablet, 360°)

Ative adicionalmente Acessível também a partir da rede. A cabine passa então a aceitar pedidos de dispositivos na mesma Wi-Fi/LAN – nunca a partir da internet.

• Endereço para o telemóvel: consta da linha de estado, por exemplo http://192.168.1.20:1500. O exemplo por baixo mostra logo o endereço certo.
• Sem introduzir o IP: a cabine anuncia-se sozinha na rede (mDNS/Bonjour, tipo de serviço _boothdock._tcp, nome «BoothDock» mais o nome do computador). As aplicações que a procuram encontram-na automaticamente.
• Bloqueio: se um dispositivo enviar uma palavra-passe errada dez vezes em dez minutos, fica bloqueado durante 15 minutos. O próprio computador da cabine nunca é bloqueado.
• Só na sua própria rede: a palavra-passe circula pela rede sem encriptação. Use o modo de rede apenas na sua própria Wi-Fi protegida – não na Wi-Fi aberta para convidados do local.
• Firewall: a instalação cria a regra, apenas para redes privadas. Se a linha de estado mostrar um aviso da firewall, reinstale o BoothDock Studio ou permita-o no Windows em «Permitir uma aplicação através da firewall». Se o Windows tratar a Wi-Fi como pública, os dispositivos não conseguem entrar – mude o perfil para Privada nas propriedades de rede.

Comandos

Se a cabine não responder em 15 segundos, é devolvido IsSuccessful: false com uma indicação.

Exportação em tempo real

No mesmo separador escolhe uma Pasta de exportação – por exemplo uma pen USB ou uma pasta na nuvem (OneDrive, Dropbox). Cada ficheiro concluído chega lá de imediato, organizado por evento e tipo (Impressões, Originais, GIFs, Vídeos – cada um pode ser desligado individualmente). Se a pen faltar por momentos, a cabine copia os ficheiros mais tarde. Se um convidado eliminar a sua sessão na cabine, as cópias também desaparecem.

Iniciar por comando

No mesmo separador, em Iniciar por comando, aprende uma tecla. Comandos de apresentação, botões USB e pedais costumam enviar a barra de espaço; esta já vem predefinida. Em Inicia escolhe o que a tecla faz no ecrã inicial: Como um toque (fluxo normal) ou logo um modo, por exemplo 360° na plataforma. No BoothDock Studio 1.4.0 e em versões anteriores, a tecla só existe para o 360°, ver 360° / câmara lenta.

Resolução de problemas

• Não acontece nada: há algo no registo? Os webhooks escrevem em webhooks.log (até à 1.4.0: ausloeser.log), a API em lokale-api.log – ambos na pasta %LocalAppData%\Boothdock Studio\logs. Os pedidos recusados (palavra-passe errada, dispositivo desconhecido) aparecem aí no máximo uma vez por minuto.
• «Invalid password.» – copie novamente a palavra-passe; depois de Nova palavra-passe, a antiga deixa de ser válida.
• «The booth is not on the start screen …» – start só funciona a partir do ecrã inicial. Primeiro cancel, depois start.
• «Too many failed attempts …» – o dispositivo enviou demasiadas vezes uma palavra-passe errada. Aguarde 15 minutos e verifique a palavra-passe.
• O telemóvel não chega à cabine, mas no computador tudo funciona: quase sempre é a Firewall do Windows ou uma Wi-Fi tratada como pública – ver acima. A linha de estado assinala ambos os casos.

Próximos passos

• Modos de captura
• Imprimir