Integrações MQTT

Crie um serviço externo que acompanhe o Presenter ou troque mensagens nos seus próprios tópicos. Credenciais persistentes têm uma senha exibida uma única vez e permissões limitadas. Elas nunca permitem comandos de projeção.

Credenciais Locais exigem uma licença Presenter Own, Flex ou uma licença anterior paga elegível, inclusive pelo Complete. Elas ficam naquele computador e não precisam de conta na nuvem. SundayAssist Cloud exige uma assinatura Complete ativa, login, participação na organização e a função de proprietário ou administrador. Um teste gratuito não dá esse acesso.

Criar credenciais

  1. Abra Conexões → Controle pelo celular → Credenciais de integração e escolha Local ou SundayAssist Cloud.
  2. Escolha Criar credenciais, dê um nome ao serviço e informe seus Tópicos de publicação e Tópicos de assinatura, um por linha. Deixe vazia a direção não usada. Para o exemplo abaixo, ative Ler eventos do Presenter e deixe os tópicos personalizados vazios.
  3. Salve imediatamente a senha no armazenamento de segredos do serviço. Copiar dados de conexão inclui a senha. Ela é exibida uma única vez e não pode ser recuperada depois.
  4. Use credenciais separadas para cada serviço. Cada credencial permite até 20 entradas de tópicos. Podem existir até 20 ativas por instalação local, ou por conta e organização na nuvem.

Conectar ao broker correto

Use MQTT 3.1.1 ou 5. Copie o endereço local e as portas mostrados pelo Presenter; os habituais são TCP 1883 e WebSocket 9883, com alternativas quando ocupados. O tráfego local não é criptografado: use uma rede confiável e nunca exponha essas portas à Internet. A nuvem usa TLS na porta 8883, ou WebSocket seguro na porta 443 com o caminho /mqtt. Mantenha a verificação de certificados. Cada conexão simultânea exige um ID de cliente exclusivo começando pelo prefixo atribuído.

Local:
  mqtt://<presenter-lan-ip>:1883
  ws://<presenter-lan-ip>:9883/mqtt
Complete cloud:
  mqtts://mqtt.sundayassist.com:8883
  wss://mqtt.sundayassist.com/mqtt
username: <generated-username>
password: <shown-once-password>
clientId: <assigned-client-id-prefix>external-1

Escolher tópicos personalizados

As publicações exigem tópicos exatos. As assinaturas permitem um tópico exato ou um /# final abaixo de um espaço de nomes literal, como church/lyrics/#. O curinga +, um # isolado, níveis vazios, espaços e $ são rejeitados. O primeiro espaço de nomes não pode ser sundayassist, independentemente de maiúsculas. A permissão explícita de leitura de eventos é a exceção reservada.

As permissões locais valem para aquela instalação do Presenter. Os tópicos na nuvem ficam isolados na organização: use o mesmo tópico nos dois clientes, sem prefixo de organização. Pessoas da mesma organização com permissões sobrepostas podem trocar mensagens. Essas credenciais não permitem parear o Remote, acessar seu protocolo de apresentação/estado, usar IA, relay ou Presenter-link nem publicar em tópicos reservados do SundayAssist. Publicações personalizadas aceitam QoS 0 ou 1, sem retenção, até 1 MiB.

Ler eventos do Presenter

Ative Ler eventos do Presenter e assine sundayassist/integrations/v1/events/#, ou limite a sundayassist/integrations/v1/events/<presenterId>/state. O Presenter publica um retrato JSON retido com QoS 1 e o seguinte contrato público. Títulos são incluídos; letras, notas, caminhos de arquivos, capturas e dados de conta são excluídos. O cartão ou a seção pode ser null.

{
  "schemaVersion": 1,
  "eventId": "boot-id:42",
  "presenterId": "opaque-installation-id",
  "runId": "boot-id",
  "sequence": 42,
  "occurredAt": "2026-10-27T12:00:00Z",
  "type": "presenter.state",
  "state": {
    "presenting": true,
    "blanked": false,
    "phase": "active",
    "cue": {"id": "opaque-occurrence", "type": "lyrics", "title": "Welcome", "index": 0},
    "section": {"id": "opaque-section", "title": "Gathering", "index": 0},
    "position": {"subIndex": 0, "page": 0}
  }
}

