CaptchaAI ile kendi QA'nızda user-agent yönetimi

Güvenli kapsam: Bu kılavuz yalnızca size ait veya yetkilendirilmiş QA, staging ve ön üretim ortamları için geçerlidir. İçerik kendi CAPTCHA entegrasyonlarınız için tanılama, test ve gözlemlenebilirlik kalıplarını ele alır — üçüncü taraf siteleri veya yetkisiz akışları kapsamaz.

Bir QA çalıştırması bugün geçiyor, yarın aynı kodla düşüyorsa suçlu çoğu zaman kodunuz değil, testten teste değişen user-agent string'idir. Kendi staging ortamınızda user-agent'ı sabitlemek testi tekrar üretilebilir kılar: aynı senaryo aynı istemci kimliğiyle çalışır, bir hata raporu da aynı koşullarla yeniden oynatılabilir. Bu bir tanılama pratiğidir.

Aşağıda kendi ortamınızda bugün uygulayabileceğiniz dört adım var: kontrollü bir liste tutmak, her QA senaryosunu tek bir string'e bağlamak, ölçüm üretmek ve sonucu CaptchaAI ile uçtan uca doğrulamak.

Tutarlı user-agent neden QA'nın temelidir

İstanbul'daki bir e-ticaret ekibinin ödeme adımı testini düşünün. Staging'deki formda reCAPTCHA v2 doğrulaması var ve gece koşan CI işi her seferinde rastgele bir string seçiyor: bir gün masaüstü Chrome, ertesi gün mobil bir string. Backend farklı davranıyor, ekip de bunu "flaky test" diye kapatıyor. Oysa ortada gerçek bir yapılandırma farkı var.

Tutarlılık burada üç şey kazandırır: aynı istemci profili, aynı HTTP başlık seti ve aynı ölçüm tabanı. Bu üçü sabitlenmeden hiçbir çözüm oranı veya çözüm süresi karşılaştırılabilir değildir.

Kontrollü bir user-agent listesi tutun

Modern ve gerçek tarayıcılara karşılık gelen kısa bir liste yeterlidir — üç ila beş string, sürüm başına bir tane. Listeyi depoda sürümleyin ve tarayıcı sürümleri ilerledikçe, pratikte 1–2 ayda bir güncelleyin.

Sahte veya elle uydurulmuş string üretmeyin; gerçek bir tarayıcının gönderdiği değeri alın. Eşlik eden başlıkları da ortamınıza göre ayarlayın: Türkiye pazarına hizmet eden bir uygulamanın staging testinde Accept-Language: tr-TR,tr;q=0.9, üretimdekine çok daha yakın bir yanıt üretir.

Her qa_kasasi değerini tek bir string'e bağlayın

Tekrar üretilebilirliğin anahtarı eşlemedir. Her QA senaryosuna bir qa_kasasi kimliği verin ve o kimliği tek bir user-agent ile ilişkilendirin. Rastgele seçim, çalıştırmalar arasında karşılaştırma yapmayı imkânsız kılar.

Pratikte bu küçük bir eşleme tablosudur: qa_kasasi → user-agent → beklenen CAPTCHA türü. Aynı oturum içinde string'i asla değiştirmeyin. Oturum ortasında değişen bir istemci kimliği backend tarafında oturumun geçersiz sayılmasına yol açar ve testin gerçekte ne ölçtüğünü belirsizleştirir.

Gözlemlenebilirlik: ölçmediğinizi düzeltemezsiniz

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 panoları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 sırasında tanılama süresini gözle görülür biçimde kısaltır.

Kayda qa_kasasi değerini ve kullanılan user-agent'ı da ekleyin. Böylece "salı gecesi çözüm süresi neden iki katına çıktı?" sorusunun yanıtı tahmin değil, bir sorgu olur.

Ö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. Görevi gönderin, dönen görev kimliğini saklayın ve sonucu periyodik sorgulama ile alın.

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

