Cliente Web MQTT Online: Teste Brokers no Navegador

Q: Posso usar recursos do MQTT 5 a partir do navegador?

Sim. O MQTT.js suporta MQTT 5 com protocolVersion: 5, então você pode ler reason codes e usar recursos como message expiry e user properties a partir de um navegador.

Um cliente web MQTT online permite conectar a um broker, assinar topics e publicar mensagens de teste direto de uma aba do navegador, sem instalar nada. Neste guia, você vai entender como os clientes de navegador realmente alcançam um broker, fazer uma sessão de testes completa com o cliente integrado ao portal do ConnectMQ e construir um pequeno cliente de navegador próprio para os casos que uma ferramenta hospedada não cobre.

Por Que Usar um Cliente Web MQTT Online?

Ferramentas de linha de comando como o mosquitto_sub são excelentes, mas nem sempre estão disponíveis. Você pode estar em um notebook corporativo bloqueado, ajudando um colega em uma videochamada ou verificando uma instalação em campo a partir de um tablet. Um cliente baseado em navegador elimina a etapa de configuração: abra uma página, informe o host e as credenciais e você já está vendo o tráfego ao vivo.

Tarefas típicas para um cliente web:

Confirmar que um novo dispositivo realmente publica, e no topic esperado.
Enviar um comando pontual, como uma atualização de configuração ou o acionamento de um relé, a um dispositivo em teste.
Verificar retained messages após uma implantação.
Mostrar a uma pessoa não técnica que os dados estão fluindo, sem precisar explicar um terminal.
Reproduzir um relato de bug com o payload exato que um cliente enviou.

Um cliente web é uma ferramenta de teste e depuração, não um consumidor de produção. Mantenha integrações de longa duração em um serviço adequado e use o navegador para o trabalho interativo.

Como os Clientes MQTT de Navegador se Conectam

Navegadores não conseguem abrir sockets TCP puros, então um cliente de navegador não pode usar as portas MQTT clássicas 1883 ou 8883. Em vez disso, ele encapsula o MQTT dentro de uma conexão WebSocket. O broker precisa expor um listener WebSocket, e o cliente precisa saber tanto a porta quanto o caminho. Se quiser todo o contexto, leia o nosso guia de MQTT sobre WebSocket.

O ConnectMQ expõe estes listeners em todos os brokers:

Transporte	Porta	Formato da URL	Usar a partir do navegador?
MQTT sobre TCP	1883	`mqtt://host:1883`	Não
MQTT sobre TLS	8883	`mqtts://host:8883`	Não
WebSocket	8083	`ws://host:8083/mqtt`	Apenas a partir de páginas HTTP sem criptografia
Secure WebSocket	8084	`wss://host:8084/mqtt`	Sim, recomendado

Duas regras dos navegadores explicam a maioria das conexões com falha. Primeiro, uma página carregada via HTTPS não pode abrir um socket ws:// sem criptografia; o navegador o bloqueia como conteúdo misto. Segundo, o caminho importa: conectar a wss://broker.connectmq.com:8084 sem /mqtt alcança o servidor, mas nunca conclui o handshake MQTT. Use WebSocket seguro com o caminho completo e os dois problemas desaparecem. O broker serve um certificado Let's Encrypt, então os navegadores confiam nele sem nenhuma configuração extra.

Passo a Passo: Teste um Broker com o Cliente Web do ConnectMQ

O caminho mais rápido é o cliente MQTT integrado ao portal, porque ele já conhece os endpoints e as credenciais do seu broker.

