Integrar uma app

Cadastrar o ambiente e as origensCopiar link da seção

Quem faz: admin.

1. Abra o menu do projeto, clique em Configurações do projeto e entre em Ambientes. O ambiente criado com o projeto já tem a origem da URL do app.
2. Clique em Novo ambiente.
3. Dê um nome, como staging, e liste em Origens uma origem por linha. Cadastre a origem exata, com a porta quando houver, ou um padrão com *, como https://*.loja-demo.test.
4. Salve. Repita para cada ambiente da tabela acima.

Anote também o ID do projeto, que está em Configurações, Geral, com um botão de copiar. Você usa esse valor na etapa B.

Liberar a CSPCopiar link da seção

Quem faz: dev.

Se a app define uma Content-Security-Policy, ela precisa deixar a página falar com o Mira. Adicione a URL da instância em connect-src:

connect-src 'self' https://mira.example.com;
script-src 'self' https://mira.example.com;

A interface do widget não vai no pacote: a página a importa da instância, em https://mira.example.com/widget/v1/widget.js, na primeira vez que o widget abre. Por isso a CSP também precisa de script-src para a instância. Se o módulo não carregar, o widget não abre e o console mostra [Mira] widget indisponível na instância.

O login do widget abre uma aba do dashboard, que não passa pela CSP da app. Se você ativar a captura de erros (etapa A), libere também o host do DSN em connect-src. Ele é o mesmo da instância.

Instalar o bridgeCopiar link da seção

Quem faz: dev.

O Mira serve os pacotes do SDK pela própria URL, sem login. Instale o bridge pela URL da instância:

npm install https://mira.example.com/downloads/sdk/mira-bridge-0.15.0.tgz

O pacote pede React 19 e react-dom como peers, porque o ErrorBoundary e o widget usam o React da app. O lockfile fixa a integridade do arquivo. Uma versão publicada nunca muda, e as antigas continuam disponíveis. Para atualizar, troque a versão na URL.

Sem bundler, a instância também serve o widget como script. Cole no <head>, antes dos scripts da app, e pule o bootstrap.ts da próxima etapa:

<script src="https://mira.example.com/widget/v1/mira.js"></script>
<script>
  mira.init({ widget: { instanceUrl: "https://mira.example.com", trigger: "button" } });
</script>

O Guia de configuração do projeto mostra o mesmo trecho na aba Script, com a URL da instância preenchida. Pela tag de script, a CSP também bloqueia o mira.init inline: mova a chamada para um arquivo .js da app ou autorize-a com nonce.

Ativar o widgetCopiar link da seção

Quem faz: dev.

Crie um bootstrap que inicializa o bridge antes da app e só então carrega o resto. Assim o bridge captura também os erros que acontecem durante o carregamento dos módulos.

// src/main.tsx
import "./bootstrap";

Escolha o ambiente na aba. Cada uma traz o .env e o bootstrap.ts correspondentes.

# .env.development
VITE_MIRA_URL=https://mira.example.com

// src/bootstrap.ts
import { mira } from "@mira/bridge";
import { widgetIntegration } from "@mira/bridge/widget";

mira.init({
  integrations: [widgetIntegration({ instanceUrl: import.meta.env.VITE_MIRA_URL, trigger: "button" })],
});

await import("./app");

Em src/app.tsx, fica o conteúdo do antigo main.tsx: o createRoot e a renderização.

O parâmetro trigger escolhe como o widget abre:

O widget sempre abre num painel junto do botão. Sem botão ("shortcut" e "manual"), o painel fica no canto inferior direito. A opção mode das versões antigas é ignorada.

Para o widget copiar o link do report depois do envio, a página precisa permitir clipboard-write. Se a app roda o widget num iframe, declare allow="clipboard-write" nele. Sem a permissão, o painel mostra o link para copiar à mão.

VerificarCopiar link da seção

Quem faz: dev e admin.

1. Abra a app no ambiente configurado. O botão do Mira aparece no canto da página.

2. Clique no botão. Na primeira vez, o widget pede o login. Clique em Entrar: o painel mostra um código, e Aprovar no Mira abre o dashboard numa aba nova. Entre, confira que o código é o do painel e aprove o projeto e o ambiente que o Mira resolveu para a origem da app.

