Fraud Prevention Web SDK

Fraud Prevention Web SDK, sizin sayfanızda çalışır — bir açılış sayfası, bir kayıt veya oturum açma ekranı ya da korumak istediğiniz herhangi bir kaynak. Mevcut ziyaret için bir karar ister ve bunu kodunuza geri teslim eder; böylece trafiğe ne yapacağınıza karar verebilirsiniz — kaydetmek, işaretlemek veya ziyaretçiden bir ek doğrulama istemek.

Hızlı başlangıç

<!-- Fraud Prevention SDK'sını yükle -->
<script src="https://cdn.captcha-cdn.net/bot-signal.js"></script>

<script>
  BotSignal.init({
    appKey: 'YOUR_APP_KEY',
    onVerdict: function (verdict) {
      // verdict.is_bot, verdict.score, verdict.action — bkz. Karar Referansı
      if (verdict.is_bot) {
        // bu ziyareti huninizden çıkarın / dönüşümlerini bastırın
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>

BotSignal.init() ayrıca bir Promise<BotVerdict> döndürür; bu nedenle onVerdict yerine onu await ile de kullanabilirsiniz — her ikisi de aynı karar nesnesini alır.

const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });

Seçenekler

Seçenek	Tür	Varsayılan	Açıklama
appKey	string	—	Fraud Prevention uygulama anahtarınız (zorunlu).
domain	string	servis varsayılanı	Karar servisi uç noktası. Size özel bir alan adı verilmedikçe ayarlamadan bırakın.
escalate	boolean	false	Bir ziyaret yüksek riskli göründüğünde Fraud Prevention'ın ziyaretçiden bir ek doğrulama istemesine izin verir. Bkz. Yükseltme.
collectWindowMs	number	1200	SDK'nın bir karar istemeden önce ziyareti ne kadar (ms) gözlemlediği. Daha uzun pencereler, küçük bir gecikme karşılığında daha emin bir karar verir.
onVerdict	(v) => void	—	Nihai kararla bir kez çağrılır. Birincil entegrasyon noktası.
onError	(err) => void	—	Bir şeyler ters giderse çağrılır. SDK sayfanıza asla istisna fırlatmaz.
onEscalate	(displayType) => void	—	Bir ek doğrulama gösterildiğinde çağrılır (yalnızca escalate: true iken).
onEscalateDone	(passed) => void	—	Ek doğrulama bittikten sonra çağrılır; ziyaretçi geçtiyse passed değeri true olur.

Trafik kaynağı senaryoları

Bir üçüncü taraf size ziyaretçi getiriyorsa ve her iki tarafın tıklama başına bir sonuç üzerinde mutabık kalması gerekiyorsa, SDK sayfa URL'sinden bir tıklama token'ı da okuyabilir. Bu, ücretli trafik akışlarına özgüdür — bkz. Reklam dolandırıcılığı kılavuzu.

Kararı kullanma

onVerdict, bir BotVerdict nesnesi alır. En çok kullanacağınız iki alan:

• verdict.is_bot — ziyaret otomatik/geçersiz olarak değerlendirildiğinde true.
• verdict.action — yapmanızı önerdiğimiz: record_only, challenge veya flag.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // normal görünen trafik — devam edin, sadece kararı kaydedin
        break;
      case 'flag':
        // şüpheli — sayfayı sunmaya devam edin ama bu ziyareti düşük kaliteli işaretleyin
        markLowQuality(verdict);
        break;
      case 'challenge':
        // yüksek risk — etkinse yükseltme tarafından ele alınır (aşağıya bakın)
        break;
    }
  },
});

Tam alan listesi ve önerilen işleme yöntemleri için Karar Referansı sayfasına bakın.

Yükseltme

Bir ziyaret yüksek riskli göründüğünde, Fraud Prevention onu gerçek bir kullanıcı olarak ele almadan önce ziyaretçiden bir ek doğrulamayı tamamlamasını isteyebilir. Bu, isteğe bağlıdır.

escalate: true ile etkinleştirin:

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // ziyaretçiye bir ek doğrulama gösteriliyor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // ziyaretçi ek kontrolü geçti — insan olarak ele alın
    } else {
      // geçmedi — orijinal kararın önerisini koruyun
    }
  },
  onVerdict: function (verdict) {
    // ziyaretçi yükseltmeyi geçtiyse, verdict.is_bot false olarak güncellenir
  },
});

Notlar:

• Yükseltme yalnızca kararın action değeri challenge olduğunda tetiklenir. Diğer tüm ziyaretlerde hiçbir şey gösterilmez ve ziyaretçi deneyimine dokunulmaz.
• Ziyaretçi ek doğrulamayı geçerse, onVerdict ile teslim edilen karar bunu yansıtır (insan olarak ele alınır).
• Yükseltme açık şekilde başarısız olur (fail open): ek doğrulama yüklenemez veya gösterilemezse, SDK sayfanızı engellemek yerine orijinal kararı korur.

INFO

Fraud Prevention sizin yerinize asla karar vermez. challenge/flag durumunda bile ziyaretin devam edip etmeyeceği konusunda kontrol sizin kodunuzda kalır — SDK yalnızca kararı yüzeye çıkarır ve isteğe bağlı olarak ek doğrulamayı çalıştırır.

Dayanıklılık

Karar servisine ulaşılamazsa veya herhangi bir hata oluşursa, SDK sayfanızı başarısız kılmak yerine düşürülmüş (degraded) bir karar (degraded: true) döndürür. Düşürülmüş bir karar muhafazakârdır (is_bot: false, action: record_only), bu yüzden gerçek kullanıcıları asla engellemez. Bu ziyaretleri özel olarak ele almak isterseniz verdict.degraded değerini kontrol edin.

Sonraki adımlar

• Karar Referansı — her alan ve buna göre nasıl hareket edilir
• Data API — kararları sunucu tarafında çekin ve mutabık kalın