Cadastre-se em app.connectmq.com, escolha o plano Serverless gratuito e crie um broker. O portal gera usuário, senha e client ID para você.
Abra o cliente MQTT no navegador a partir do portal. Os dados de conexão do seu broker ficam disponíveis ao lado dele.
Conecte. Um CONNACK bem-sucedido significa que as credenciais e o client ID foram aceitos. Lembre-se de que os client IDs ficam vinculados às credenciais emitidas, então use o client ID fornecido pelo portal em vez de inventar um.
Assine um filtro com wildcard para o seu projeto, por exemplo factory1/#, para ver tudo sob essa raiz.
Publique um payload de teste como {"temperature": 21.7} em factory1/line1/sensor1/telemetry com QoS 1. Ele deve aparecer imediatamente no painel de assinaturas.
Publique mais uma vez com a flag retain ativada, desconecte, reconecte e assine de novo. O valor retido deve chegar instantaneamente, o que prova que o broker armazena o último valor daquele topic.
Abra o explorador de topics ao vivo em outra aba. O mesmo topic agora aparece na árvore, uma verificação cruzada prática de que a mensagem realmente passou pelo broker.

Se você só quer experimentar, também pode apontar qualquer cliente web para o servidor MQTT público (gratuito) em wss://broker.connectmq.com:8084/mqtt, pensado para testes e protótipos, não para dados de produção. Ele aceita conexões anônimas com qualquer client ID único e não vazio. Use um prefixo de topic exclusivo como connectmq/demo/k3x9/..., porque tudo na área pública pode ser lido por qualquer pessoa.

Construa um Cliente de Navegador Mínimo com MQTT.js

Às vezes você precisa de um comportamento que uma ferramenta genérica não oferece: um gerador de payloads personalizado, um botão ligado a um comando específico ou uma página que você possa entregar a um técnico de campo. O MQTT.js roda no navegador e fala WebSockets nativamente. Instale-o em qualquer projeto baseado em bundler (Vite, webpack ou similar) com npm install mqtt e use o módulo a seguir:

import mqtt from "mqtt";

const prefix = `connectmq/demo/${Math.random().toString(16).slice(2, 8)}`;
const clientId = `web-${Math.random().toString(16).slice(2, 10)}`;

const client = mqtt.connect("wss://broker.connectmq.com:8084/mqtt", {
  clientId,
  protocolVersion: 5,
  clean: true,
  connectTimeout: 10_000,
  reconnectPeriod: 3_000,
  // Para o seu broker privado, adicione as credenciais do portal:
  // username: "YOUR_USERNAME",
  // password: "YOUR_PASSWORD",
  // e use clientId: "YOUR_CLIENT_ID"
});

client.on("connect", (connack) => {
  console.log("Connected, reason code:", connack.reasonCode ?? 0);
  client.subscribe(`${prefix}/#`, { qos: 1 }, (err, granted) => {
    if (err) return console.error("Subscribe failed:", err);
    console.log("Granted:", granted);
    client.publish(
      `${prefix}/sensor1/telemetry`,
      JSON.stringify({ temperature: 21.7, ts: Date.now() }),
      { qos: 1 }
    );
  });
});

client.on("message", (topic, payload) => {
  console.log(`${topic} -> ${payload.toString()}`);
});

client.on("error", (err) => console.error("MQTT error:", err.message));
client.on("close", () => console.log("Connection closed"));

Abra o console do navegador e você deverá ver a mensagem de conexão, o QoS concedido e o seu próprio payload ecoado de volta. Como o código usa MQTT 5, o valor connack.reasonCode fica disponível, e uma conexão recusada informará um motivo significativo em vez de uma falha genérica.

Nunca Envie Segredos de Produção para o Navegador

Tudo o que você coloca em JavaScript de front-end fica visível para o usuário. Para uma página interna de depuração, isso é aceitável; para um dashboard público, não. Se muitas pessoas precisam de acesso de leitura, emita uma credencial dedicada para o dashboard e mantenha as credenciais dos dispositivos separadas, ou coloque um pequeno back-end entre o navegador e o broker. As nossas boas práticas de segurança MQTT abordam a separação de credenciais com mais detalhes.

Solução de Problemas de Conexão do Cliente MQTT Online

A maioria dos problemas se resume a detalhes de transporte. Percorra este checklist na ordem:

