Cloudflare Workers

Use este guia quando quiser implantar cside fingerprinting no edge da Cloudflare. Esta é uma receita de Worker gerenciada pelo cliente. O cside não precisa gerenciar a sua conta Cloudflare para este setup.

Antes de começar

Você precisa de:

• Uma zona Cloudflare que roteie tráfego para as páginas que você quer fingerprint
• Permissão para criar ou editar Workers e rotas de Worker
• A URL do script de cside fingerprinting para o seu domínio
• Uma chave de API de fingerprint apenas para backend gerada no dashboard do cside
• Um endpoint backend que receba a string do token extraída da resposta JSON retornada por /client

Rollout recomendado

Comece com uma rota limitada, como /login* ou /checkout*, antes de aplicar o Worker ao site inteiro. Mantenha o Worker fail-open para que um problema no cside ou no Worker não bloqueie a entrega da página.

Consulte o guia de Workers Routes da Cloudflare para saber como aplicar um Worker a uma rota.

Exemplo de Worker

Armazene a URL do script do cside como CSIDE_FINGERPRINT_SCRIPT_URL no ambiente do Worker.

export default {
  async fetch(request, env) {
    const response = await fetch(request);
    const contentType = response.headers.get("content-type") || "";

    if (!contentType.includes("text/html")) {
      return response;
    }

    try {
      return new HTMLRewriter()
        .on("head", {
          element(element) {
            element.append(
              `<script src="${env.CSIDE_FINGERPRINT_SCRIPT_URL}" referrerpolicy="origin" data-src="6"></script>`,
              { html: true },
            );
          },
        })
        .transform(response);
    } catch {
      return response;
    }
  },
};

Troca do token

O Worker injeta apenas o script do navegador. Ele não cria um fingerprint de sessão sozinho. A sua aplicação ainda chama sendClientTelemetry(externalIds?), recebe { token } de /client e envia esse token de sessão ao seu backend.

Gere uma chave de API de fingerprint no dashboard do cside antes de conectar a troca no backend. A chave começa com cside_tgatv1_, é exibida apenas uma vez e deve ser armazenada como segredo do servidor. Não a inclua em código de navegador.

Chame sendClientTelemetry no código da sua página ou aplicação depois que o script carregar e, em seguida, leia a resposta JSON retornada por /client:

const result = await sendClientTelemetry({
  email: "user@example.com",
  accountId: "1234567890",
});

if (result.errors) {
  console.error(result.errors);
  throw new Error("A solicitação de telemetria falhou.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Nenhum token de sessão de fingerprint foi retornado.");
}

await fetch("/api/fingerprinting", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ sessionToken }),
});

/client retorna JSON no formato { "token": "..." }. Você também pode chamar sendClientTelemetry() sem argumentos quando não precisar anexar externalIds.

O seu backend troca o token de sessão com o cside chamando o endpoint de verificação autenticado:

curl https://api.cside.com/token/v2/verify \
  --request POST \
  --header "Authorization: Bearer $CSIDE_FINGERPRINT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"token":"'"$CSIDE_FINGERPRINT_SESSION_TOKEN"'"}'

Exemplo de handler backend:

app.post("/api/fingerprinting", async (request, reply) => {
  const { sessionToken } = request.body;

  const csideResponse = await fetch("https://api.cside.com/token/v2/verify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CSIDE_FINGERPRINT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ token: sessionToken }),
  });

  const payload = await csideResponse.json();

  if (!csideResponse.ok) {
    throw new Error(payload.error_message || "A troca de fingerprint falhou.");
  }

  reply.code(csideResponse.status).send(payload);
});

Consulte Recuperar datapoints para ver as opções de recuperação.

Notas operacionais

• Use rotas estreitas para o primeiro rollout
• Mantenha o Worker fail-open
• Não injete o script em respostas que não sejam HTML
• Confirme que a sua CSP permite a URL do script do cside e o endpoint de troca do token
• Mantenha a chave de API de fingerprint apenas em segredos do backend
• Passe de caminhos de teste para cobertura completa depois de ver datapoints no cside