reCAPTCHA v3 skorunu kendi uygulamanızda iyileştirme

Güvenli kapsam: Bu rehber yalnızca size ait ya da yetkilendirilmiş QA, staging ve ön üretim ortamları içindir. Anlatılan her şey kendi CAPTCHA entegrasyonunuzun tanılaması, testi ve gözlemlenebilirliği ile ilgilidir — üçüncü taraf siteleri veya yetkisiz akışları kapsamaz.

reCAPTCHA v3 kullanıcıya bir kutucuk göstermez; arka planda 0,0 ile 1,0 arasında bir skor üretir ve 1,0'a yaklaştıkça "daha insan" demektir. Çoğu düşük skorun nedeni kötü niyetli kullanıcı değildir — entegrasyonun kurgusudur. Yanlış action adı, tek bir global eşik ve düşük skorda kapıyı doğrudan kapatan bir mantık, gerçek müşterinizi de bot muamelesi görmeye iter. Aşağıda, kendi uygulamanızı bu tuzaklara düşmeyecek şekilde tasarlamanın ve sonucu QA'da kanıtlamanın yolunu bulacaksınız.

reCAPTCHA v3 skoru gerçekte neyi ölçer?

Skor tek bir sinyal değildir; Google'ın oturum boyunca gözlemlediği davranış, etkileşim ritmi ve sayfa bağlamının bileşkesidir. Sizin kontrolünüzde olan kısım, kullanıcının bu sinyalleri doğal biçimde üretebileceği bir akış kurmaktır: script'i sayfa yüklenirken erkenden çağırıp kullanıcı hiçbir şeye dokunmadan token üretmeyin, grecaptcha.execute çağrısını gerçek bir niyet anına (form gönderimi, giriş denemesi) bağlayın. Skorun kendisi Google tarafından atanır; sizin işiniz bu skoru düşüren yapay kalıpları entegrasyondan çıkarmaktır.

Action adlarını temiz ve anlamlı tutun

Her fonksiyona kendi action adını verin: login, signup, checkout. Tek bir genel ad ("submit" gibi) kullanmak, farklı risk profillerine sahip akışları aynı sepete koyar ve eşik ayarınızı körleştirir. Ad, sayfadaki gerçek işlemle birebir örtüşmelidir; backend token'ı doğrularken bu action değerini kontrol eder ve uyuşmazlık doğrudan redle sonuçlanır.

Her akışa ayrı eşik belirleyin

Tek bir global eşik neredeyse her zaman yanlış karardır. Bir login akışında 0,5 makul bir alt sınırken, checkout gibi para hareketi olan bir adımda daha temkinli, düşük hacimli bir yorum akışında ise daha esnek davranmak istersiniz. Eşikleri action bazında ayırın ve üretim verinizle kalibre edin — sabit bir değeri belgeye bakıp kopyalamak yerine, kendi kullanıcı dağılımınıza göre belirleyin. Aşağıdaki değerler yalnızca bir başlangıç noktasıdır; kendi verinizle doğrulayıp güncelleyin:

Düşük skorda insan yedek akışı sunun

Düşük skor "bu bir bottur" anlamına gelmez; "emin değilim" anlamına gelir. Skoru eşiğin altında kalan kullanıcıyı doğrudan reddetmek yerine ikinci bir adım sunun: bir reCAPTCHA v2 onay kutusu, SMS/e-posta doğrulaması ya da hafif bir sürtünme adımı. Bu yaklaşım, gerçek kullanıcıyı kaybetmeden şüpheli trafiği süzer. Kapıyı sertçe kapatan bir mantık, dönüşüm oranınıza sessizce zarar verir ve bunu genellikle aylar sonra fark edersiniz.

Yerel senaryo: e-ticaret ödeme akışı

Türkiye'deki geliştirici ekiplerin büyük kısmı e-ticaret ve ödeme entegrasyonlarıyla uğraşır; bu da v3'ün en kritik olduğu yerdir. Bir ödeme adımında agresif bir eşik, tam alışverişi tamamlamak üzere olan gerçek müşteriyi engellerse doğrudan gelir kaybıdır. Böyle bir akışta önerilen kurgu: checkout action'ına ayrı, ölçülmüş bir eşik; eşiğin hemen altındaki kullanıcıya v2 onay kutusu; ve tüm bu davranışın kendi staging kopyanızda tekrar tekrar test edilmesi. Toplanan her sinyalin kişisel veri boyutu olabileceğini de unutmayın — KVKK kapsamında, doğrulama akışında işlenen verinin yalnızca yetkili QA ve üretim amaçlarıyla sınırlı kalması gerekir.

CaptchaAI ile QA'da doğrulama

Eşiklerinizi ve yedek akışınızı gerçek üretim trafiğine güvenmeden sınamanın yolu, tam akışı kendi staging ortamınızda çalıştırmaktır. CaptchaAI'yi bu noktada bir QA aracı olarak kullanırsınız: kendi test sayfanızdaki v3 widget'ını uçtan uca çalıştırıp backend doğrulamanızın, eşik mantığınızın ve yedek akışınızın beklendiği gibi davrandığını gözlemlersiniz. Fiyatlandırma thread bazlıdır ve TL yerine sabit USD üzerinden ilerler; küçük bir QA hattı için BASIC ($15/ay, 5 thread) fazlasıyla yeterlidir.

