Vai al contenuto
Come usare la Fingerprint API

Genera un fingerprint, iniettalo, mimetizzati.

Richiedi un fingerprint di browser coerente e realistico con una semplice chiamata REST, poi applica i suoi campi a Playwright, Puppeteer o Selenium, così la tua automazione si presenta come un'unica macchina plausibile e coerente.

1. Primi passi

Ottieni una chiave API dalla tua dashboard, poi richiedi un fingerprint. /generate sintetizza un'identità nuova e unica; /random ne restituisce una reale dal pool.

generate.sh
# Generate a fresh, coherent fingerprint (quota deducts on success)
curl "https://api.capzy.ai/fingerprint/generate?key=YOUR_API_KEY&format=chromium&tags=Windows&country=us"
  • Filtra con tags (Windows, macOS, Linux, Android, iOS) e country (ISO alpha-2).
  • format=chromium restituisce campi pronti per l'iniezione; format=raw restituisce i dati completi.
  • La quota viene detratta solo in caso di generazione riuscita.

2. Applicalo nella tua automazione

Imposta sul browser i campi a livello di macchina (userAgent, viewport, lingua, fuso orario), poi allinea il navigator visibile da JS alla stessa macchina prima che venga eseguito qualsiasi script della pagina.

playwright.py
import requests
from playwright.sync_api import sync_playwright

# 1. Generate a coherent fingerprint for a Windows visitor in the US
fp = requests.get("https://api.capzy.ai/fingerprint/generate", params={
    "key": "YOUR_API_KEY",
    "format": "chromium",   # injection-ready
    "tags": "Windows",
    "country": "us",
}).json()

rect = fp["screen"]["screenRect"]

with sync_playwright() as p:
    browser = p.chromium.launch()
    # 2. Apply the machine-level fields on the context
    context = browser.new_context(
        user_agent=fp["userAgent"]["userAgent"],
        locale=fp["intl"]["languages"][0],
        timezone_id=fp["intl"]["timeZone"],
        viewport={"width": rect["width"], "height": rect["height"]},
        device_scale_factor=fp["screen"]["deviceScaleFactor"],
    )
    # 3. Match the JS-visible navigator to the SAME machine (before page scripts)
    context.add_init_script(f"""
      Object.defineProperty(navigator, 'hardwareConcurrency', {{ get: () => {fp['navigator']['hardwareConcurrency']} }});
      Object.defineProperty(navigator, 'deviceMemory', {{ get: () => {fp['navigator']['deviceMemory']} }});
      Object.defineProperty(navigator, 'platform', {{ get: () => '{fp['userAgent']['platform']}' }});
    """)
    page = context.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

I fingerprint di Firefox e Safari funzionano allo stesso modo. I campi di capacità presenti su Chromium (deviceMemory, hardwareConcurrency, client hint) vengono omessi dove un browser reale non li esporrebbe.

3. Formati di risposta

chromium pronto per l'iniezione

Esattamente i campi da impostare sul browser: userAgent, screen, intl, navigator, webgl. Usalo per gli esempi qui sopra.

raw dati completi

Il payload completo del fingerprint (canvas, fonts, visitor_id, webgl_properties) per l'archiviazione o per il tuo iniettore.

4. Mantienilo coerente

Un fingerprint è una singola macchina reale plausibile, non un insieme di campi casuali. Due regole lo rendono credibile:

Applica i campi insieme

Imposta userAgent, client hint e navigator dalla stessa risposta. Sovrascrivere lo UA mentre i client hint riportano il browser originale è l'indizio di automazione numero uno.

Un fingerprint per identità

Riutilizza lo stesso fingerprint per un determinato profilo/sessione. Cambiare i campi a metà sessione sembra una macchina che ha cambiato hardware.

Allinea la geografia del proxy

Abbina il paese richiesto a un IP di uscita in quel paese, così fuso orario, lingua e IP concordano.

5. FAQ

random o generate: quale endpoint?›

/fingerprint/random restituisce un dispositivo reale, raccolto in precedenza, dal pool (economico). /fingerprint/generate ne sintetizza uno nuovo e unico con vincoli di coerenza rigorosi (la quota viene detratta solo in caso di successo). Usa generate quando ti serve un'identità unica.

Formato chromium o raw?›

chromium è pronto per l'iniezione: contiene esattamente i campi da impostare sul browser (userAgent, screen, intl, navigator). raw restituisce i dati completi del fingerprint (canvas, fonts, visitor_id, webgl_properties) per l'archiviazione o per il tuo iniettore.

Devo impostare anche gli header Sec-CH-UA?›

Il fingerprint viene derivato come un'unica macchina, quindi userAgent, header client hint e navigator concordano tutti. L'indizio numero 1 è sovrascrivere lo UA lasciando che i client hint riportino il browser originale, quindi applica i campi insieme e non modificarne a mano uno isolatamente.

Come scelgo un paese o un OS?›

Passa country (ISO alpha-2, determina lingue + fuso orario + voci) e tags (Windows, macOS, Linux, Android, iOS). Consulta la tabella dei parametri nella pagina della Fingerprint API.

Pronto per iniziare?

Ottieni una chiave API e genera il tuo primo fingerprint coerente.

Ottieni la tua chiave API