Skip to main content
Frameworks suportados
Language

Integração CLI

Use a ferramenta CLI do cside para adicionar automaticamente o cside a arquivos HTML estáticos após o processo de build.

O CLI é um método de integração independente para sites estáticos. Ele injeta automaticamente o script de monitoramento do cside nos seus arquivos HTML. Nenhuma tag de script manual é necessária.

Não é necessário adicionar o script manualmente

Ao usar o CLI, não há necessidade de adicionar o script do cside ao seu site. O CLI o adiciona automaticamente. Use o CLI ou a instalação manual do script, não ambos.

Apenas HTML estático

O CLI suporta apenas arquivos HTML estáticos. Para aplicações SSR, use o script manual ou o pacote Next.js.

Frameworks suportados

O CLI funciona com qualquer framework que gere arquivos HTML estáticos:

  • Astro (modo estático)
  • Next.js (exportação estática)
  • Gatsby
  • Nuxt (modo estático)
  • SvelteKit (adaptador estático)
  • Eleventy (11ty)
  • Hugo
  • VitePress / VuePress
  • Docusaurus

Qualquer outro framework que gere arquivos HTML estáticos também funcionará. O CLI detecta automaticamente as pastas de saída .next e dist, ou especifique um diretório personalizado com --dir.

Instalação

npm i @cside.dev/cli

Ou execute diretamente sem instalar:

npx @cside.dev/cli

Uso

Execute o CLI após o processo de build para injetar o script do cside nos seus arquivos HTML. Passe o ID da sua equipe com --team-id; o CLI não aceita argumentos posicionais:

// package.json
{
  "scripts": {
    "build": "next build && npx @cside.dev/cli@latest --team-id [your-team-id]"
  }
}

O ID da sua equipe é exibido em Team Settings > General no painel do cside. Sem --team-id, o CLI injeta o host compartilhado proxy.csidetm.com em vez do host da sua equipe.

Opções do CLI

Usage: @cside.dev/cli [options]

Options:
      --version  Show version number                                   [boolean]
  -d, -f, --dir  Directory which include html files to process. By default we'll
                 try to look for a `.next` and `dist` folder. Also a single file
                 can be used.                                           [string]
  -s, --silent   Disable outputting processed html files.
                                                      [boolean] [default: false]
  -t, --team-id, --team
                 Inject a team-scoped cside script host using the provided team
                 ID.                                                     [string]
      --device-intelligence, --fingerprint
                 Inject cside device intelligence hosts on csidefd.com instead of
                 the default csidetm.com domain.
                                                      [boolean] [default: false]
  -h, --help     Show help                                             [boolean]

--fingerprint é mantido como alias de --device-intelligence para que os scripts de build existentes continuem funcionando.

Exemplos

Processar um diretório específico:

npx @cside.dev/cli --dir ./out

Processar um único arquivo:

npx @cside.dev/cli --dir ./dist/index.html

Injetar um host de script com escopo de equipe (recomendado):

npx @cside.dev/cli@latest --team-id [your-team-id]

Injetar o script de Device Intelligence em vez do script de monitoramento:

npx @cside.dev/cli@latest --team-id [your-team-id] --device-intelligence

Quando usar o CLI

Use o CLI se:

  • Você tem um processo de build de site estático (SSG)
  • Você quer uma integração sem código
  • Você não quer modificar seu código-fonte

O CLI automaticamente:

  1. Remove qualquer tag de script do cside já presente no HTML, então executá-lo novamente após cada build nunca adiciona uma duplicata
  2. Injeta o script do cside como o primeiro <script> ou <link> de cada arquivo HTML
  3. Adiciona o atributo referrerpolicy="origin" necessário
  4. Ignora os diretórios node_modules e vendor ao procurar arquivos HTML

Content Security Policy (CSP)

Se o seu site usa uma Content Security Policy, você ainda precisa atualizá-la ao usar o CLI. Adicione *.csidetm.com às suas diretivas script-src e connect-src. Isso só é necessário se você usar essas diretivas. Se connect-src não estiver presente, você não precisa adicionar connect-src:

Content-Security-Policy: script-src 'self' *.csidetm.com; connect-src 'self' *.csidetm.com
Apenas se você usar essas diretivas

Você só precisa atualizar sua CSP se já tiver as diretivas script-src ou connect-src definidas. Se você não usa CSP, ou não usa essas diretivas específicas, nenhuma alteração é necessária.

O que cada diretiva permite:

  • script-src: Se você usa esta diretiva, adicione *.csidetm.com para permitir que o script do cside seja executado
  • connect-src: Se você usa esta diretiva, adicione *.csidetm.com para permitir que o script do cside se comunique com a infraestrutura de borda

Para mais detalhes sobre configuração de CSP, consulte Adicionando cside à sua CSP e Configuração de Relatórios CSP.

Métodos de integração alternativos

Was this page helpful?