Gözlemlenebilirlik ve günlükler

Her QA çalıştırması için yapılandırılmış günlükler üretin. Toplam token süresi, HTTP yanıt kodu, görev kimliği ve kuyruk derinliği gibi ölçümler tablolarınızı ve uyarılarınızı besler. Ortamlarınızı (geliştirme, staging, ön üretim) ayrı kanallara yazın ve dağıtık izleme (örneğin OpenTelemetry) ile bağıntı kimliklerini eşleştirin. Tek bir kimlikten tüm senaryoyu yeniden oynatabilmek, olay anında tanılama süresini yarıya indirir.

QA'da sık karşılaşılan sorunlar

Kendi staging kopyanızda akışı çalıştırırken en sık şu üç durumla karşılaşırsınız; her biri entegrasyonun bir katmanına işaret eder.

Yayına almadan önce kontrol listesi

• Kapsam kesinlikle kendi uygulamalarınız veya yetkilendirilmiş kaynaklarla sınırlıdır.
• CaptchaAI anahtarı CI gizli deposunda ya da kasada saklanır, kaynak kodda asla bulunmaz.
• Her action için ayrı, üretim verisiyle kalibre edilmiş bir eşik tanımlıdır.
• Eşiğin altındaki kullanıcı için bir insan yedek akışı (v2 veya ek adım) hazırdır.
• Her çalıştırma için çağrı süresi ve yanıt kodu kayıt altına alınır.
• Geçici hatalar için idempotent yeniden deneme stratejisi kuruludur.

Örnek QA çağrısı

Aşağıdaki Python örneği, kendi staging ortamınızdaki bir CAPTCHA widget'ını CaptchaAI üzerinden test etmek için kullanılan minimal akışı gösterir.

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']
QA_PAGE_URL = os.environ['QA_PAGE_URL']  # ör. https://staging.example.com/qa-login
QA_SITE_KEY = os.environ['QA_SITE_KEY']


def submit_qa_recaptcha() -> str:
    payload = {
        'clientKey': API_KEY,
        'task': {
            'type': 'NoCaptchaTaskProxyless',
            'websiteURL': QA_PAGE_URL,
            'websiteKey': QA_SITE_KEY,
        },
    }
    response = requests.post(
        'https://api.captchaai.com/createTask',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()['taskId']


def fetch_qa_result(task_id: str) -> dict:
    payload = {'clientKey': API_KEY, 'taskId': task_id}
    response = requests.post(
        'https://api.captchaai.com/getTaskResult',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Sık sorulan sorular

reCAPTCHA v3 skoru tam olarak neyi ölçer?

Skor 0,0 ile 1,0 arasında bir güven değeridir; 1,0'a yakın skor "muhtemelen gerçek kullanıcı" anlamına gelir. Değeri Google atar, CaptchaAI değil. Sizin etkiniz, kullanıcının doğal sinyal üretebileceği bir akış kurmakla sınırlıdır.

Gerçek kullanıcılar neden bazen düşük skor alır?

Genelde entegrasyon nedeniyle: script'in kullanıcı etkileşiminden önce erkenden çalışması, akışla uyuşmayan bir action adı ya da bağlam kurulmadan tetiklenen bir execute çağrısı. Kişiyi değil, kurguyu düzeltmek skoru toparlar.

Düşük skorlu kullanıcıları doğrudan reddetmeli miyim?

Hayır. Düşük skor kesinlik değil, belirsizlik sinyalidir. Doğrudan red yerine bir v2 onay kutusu veya ek doğrulama adımı sunun; böylece gerçek kullanıcıyı kaybetmeden şüpheli trafiği süzersiniz.

Kendi v3 akışımı test etmek için hangi plan yeterli?

Küçük bir QA hattı için BASIC ($15/ay, 5 thread) yeterlidir. Fiyatlandırma thread bazlıdır ve sabit USD üzerinden ilerler; ihtiyaç büyüdükçe STANDARD ($30/ay, 15 thread) gibi üst planlara geçebilirsiniz.

Geçici hatalar için ne öneriyorsunuz?

İdempotent yeniden deneme: üstel geri çekilme (exponential backoff, örneğin 1s, 2s, 4s) ve bir üst sınır. Ağ hataları, 5xx yanıtları ve ERROR_NO_SLOT_AVAILABLE için yeniden deneme uygundur; kalıcı kimlik doğrulama hataları için değildir.

İlgili güvenli kılavuzlar

• CaptchaAI hızlı başlangıç rehberi
• Yetkili CAPTCHA QA testleri
• Kendi formlarınızda CAPTCHA endpoint testleri
• Tarayıcı testi başarısız ama API başarılı: hata ayıklama
• reCAPTCHA v2'yi API ile çözme
• Cloudflare Turnstile'ı API ile çözme
• GeeTest v3'ü API ile çözme

CAPTCHA entegrasyonunuzu kendi ortamınızda CaptchaAI ile doğrulayın.