Cloudflare Workers

Utilisez ce guide pour déployer cside Device Intelligence à l’edge Cloudflare. Il s’agit d’une recette Worker gérée par le client. cside n’a pas besoin de gérer votre compte Cloudflare pour cette configuration.

Avant de commencer

Vous avez besoin de :

• Une zone Cloudflare qui route le trafic des pages à fingerprinter
• L’autorisation de créer ou modifier des Workers et routes Worker
• L’URL du script cside Device Intelligence pour votre domaine, que vous trouverez dans le tableau de bord cside
• Une clé API de Device Intelligence réservée au backend, générée dans le dashboard cside
• Un endpoint backend qui reçoit la chaîne du token extraite de la réponse JSON renvoyée par /client

Déploiement recommandé

Commencez avec une route limitée, comme /login* ou /checkout*, avant d’appliquer le Worker à tout le site. Gardez le Worker fail-open pour qu’un problème cside ou Worker ne bloque pas la livraison des pages.

Consultez le guide Workers Routes de Cloudflare pour savoir comment appliquer un Worker à une route.

Exemple de Worker

Stockez l’URL de votre script cside dans CSIDE_FINGERPRINT_SCRIPT_URL dans l’environnement du Worker.

function getFingerprintBootstrap(scriptURL) {
  return `<script>
(function () {
  const calls = [];
  let error;
  let timeoutID;

  function fallback(externalIds) {
    return error
      ? Promise.reject(error)
      : new Promise((resolve, reject) => {
          calls.push({ externalIds, resolve, reject });
        });
  }

  function rejectAll(nextError) {
    if (error) {
      return;
    }

    error = nextError;
    while (calls.length > 0) {
      calls.shift().reject(nextError);
    }
  }

  function flush(sendClientTelemetry) {
    while (calls.length > 0) {
      const call = calls.shift();
      Promise.resolve()
        .then(() => sendClientTelemetry(call.externalIds))
        .then(call.resolve, call.reject);
    }
  }

  window.sendClientTelemetry = window.sendClientTelemetry || fallback;

  const script = document.createElement("script");
  script.async = true;
  script.src = ${JSON.stringify(scriptURL)};
  script.referrerPolicy = "origin";
  script.setAttribute("data-src", "6");

  const fail = (nextError) => {
    clearTimeout(timeoutID);
    rejectAll(nextError);
  };

  script.onerror = () =>
    fail(new Error("cside client.js failed to load"));
  script.onload = () => {
    clearTimeout(timeoutID);
    const sendClientTelemetry = window.sendClientTelemetry;
    if (
      typeof sendClientTelemetry !== "function" ||
      sendClientTelemetry === fallback
    ) {
      rejectAll(new Error("cside telemetry unavailable"));
      return;
    }
    flush(sendClientTelemetry);
  };

  timeoutID = setTimeout(
    () => fail(new Error("cside client.js timed out while loading")),
    10000,
  );
  (document.head || document.documentElement).appendChild(script);
})();
</script>`;
}

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(
              getFingerprintBootstrap(env.CSIDE_FINGERPRINT_SCRIPT_URL),
              { html: true },
            );
          },
        })
        .transform(response);
    } catch {
      return response;
    }
  },
};

Échange du token

Le Worker injecte seulement le script navigateur. Il ne crée pas de fingerprint de session tout seul. Votre application appelle toujours sendClientTelemetry(externalIds?), reçoit { token } depuis /client et envoie ce token de session à votre backend.

Générez une clé API de Device Intelligence dans le dashboard cside avant de connecter l’échange backend. La clé commence par cside_tgatv1_, elle est affichée une seule fois et doit être stockée comme secret côté serveur. Ne l’intégrez pas dans du code navigateur.

Appelez sendClientTelemetry depuis le code de votre page ou application après le chargement du script, puis lisez la réponse JSON renvoyée par /client :

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("La requête de télémétrie a échoué.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Aucun token de session fingerprint n'a été renvoyé.");
}

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

/client renvoie du JSON au format { "token": "..." }. Vous pouvez aussi appeler sendClientTelemetry() sans argument lorsque vous n’avez pas besoin d’ajouter externalIds.

Votre backend échange le token de session avec cside en appelant l’endpoint de vérification authentifié :

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"'"}'

Exemple 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 || "L'échange de fingerprint a échoué.");
  }

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

Consultez Récupérer les datapoints pour les options de récupération.

Notes opérationnelles

• Utilisez des routes étroites pour le premier déploiement
• Gardez le Worker fail-open
• N’injectez pas le script dans les réponses non HTML
• Confirmez que votre CSP autorise l’URL du script cside et l’endpoint d’échange du token
• Conservez la clé API de Device Intelligence uniquement dans les secrets backend
• Passez des chemins de test à une couverture complète après avoir vu les datapoints dans cside