AS216394 · WireShield

Dokümantasyon

Kurulum, bağlantı ve günlük operasyon rehberleri.

wsCAPTCHA entegrasyonu

wsCAPTCHA, web sitenizdeki formlardan botları uzak tutan, tıklayarak doğrulanan bir bileşendir. Ücretsizdir, her sitede çalışır ve Web Protection aboneliği gerektirmez.

Ziyaretçiyi nasıl denetler

Ziyaretçi bir kutuyu işaretler. Tarayıcı imzalı küçük bir bulmaca çözer ve birkaç teknik tarayıcı bilgisiyle birlikte gönderir. WireShield cevabı tehdit istihbaratıyla birlikte puanlar:

  • Düşük puan: ziyaretçi hemen geçer.
  • Orta puan: ziyaretçiden basılı tutması istenir, bu yaklaşık bir saniye sürer.
  • Yüksek puan: cevap reddedilir.

Adresin yakın zamandaki davranışı da hesaba katılır. Art arda başarısız denemeler ya da aynı anahtar ve site için çok sayıda geçiş, sonraki denemeyi zorlaştırır. Bulmaca site ve tarayıcı için imzalıdır, beş dakika geçerlidir ve bir kez kullanılır.

1. Anahtar oluşturun

WS Account’unuza girin, wsCAPTCHA sayfasını açın ve Anahtar oluştur’u seçin. Anahtara bir ad verin ve kullanılabileceği alan adlarını yazın (alt alan adları dahildir). Sayfa için bir site anahtarı (wsk_…), sunucunuz için bir gizli anahtar (wss_…) alırsınız.

Gizli anahtar yalnızca anahtarı oluştururken ya da yenilerken bir kez gösterilir. WireShield yalnızca özetini (hash) saklar. Hemen sunucu ayarlarınıza kopyalayın.

2. Bileşeni yerleştirin

<script src="https://captcha.wireshield.network/v1/api.js" async defer></script>

<form action="/register" method="post">
  <input type="email" name="email" required>
  <div class="ws-captcha" data-sitekey="SITE_ANAHTARINIZ"></div>
  <button type="submit">Gönder</button>
</form>

Ziyaretçi doğrulamadan geçince form, ws-captcha-response alanında bir token gönderir.

ÖznitelikAnlamı
data-sitekeySite anahtarınız (zorunlu).
data-themelight ya da dark.
data-langBileşenin dili, tr ya da en. Varsayılan: sayfanın dili.
data-callbackGeçişten sonra token ile çağrılan fonksiyonun adı.
data-expired-callbackToken’ın süresi dolunca çağrılır.
data-error-callbackHata kodu ile çağrılır: quota-exceeded, invalid-domain, invalid-sitekey ya da network-error.
data-response-field-nameToken’ı taşıyan form alanının adı. Varsayılan: ws-captcha-response.

Bileşeni kendiniz çizmek için api.js?render=explicit yükleyin ve wscaptcha.render(element, options) çağırın. api.js?onload=fonksiyonAdi betik hazır olunca fonksiyonunuzu çağırır. wscaptcha.reset() bileşeni sıfırlar, wscaptcha.getResponse() geçerli token’ı verir.

3. Sunucunuzda doğrulayın

Yalnızca forma güvenmeyin. Token’ı ve gizli anahtarınızı doğrulama adresine gönderin ve formu yalnızca success değeri true ise kabul edin.

curl -X POST https://captcha.wireshield.network/v1/siteverify \
  -d "secret=GIZLI_ANAHTARINIZ" \
  -d "response=TOKEN"
# {"success":true,"hostname":"example.com","challenge_ts":"2026-10-26T00:42:02Z","error-codes":[]}
Hata koduAnlamı
missing-input-secret, invalid-input-secretGizli anahtar yok ya da tanınmıyor.
missing-input-response, invalid-input-responseToken yok, geçersiz ya da süresi dolmuş.
timeout-or-duplicateToken daha önce kullanılmış.

Bir token yalnızca bir kez çalışır. Doğrulama isteğinin kendisi başarısız olursa (örneğin zaman aşımı) ne yapılacağına kodunuzda karar verin: formu kabul etmek ya da reddetmek.

reCAPTCHA, hCaptcha ya da Turnstile’dan geçiş

Dört değeri değiştirirsiniz, formunuz ve sunucu kodunuzun geri kalanı olduğu gibi kalır.

reCAPTCHAhCaptchaTurnstilewsCAPTCHA
Betikwww.google.com/recaptcha/api.jsjs.hcaptcha.com/1/api.jschallenges.cloudflare.com/turnstile/v0/api.jscaptcha.wireshield.network/v1/api.js
Eleman sınıfıg-recaptchah-captchacf-turnstilews-captcha
Form alanıg-recaptcha-responseh-captcha-responsecf-turnstile-responsews-captcha-response
Doğrulama adresi…/recaptcha/api/siteverifyapi.hcaptcha.com/siteverify…/turnstile/v0/siteverifycaptcha.wireshield.network/v1/siteverify

Doğrulama cevabı aynı biçimdedir: success, hostname, challenge_ts ve error-codes. Sunucu kodunuza dokunmamak için data-response-field-name değerini zaten okuduğunuz alan adına ayarlayın, örneğin data-response-field-name="g-recaptcha-response".

wsCAPTCHA görünür, tıklayarak doğrulanan bir bileşendir. reCAPTCHA v3 gibi görünmez, skor tabanlı denetimlerin bir karşılığı yoktur.

Content-Security-Policy kullanıyorsanız betikler ve bağlantılar için https://captcha.wireshield.network adresini eklemeyi unutmayın.

Sınırlar

  • Aylık doğrulama: hesabınızın bir aydaki başarılı doğrulamaları sayılır ve portalınızda gösterilir. Sınıra ulaşılınca bileşen ay sonuna kadar quota-exceeded cevabı verir. Daha önce verilmiş token’lar doğrulamadan geçmeye devam eder. %80 ve %100’de e-posta alırsınız.
  • Anahtar sayısı: hesap başına anahtar sayısı da sınırlıdır.
  • Hız sınırları: adres başına dakikada 120 bulmaca ve 60 cevap. Doğrulama adresi dakikada 1200 isteği kabul eder.

Daha yüksek sınır mı gerekiyor? İletişim sayfasından bize yazın.

wsCAPTCHA’yı Web Protection ile kullanmak

Siteniz WireShield Web Protection ile korunuyorsa, challenge ayarlarında etkileşimli doğrulama olarak wsCAPTCHA’yı seçebilirsiniz. Bunun için anahtar gerekmez. Cevap kendi alan adınızda denetlenir ve başarılı geçişte bir geçiş çerezi verilir.

Bu rehberle ilgili sorunuz mu var?
Teknik ekibe sorun