Adicionando nosso script

Escolha o método de instalação adequado ao site. A instalação fixada com SRI só está disponível para equipes em que o cside a ativou.

Opção 1: Ferramenta CLI (recomendada para sites estáticos)

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

• 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 você pode especificar um diretório personalizado com --dir.

Instalar o CLI

npm install @cside.dev/cli

Ou execute diretamente sem instalar:

npx @cside.dev/cli@latest

Adicionar ao seu processo de build

Adicione o CLI ao seu script de build no package.json:

{
  "scripts": {
    "build": "your-build-command && npx @cside.dev/cli@latest"
  }
}

O que o CLI faz

Quando você executa o CLI, ele automaticamente:

1. Remove qualquer tag de script do cside existente, então executá-lo novamente após cada build nunca adiciona uma duplicata
2. Injeta o script do cside como primeiro script em todos os arquivos HTML, ignorando node_modules e vendor
3. Adiciona referrerpolicy="origin" à tag de script para verificação de licença

Opções comuns

# Processar um diretório específico
npx @cside.dev/cli --dir ./out

# Injetar um host de script com escopo de equipe (recomendado)
npx @cside.dev/cli@latest --team-id [your-team-id]

Consulte o guia de Integração CLI para todas as opções.

Opção 2: Instalação manual do script

Use este método para aplicações SSR ou se você precisar de mais controle sobre a integração.

O script manual é executado no motor JavaScript do navegador, tornando-o compatível com qualquer framework ou plataforma, independentemente da sua stack tecnológica.

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="https://[your-team-id].csidetm.com/client.js" referrerpolicy="origin"></script>
    ...
  </head>
  <body>
  ...
  </body>
</html>

# Com NPM
npm install @cside.dev/next

# Com Yarn
yarn add @cside.dev/next

# Com PNPM
pnpm add @cside.dev/next

// pages/_document.tsx
import Document, { Html, Head, Main, NextScript } from 'next/document';
import { CSideScript } from '@cside.dev/next';

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <CSideScript teamId="[your-team-id]" /> {/* <- Aqui */}
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

// layout.tsx
import { CSideScript } from '@cside.dev/next';

export default function Layout({ children }) {
  return (
    <>
      <CSideScript teamId="[your-team-id]" /> {/* <- Aqui */}
      {children}
    </>
  );
}

<!-- cside script -->
<script src="https://[your-team-id].csidetm.com/client.js" referrerpolicy="origin"></script>
<!-- the rest of your head code/scripts -->

Opção 3: Script fixo com Subresource Integrity (SRI)

Se scripts fixos estiverem disponíveis para o seu time, você pode instalar uma versão fixa do script do cside com um hash de Subresource Integrity (SRI), para que o navegador verifique os bytes exatos do script antes de executá-lo. O nome do arquivo é o hash SHA-256 do script completo, incluindo a configuração do seu time. Publicar uma nova configuração ou versão do script gera uma nova URL; URLs fixas existentes continuam funcionando.

Abra Setup > Security no painel e copie a tag de script completa em Latest published version. Coloque-a de forma síncrona próximo ao início do <head>, antes de outros scripts, mantendo a URL e o valor de integridade da mesma publicação:

<script
  src="https://[your-team-id].csidetm.com/[sha256].js"
  integrity="sha384-[base64-digest]"
  crossorigin="anonymous"
  referrerpolicy="origin"
></script>

A versão exibida é sempre a mais recente publicada. Ela não indica qual versão está instalada no seu site. Se o script ainda estiver em preparação, volte a esta página e selecione Refresh; isso verifica a publicação e não reconstrói o script. Mudanças de configuração podem demorar para aparecer em uma nova publicação.

Um script fixo mantém seu código e configuração originais. Para receber novas configurações ou correções do script, substitua a tag completa pela mais recente. Ativar ou desativar o Developer Mode também exige substituir ou remover um script já fixado, e URLs fixas antigas continuam funcionando mesmo que a instalação fixa seja desabilitada depois para o seu time.

Se uma publicação falhar ao carregar, use Retry.

Próximos passos

Depois de adicionar o cside ao seu site , você verá o tráfego de scripts em tempo real no painel.

Verifique se está funcionando: Abra o painel e abra Health na barra lateral esquerda. O tráfego de scripts aparece em segundos após o primeiro acesso. Não existe etapa de ativação. Seus domínios ficam na página Home do time e em Team Settings > Domains.

Prefere usar IA? Você também pode adicionar o cside com um assistente de IA como o Claude Code ou Cursor - cole um prompt e ele cuida da integração para você.