3. Faça uma captura pelo menu do botão, ou escolha Novo report. O report abre num diálogo: o tipo começa em Bug (troque para Melhoria ou Sugestão se for o caso), preencha o título e a descrição (em Markdown) e clique em Criar.

4. O painel troca o formulário por Report enviado.

5. O admin abre o dashboard e confere que o report chegou à triagem do ambiente.

Se o botão não aparece ou o login falha, confira nesta ordem: a origem cadastrada bate com a da barra de endereço (incluindo a porta), a CSP libera a instância, o navegador não bloqueou a aba de aprovação e nenhum <dialog> modal está aberto por cima da página.

Gerar a chaveCopiar link da seção

Quem faz: admin.

1. Em Configurações do projeto, Erros, escolha o ambiente no seletor. A seção mostra o nível de dados e as chaves de ingestão.
2. Dê um nome à chave, como web, e clique em Gerar chave.
3. Copie o DSN pelo botão da linha.

Cada chave vale só para o ambiente em que foi gerada. Revogar não tem volta e faz as apps com aquele DSN pararem de enviar.

Configurar a appCopiar link da seção

Quem faz: dev.

Coloque o DSN em VITE_MIRA_DSN e use o bootstrap.ts da aba de staging ou de produção da etapa 4 (Ativar o widget). A release identifica a versão (1.4.0+abc1234), e o buildTime permite ao Mira reabrir sozinho um erro resolvido quando um build novo volta a falhar.

Libere o host do DSN em connect-src. A origem da app precisa estar cadastrada no ambiente, porque a ingestão confere a origem dos envios do navegador.

ConferirCopiar link da seção

Quem faz: dev e admin.

Provoque um erro na app e abra Erros no projeto. A ocorrência aparece agrupada em um erro novo.

Criar a credencial de serviçoCopiar link da seção

Quem faz: admin.

1. Abra Admin, Serviços de API, e crie um serviço com os projetos da app.
2. Ative só a permissão Permitir envio de source maps e desative as consultas.
3. Em Chaves, informe nome e validade e use Emitir chave. O segredo (mira_svc_...) aparece uma vez; salve no gerenciador de segredos do CI.

Veja os detalhes em Tokens.

Instalar o pluginCopiar link da seção

Quem faz: dev.

npm install --save-dev https://mira.example.com/downloads/sdk/mira-sourcemaps-0.1.1.tgz

// vite.config.ts
import { miraSourceMaps } from "@mira/sourcemaps/vite";
import react from "@vitejs/plugin-react";
import { defineConfig, loadEnv } from "vite";

export default defineConfig(({ mode }) => {
  // Lê os `.env` do modo (`.env.production`, `.env.staging`) junto com o ambiente do CI.
  const env = loadEnv(mode, process.cwd(), "VITE_");

  return {
    plugins: [
      react(),
      miraSourceMaps({
        release: `${env.VITE_VERSION}+${env.VITE_BUILD_SHA}`,
        buildTime: env.VITE_BUILD_TIME,
      }),
    ],
  };
});

Use a mesma release e o mesmo buildTime do mira.init, que lê os mesmos valores de import.meta.env.

Configurar o CICopiar link da seção

Quem faz: dev.

O plugin lê três variáveis de ambiente:

# .github/workflows/deploy.yml
- run: pnpm build
  env:
    MIRA_URL: https://mira.example.com
    MIRA_PROJECT_ID: ${{ vars.MIRA_PROJECT_ID }}
    MIRA_SOURCEMAPS_TOKEN: ${{ secrets.MIRA_SOURCEMAPS_TOKEN }}
- run: pnpm exec mira-sourcemaps check dist

O check falha se sobrar um .map no diretório ou se um .js ou .css tiver map inline (sourceMappingURL=data:). Rode antes de publicar.

Fora do Vite, o mesmo pacote traz o comando mira-sourcemaps upload <dir> --release <release> para um dist já gerado.

O que o Mira armazena do código depende do nível de código do projeto, em Configurações, Geral: sem código, só mapeamento (padrão) ou completo.