Use eventId para remover duplicatas e sequence para ordenar mensagens no mesmo runId. Reiniciar o Presenter cria uma execução nova. Reconectar pode repetir o mesmo evento. Os IDs de cartão e seção são referências opacas a ocorrências; editar ou reordenar a apresentação pode mudá-los. Os índices começam em zero; subIndex pode ser -1 para um slide padrão.

As mudanças são agrupadas por até 1 segundo, com um novo retrato normalmente a cada 15 segundos, mesmo sem mudanças. Confira occurredAt e o indicador de retenção MQTT antes de agir. Um retrato retido pode durar mais que um Presenter em execução e não prova que ele esteja conectado. É o último estado conhecido, não um registro completo nem a programação futura.

Experimente a visão ao vivo em Node.js

Baixe o exemplo funcional ou abra a prévia simulada. Com Node.js 22 ou posterior, inicie uma visão do cartão atual e uma linha do tempo dos cartões recebidos, sem broker nem licença:

unzip mqtt-showcase.zip
cd mqtt-showcase
npm ci
npm run demo

Para eventos reais, copie .env.example para .env e preencha a URL do broker, usuário, senha e prefixo de cliente gerados. Defina PRESENTER_ID quando vários Presenters compartilharem a organização na nuvem e execute npm start. Abra http://127.0.0.1:4188. Sem ID, o primeiro Presenter é selecionado. As credenciais ficam no Node; o navegador recebe apenas os campos públicos selecionados por Server-Sent Events. Mantenha .env privado. O exemplo é um servidor local de desenvolvimento, não um serviço hospedado compartilhado.

No Node-RED, conecte um nó MQTT in ao broker informado. Preencha o usuário e a senha gerados e um ID de cliente exclusivo com o prefixo atribuído; ative TLS com verificação de certificados para a nuvem. Configure o tópico de eventos acima e QoS 1 e conecte JSON → debug. Leia msg.payload.state.cue.title, confira msg.payload.occurredAt e remova duplicatas por msg.payload.eventId antes de iniciar uma ação. Consulte a referência oficial do MQTT.js e o guia MQTT do Node-RED.

Receber texto ao vivo

Para texto local, permita que o serviço externo publique em church/lyrics/slide. Em Conexões → Controle pelo celular → Mesmo Wi-Fi, defina o Tópico de letras como church/lyrics/slide. Adicione um cartão de letras ao vivo da biblioteca e projete-o. Publique texto UTF-8 simples no broker local, sem envolver em JSON.

Para texto na nuvem do Complete, crie outras credenciais na mesma organização com assinatura somente de church/lyrics/slide. Escolha Servidor próprio no Presenter, informe wss://mqtt.sundayassist.com/mqtt, essas credenciais e o mesmo Tópico de letras, salve e teste. A conexão local do celular continua disponível. Servidor próprio usa essa conexão manual no lugar de De qualquer lugar (Complete) automático; essas credenciais não dão acesso ao Remote na nuvem.

Substituir, revogar e tratar interrupções

Substituir senha invalida os dados antigos e exibe os novos uma única vez; atualize todos os clientes que os usam. Revogar desativa essas credenciais permanentemente. As credenciais locais persistem ao reiniciar o Presenter; as senhas não têm expiração fixa. O acesso pago e as permissões continuam obrigatórios. Você pode consultar e revogar as credenciais após o fim do acesso pago.

A elegibilidade na nuvem e as conexões ativas são verificadas aproximadamente a cada 30 segundos. Revogar não é instantâneo; uma interrupção na verificação de permissões pode atrasar a desconexão por alguns minutos. Clientes na nuvem devem reconectar pelo menos uma vez por hora com a senha atual. Ative a reconexão e a nova assinatura automáticas. QoS 1 pode entregar duplicatas; falhas de rede, manutenção e failover podem interromper a entrega. Torne as ações seguras em caso de repetição e mantenha conteúdo local preparado. TLS protege a conexão de rede, não o conteúdo de ponta a ponta.