API anahtarınızı ortam değişkeninden okuyun; CAPTCHAAI_KEY değeri CI gizli deposunda kalsın. Aynı akışı reCAPTCHA v2'yi API ile çözme, Cloudflare Turnstile'ı API ile çözme veya GeeTest v3'ü API ile çözme rehberlerindeki parametrelerle tekrarlayabilirsiniz.

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 veya kasada saklanır, kaynak kodda asla bulunmaz.
• Her çalıştırma için çağrı süresi, yanıt kodu ve kullanılan user-agent kayıt altına alınır.
• Geçici hatalar için idempotent yeniden deneme stratejisi kuruludur.
• Testler sürekli entegrasyon ortamınızdan tekrarlanabilir biçimde yeniden oynatılır.

Sorun giderme

Thread hesabı: QA hacmi maliyeti nasıl belirler

QA çalıştırmalarınızın toplam sayısı değil, aynı anda kaç testin koştuğu belirleyicidir. CaptchaAI planları thread tabanlıdır ve her plan thread başına sınırsız çözüm içerir; dolayısıyla gecelik regresyon paketinizin büyüklüğü değil, eşzamanlılık düzeyi plan seçimini belirler.

Tek bir CI işinin sırayla koştuğu küçük bir paket için BASIC ($15/ay, 5 thread) genellikle yeterlidir. Paralel çalışan birkaç pipeline'ı olan ekipler STANDARD ($30/ay, 15 thread) ile rahat eder. Nightly ve pull request paketlerini aynı anda koşturan büyük ekipler ADVANCE ($90/ay, 50 thread) seviyesine çıkar. Fiyatlar USD'dir; TL kuru dalgalanırken sabit aylık USD maliyeti, bütçe tarafını öngörülebilir kılar.

KVKK ve test verisi disiplini

Türkiye'de çalışan ekipler için ek bir sınır daha var: test verisi. Staging ortamınıza üretimden kopyalanan kayıtlar kişisel veri içeriyorsa KVKK kapsamına girer. QA senaryolarında +90 formatında sahte telefon numaraları, tr-TR locale string'leri ve Europe/Istanbul saat dilimiyle üretilmiş yapay veri kullanın. Bu hem uyum tarafını rahatlatır hem de testin üretim davranışına yakın kalmasını sağlar.

Sık sorulan sorular

Her testte farklı bir user-agent kullanmalı mıyım?

Hayır. Bir QA senaryosu içinde tek bir string kullanın. Farklı senaryolar farklı string'ler test edebilir, ancak eşleme sabit kalmalı — aksi halde iki çalıştırmanın sonucunu karşılaştıramazsınız.

User-agent listemi ne sıklıkla güncellemeliyim?

Tarayıcı sürümleri ilerledikçe, pratikte 1–2 ayda bir. Eskimiş bir string gerçek kullanıcı davranışını temsil etmediği için testinizin ölçtüğü şeyi de eskitir.

CaptchaAI hCaptcha'yı destekliyor mu?

Hayır. CaptchaAI şu anda hCaptcha ve FunCaptcha (Arkose Labs) çözmüyor. Desteklenen türler reCAPTCHA v2/v3 aileleri, Cloudflare Turnstile ve Cloudflare doğrulama akışı, GeeTest v3, görsel/OCR ve grid CAPTCHA ile BLS'dir. CaptchaFox (beta), Friendly Captcha (beta) ve Lemin (beta) beta aşamasındadır; GeeTest v4 için yalnızca "çok yakında" ifadesi geçerlidir.

Bu akış üretim trafiğine dokunur mu?

Hayır. Tüm örnekler staging.example.com veya kendi QA alan adınız gibi yetkilendirilmiş ortamları varsayar. Üretim CAPTCHA korumasını kendi staging kopyanızda yeniden üretin.

API anahtarımı kodda saklayabilir miyim?

Hayır. Anahtarı CI gizli yöneticisi, ortam değişkeni veya kasa hizmeti üzerinden enjekte edin. Kod tabanına işlenen anahtarlar derhal döndürülmelidir.

Güvenli ilgili kılavuzlar

• Beş dakikada ilk API çağrınız
• Yetkili ortamlarda CAPTCHA QA testleri
• Kendi formlarınızda endpoint doğrulaması
• Tarayıcı testi düşüyor ama API çalışıyor: nereye bakmalı
• 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.