Guia de integração

Tudo o que um engenheiro ou agente de código precisa para instalar o DeltaCrab.

Versão da documentação: widget v1. Não misture com outras versões.

Visão geral

O widget do DeltaCrab é um script que cria um iframe no seu site. O iframe roda no domínio do DeltaCrab; seu site nunca vê tokens nem mensagens.

O widget só carrega em origens autorizadas na página Instalação. Comece no modo visitante; adicione identidade verificada quando seu app tiver servidor.

1. Copie a chave pública do site na página Instalação.
2. Adicione a origem do seu app (ex.: https://app.exemplo.com) em Origens autorizadas.
3. Cole o snippet no layout global.
4. Abra seu site, envie uma mensagem e responda pela caixa de entrada.

HTML / qualquer site

Cole antes de </body> em todas as páginas, ou uma vez no layout principal.

HTML

<script>
  window.DeltaCrabSettings = { siteKey: "dc_pk_YOUR_SITE_KEY" };
  window.DeltaCrab = window.DeltaCrab || function () { (window.DeltaCrab.q = window.DeltaCrab.q || []).push(arguments); };
</script>
<script async src="https://app.deltacrab.com/widget.js"></script>

Next.js (App Router)

Adicione uma vez em app/layout.tsx. Funciona com Server Components; o script carrega depois da hidratação.

app/layout.tsx

// app/layout.tsx — add once, inside <body>
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script id="deltacrab-settings" strategy="afterInteractive">
          {`window.DeltaCrabSettings = { siteKey: "dc_pk_YOUR_SITE_KEY" };
window.DeltaCrab = window.DeltaCrab || function () { (window.DeltaCrab.q = window.DeltaCrab.q || []).push(arguments); };`}
        </Script>
        <Script src="https://app.deltacrab.com/widget.js" strategy="afterInteractive" />
      </body>
    </html>
  );
}

// Optional, from any client component:
//   window.DeltaCrab?.("setLocale", "pt-BR");
//   window.DeltaCrab?.("setTheme", "dark");
//   window.DeltaCrab?.("open");

Identidade verificada

Seu servidor assina um token HS256 curto com o segredo gerado em Instalação → Identidade verificada. O segredo fica só no servidor, na variável DELTACRAB_IDENTITY_SECRET.

Claims obrigatórios: site_key, sub (ID estável do cliente no seu banco), iat, exp (no máximo 10 minutos depois de iat) e jti (único; cada token só pode ser usado uma vez). Atributos aceitos: name, email, plan, organization, account_id, locale. Outros campos são ignorados.

Peça um token novo e chame identify a cada carregamento de página enquanto o usuário estiver logado, e logo após login ou troca de conta. Chame logout ao sair. O histórico anônimo nunca é unido ao cliente identificado.

Ao rotacionar o segredo, o anterior continua válido por 24 horas para você publicar o novo sem derrubar ninguém.

app/api/deltacrab-token/route.ts

// app/api/deltacrab-token/route.ts — runs on YOUR server only.
// Requires DELTACRAB_IDENTITY_SECRET (from DeltaCrab → Install → Verified identity).
import { createHmac, randomUUID } from "node:crypto";
import { NextResponse } from "next/server";
import { getSession } from "@/lib/auth"; // your existing server-side session helper

function base64url(input: Buffer | string) {
  return Buffer.from(input).toString("base64url");
}

export async function POST() {
  const session = await getSession();
  if (!session?.user) return NextResponse.json({ error: "unauthenticated" }, { status: 401 });

  const now = Math.floor(Date.now() / 1000);
  const header = base64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
  const payload = base64url(JSON.stringify({
    site_key: "dc_pk_YOUR_SITE_KEY",
    sub: String(session.user.id),          // stable customer ID from YOUR database
    iat: now,
    exp: now + 300,                         // at most 10 minutes
    jti: randomUUID(),                      // single use
    name: session.user.name,                // optional, allowlisted attributes:
    email: session.user.email,              // name, email, plan, organization, account_id, locale
  }));
  const signature = createHmac("sha256", process.env.DELTACRAB_IDENTITY_SECRET!)
    .update(`${header}.${payload}`)
    .digest("base64url");
  return NextResponse.json({ token: `${header}.${payload}.${signature}` });
}

// In the browser, on every page load while the user is signed in (tokens are
// single use and short-lived, so fetch a fresh one each time), and right
// after login or an account switch:
//   const { token } = await fetch("/api/deltacrab-token", { method: "POST" }).then(r => r.json());
//   window.DeltaCrab("identify", { token });
// On logout:
//   window.DeltaCrab("logout");
// Widget script: https://app.deltacrab.com/widget.js

API do widget

Comandos podem ser chamados antes do script terminar de carregar: o stub do snippet guarda a fila e o loader executa na ordem.

JavaScript

window.DeltaCrab("open");                    // open the panel
window.DeltaCrab("close");                   // close the panel
window.DeltaCrab("setLocale", "pt-BR");      // en | pt-BR | es
window.DeltaCrab("setTheme", "dark");        // light | dark | system
window.DeltaCrab("identify", { token });     // signed identity token from YOUR server
window.DeltaCrab("logout");                  // forget the signed-in customer on this device

Content Security Policy

Se seu app define CSP, libere a origem do DeltaCrab nestas diretivas:

CSP

Content-Security-Policy:
  script-src  'self' https://app.deltacrab.com;
  frame-src   https://app.deltacrab.com;
  connect-src 'self' https://app.deltacrab.com;

Solução de problemas

O console do navegador e a seção Diagnóstico da página Instalação mostram a causa.

"not in the allowed origins": adicione a origem exata (protocolo + host + porta) em Origens autorizadas.
"Unknown site key": copie o snippet de novo da página Instalação.
Recusa de frame-ancestors no console: a origem não está autorizada para este site.
Identidade recusada: expired (token vencido), replay (jti repetido), bad_signature (segredo errado), wrong_site (site_key diferente), lifetime_too_long (exp - iat acima do limite).
Nada aparece: confira a CSP (script-src, frame-src, connect-src).