Porta errada. As portas 1883 e 8883 não funcionam a partir de um navegador. Use a 8084 para wss://.
Caminho ausente. A URL precisa terminar em /mqtt.
Conteúdo misto. Uma página HTTPS não pode abrir ws://. Troque para wss://.
Client ID vazio. O servidor MQTT público exige um client ID não vazio; o seu broker privado exige o que foi emitido.
Client ID duplicado. Se duas abas usam o mesmo client ID, o broker desconecta a sessão mais antiga cada vez que a outra se conecta, e as duas abas ficam oscilando. Dê a cada aba um ID único no servidor MQTT público.
Credenciais erradas. Copie usuário e senha diretamente do portal. Repetidas falhas de login podem acionar o bloqueio de IP como parte da proteção contra força bruta do broker, então corrija as credenciais antes de tentar de novo em loop.
Proxy corporativo. Alguns proxies removem os cabeçalhos de upgrade do WebSocket. Teste a partir de outra rede para confirmar.
Cota atingida. O plano Serverless gratuito permite até 25 conexões. Com o MQTT 5, o broker pode retornar o reason code 0x97 (quota exceeded), que o cliente MQTT.js expõe no seu erro.

Interpretando os Sintomas

Sintoma	Causa provável	Solução
O socket abre e depois fecha sem CONNACK	Caminho `/mqtt` ausente	Adicione o caminho
"Mixed content" no console	`ws://` a partir de uma página HTTPS	Use `wss://` na 8084
Conecta e reconecta a cada poucos segundos	Client ID duplicado	Use um ID único por aba
As publicações somem	Topic divergente ou assinatura inativa	Assine `prefix/#` primeiro
Não autorizado	Credenciais ou client ID errados	Copie de novo do portal

Quando Ir Além do Navegador

Um cliente web é ideal para verificações interativas, mas ele termina na aba. Quando você precisar registrar o tráfego por horas, reproduzir mensagens ou automatizar testes com scripts, passe para ferramentas que rodam fora do navegador. Os exemplos de mosquitto_pub e mosquitto_sub cobrem testes automatizados, a extensão ConnectMQ para VS Code mostra os reason codes de CONNACK, SUBACK e PUBACK dentro do seu editor, e o Desktop MQTT explorer do ConnectMQ é mais adequado para sessões longas. Para inspecionar visualmente uma hierarquia grande de topics, veja o nosso passo a passo do navegador de topics MQTT.

Para o tráfego de produção em si, a decisão importante é o broker, não o cliente. Um broker MQTT gerenciado oferece endpoints WebSocket seguros, credenciais emitidas e um portal com cliente web e explorador de topics prontos para uso, para que as verificações no navegador que você acabou de aprender funcionem desde o primeiro dia.

Comece com o ConnectMQ

Crie um broker gratuito em app.connectmq.com no plano Serverless; não é preciso cartão de crédito. Você recebe credenciais, os quatro transportes, incluindo WebSockets seguros, e o cliente no navegador usado neste guia. Para saber como o ConnectMQ se compara a operar o seu próprio servidor, leia o nosso guia para escolher um broker MQTT na nuvem.

Perguntas frequentes

Um navegador pode se conectar às portas MQTT 1883 ou 8883?

Não. Navegadores não conseguem abrir sockets TCP puros, então precisam usar MQTT sobre WebSocket. No ConnectMQ, isso significa wss://<host>:8084/mqtt para conexões criptografadas.

É seguro usar um cliente web MQTT online com credenciais reais?

É seguro quando o cliente roda em uma página confiável, como o portal do seu próprio broker, via wss://. Evite digitar credenciais de produção em sites de terceiros desconhecidos e nunca embuta credenciais de dispositivos em código de front-end público.

Por que meu cliente web fica desconectando?

A causa mais comum são duas sessões usando o mesmo client ID, o que faz o broker derrubar a mais antiga a cada vez. Dê a cada aba e ferramenta um client ID único.

O plano gratuito inclui o cliente web?

Sim. O plano Serverless gratuito inclui o portal com o cliente MQTT no navegador e o explorador de topics ao vivo.

Posso usar recursos do MQTT 5 a partir do navegador?

Sim. O MQTT.js suporta MQTT 5 com protocolVersion: 5, então você pode ler reason codes e usar recursos como message expiry e user properties a partir de um navegador.

Cliente Web MQTT Online: Teste Qualquer Broker pelo Navegador