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
• 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. A sua aplicação ainda chama sendClientTelemetry(externalIds?), recebe { token } de /client e envia esse token de sessão ao seu backend.

O seu backend troca o token de sessão bruto com o cside:

curl https://api.cside.com/token/v1/client \
  --request POST \
  --header "Content-Type: text/plain" \
  --data "$CSIDE_FINGERPRINT_SESSION_TOKEN"

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
• Passe de caminhos de teste para cobertura completa depois de ver datapoints no cside