Cloudflare Workers

Gebruik deze handleiding wanneer u cside fingerprinting aan de Cloudflare edge wilt inzetten. Dit is een klantbeheerd Worker-recept. cside hoeft uw Cloudflare-account niet te beheren voor deze setup.

Voordat u begint

U heeft nodig:

• Een Cloudflare-zone die verkeer routeert voor de pagina’s die u wilt fingerprinten
• Toegang om Workers en Worker-routes te maken of aan te passen
• De cside fingerprinting script-URL voor uw domein
• Een backend-only fingerprint-API-sleutel die in het cside-dashboard is gegenereerd
• Een backend-endpoint dat de tokenstring ontvangt die uit de JSON-respons van /client is gehaald

Aanbevolen uitrol

Begin met een beperkte route, zoals /login* of /checkout*, voordat u de Worker over de volledige site routeert. Houd de Worker fail-open zodat een cside- of Worker-probleem de paginaweergave niet blokkeert.

Bekijk de Workers Routes-handleiding van Cloudflare voor hoe u een Worker op een route toepast.

Worker-voorbeeld

Sla uw cside script-URL op als CSIDE_FINGERPRINT_SCRIPT_URL in de Worker-omgeving.

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;
    }
  },
};

Tokenuitwisseling

De Worker injecteert alleen het browserscript. De Worker maakt niet zelf een sessiefingerprint. Uw applicatie roept nog steeds sendClientTelemetry(externalIds?) aan, ontvangt { token } van /client, en stuurt dat sessietoken naar uw backend.

Genereer een fingerprint-API-sleutel in het cside-dashboard voordat u de backenduitwisseling aansluit. De sleutel begint met cside_tgatv1_, wordt maar één keer getoond en moet als server-side secret worden opgeslagen. Plaats deze niet in browsercode.

Roep sendClientTelemetry aan vanuit de code van uw pagina of applicatie nadat het script is geladen, en lees daarna de JSON-respons die door /client wordt teruggegeven:

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

if (result.errors) {
  console.error(result.errors);
  throw new Error("Telemetry-aanvraag is mislukt.");
}

const { token: sessionToken } = result;

if (!sessionToken) {
  throw new Error("Er is geen fingerprint-sessietoken geretourneerd.");
}

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

/client retourneert JSON in de vorm { "token": "..." }. U kunt sendClientTelemetry() ook zonder argumenten aanroepen wanneer u geen externalIds hoeft mee te geven.

Uw backend wisselt het sessietoken uit met cside door het geauthenticeerde verificatie-endpoint aan te roepen:

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

Voorbeeld van een backendhandler:

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 || "Fingerprintuitwisseling is mislukt.");
  }

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

Zie Datapoints ophalen voor ophaalopties.

Operationele notities

• Gebruik smalle routes voor de eerste uitrol
• Houd de Worker fail-open
• Injecteer het script niet in non-HTML responses
• Controleer dat uw CSP de cside script-URL en het tokenuitwisselingsendpoint toestaat
• Bewaar de fingerprint-API-sleutel alleen in backendsecrets
• Ga van testroutes naar volledige dekking nadat u datapoints in cside ziet