Cloudflare Workers

Use esta guía si quiere desplegar cside fingerprinting en el edge de Cloudflare. Esta es una receta de Worker gestionada por el cliente. cside no necesita administrar su cuenta de Cloudflare para este setup.

Antes de empezar

Necesita:

• Una zona de Cloudflare que enrute el tráfico de las páginas que quiere fingerprint
• Permiso para crear o editar Workers y rutas de Worker
• La URL del script de cside fingerprinting para su dominio
• Una clave API de fingerprint solo para backend generada en el dashboard de cside
• Un endpoint backend que reciba la cadena del token extraída de la respuesta JSON devuelta por /client

Despliegue recomendado

Empiece con una ruta limitada, como /login* o /checkout*, antes de aplicar el Worker a todo el sitio. Mantenga el Worker fail-open para que un problema de cside o del Worker no bloquee la entrega de páginas.

Consulte la guía de Workers Routes de Cloudflare para saber cómo aplicar un Worker a una ruta.

Ejemplo de Worker

Guarde su URL de script de cside como CSIDE_FINGERPRINT_SCRIPT_URL en el entorno del 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;
    }
  },
};

Intercambio de token

El Worker solo inyecta el script del navegador. No crea un fingerprint de sesión por sí solo. Su aplicación sigue llamando a sendClientTelemetry(externalIds?), recibe { token } desde /client y envía ese token de sesión a su backend.

Genere una clave API de fingerprint en el dashboard de cside antes de conectar el intercambio en backend. La clave empieza con cside_tgatv1_, se muestra solo una vez y debe guardarse como secreto del servidor. No la inserte en código de navegador.

Llame a sendClientTelemetry desde el código de su página o aplicación después de que cargue el script y luego lea la respuesta JSON devuelta por /client:

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("La solicitud de telemetría falló.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("No se devolvió ningún token de sesión de fingerprint.");
}

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

/client devuelve JSON con la forma { "token": "..." }. También puede llamar a sendClientTelemetry() sin argumentos cuando no necesite adjuntar externalIds.

Su backend intercambia el token de sesión con cside llamando al endpoint de verificación 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"'"}'

Ejemplo 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 || "El intercambio de fingerprint falló.");
  }

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

Consulte Recuperar datapoints para ver las opciones de recuperación.

Notas operativas

• Use rutas estrechas para el primer despliegue
• Mantenga el Worker fail-open
• No inyecte el script en respuestas que no sean HTML
• Confirme que su CSP permite la URL del script de cside y el endpoint de intercambio de token
• Mantenga la clave API de fingerprint solo en secretos del backend
• Pase de rutas de prueba a cobertura completa después de ver datapoints en cside