コンテンツへスキップ
Fingerprint APIの使い方

フィンガープリントを生成し、挿入して、自然に溶け込む。

シンプルなREST呼び出しで、一貫性のある実在のブラウザフィンガープリントをリクエストし、そのフィールドをPlaywright、Puppeteer、Seleniumに適用すれば、自動化したブラウザがもっともらしく一貫した1台のマシンとして認識されます。

1. はじめに

ダッシュボードからAPIキーを取得し、フィンガープリントをリクエストします。/generate は新しい一意のIDを合成し、/random はプールにある実際のものを返します。

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"
  • tags(Windows、macOS、Linux、Android、iOS)とcountry(ISO alpha-2)で絞り込めます。
  • format=chromium はそのまま挿入できるフィールドを、format=raw は完全なデータを返します。
  • クォータは生成が成功したときにのみ消費されます。

2. 自動化に適用する

マシンレベルのフィールド(userAgent、viewport、locale、timezone)をブラウザに設定し、ページのスクリプトが実行される前に、JSから見える navigator を同じマシンに合わせます。

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()

FirefoxとSafariのフィンガープリントも同じように機能します。Chromiumに存在する機能フィールド(deviceMemory、hardwareConcurrency、クライアントヒント)は、実際のブラウザが公開しない場合は省略されます。

3. レスポンス形式

chromium すぐに挿入可能

ブラウザに設定するフィールドそのものです:userAgent、screen、intl、navigator、webgl。上記の例で使用します。

raw 完全なデータ

保存や独自のインジェクター向けの、完全なフィンガープリントのペイロード(canvas、fonts、visitor_id、webgl_properties)です。

4. 一貫性を保つ

フィンガープリントは、ランダムなフィールドの寄せ集めではなく、もっともらしい1台の実在のマシンです。信ぴょう性を保つためのルールは次のとおりです:

フィールドはまとめて適用する

userAgent、クライアントヒント、navigatorは同じレスポンスから設定してください。クライアントヒントが元のブラウザを報告しているのにUAだけを上書きすることは、自動化を見破られる最大の原因です。

1つのIDに1つのフィンガープリント

特定のプロファイル/セッションでは同じフィンガープリントを使い続けてください。セッションの途中でフィールドを変えると、ハードウェアが変わったマシンのように見えます。

プロキシの地域を合わせる

リクエストする国と、その国の出口IPを組み合わせて、タイムゾーン、言語、IPを一致させてください。

5. よくある質問

randomとgenerate:どちらのエンドポイントを使うべきですか?›

/fingerprint/random は、プールから過去に収集した実際のデバイスを返します(安価)。/fingerprint/generate は、厳密な一貫性の制約のもとで新しい一意のデバイスを合成します(クォータは成功時にのみ消費されます)。唯一無二のIDが必要な場合はgenerateを使用してください。

chromium形式とraw形式の違いは?›

chromiumはそのまま挿入できる形式で、ブラウザに設定するフィールド(userAgent、screen、intl、navigator)そのものです。rawは、保存や独自のインジェクター向けに、フィンガープリントの完全なデータ(canvas、fonts、visitor_id、webgl_properties)を返します。

Sec-CH-UAヘッダーも設定する必要がありますか?›

フィンガープリントは1台のマシンとして生成されるため、userAgent、クライアントヒントヘッダー、navigatorはすべて一致しています。最もよくある検出の手がかりは、UAを上書きしたのにクライアントヒントが元のブラウザを報告したままになっていることです。フィールドはまとめて適用し、1つだけを手作業で編集しないでください。

国やOSを指定するには?›

country(ISO alpha-2。言語、タイムゾーン、音声を決定)とtags(Windows、macOS、Linux、Android、iOS)を渡してください。Fingerprint APIページのパラメーター表をご覧ください。

始める準備はできましたか?

APIキーを取得して、最初の一貫したフィンガープリントを生成しましょう。

APIキーを取得