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

option	type	default	Açıklama
appKey	string	—	Zorunlu. Fraud Prevention uygulama anahtarınız.
domain	string	signal-v1.world-dynamic.com	SDK'nın istek gönderdiği Signal alan adı.
tokenParam	string	_ctk	SDK'nın tıklama token'ını okuduğu URL sorgu parametresi.
onVerdict	(v) => void	—	Nihai kararla bir kez çağrılır. Birincil entegrasyon noktası. init() ayrıca Promise<BotVerdict> döndürür.
onError	(err) => void	—	Herhangi bir hata durumunda çağrılır. SDK sayfanıza asla istisna fırlatmaz.
onChallenge	(v) => creds | null | Promise<…>	—	Yükseltme kimlik bilgilerini geçersiz kılın: kendi { appKey, serverToken } değerinizi döndürün (serverToken sizin arka ucunuz tarafından verilir) veya yükseltmeyi atlamak için null döndürün. Ayarlanmazsa, verdict.escalate içindeki arka uç tarafından verilen varsayılan kimlik bilgileri kullanılır (sıfır yapılandırma).
challengeConfig	object	—	Captcha görünümü/yerleşimi: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Bir yükseltme captcha'sı gösterildiğinde çağrılır.
onEscalateDone	(passed, detail) => void	—	Yükseltmeden sonra çağrılır. passed = ziyaretçi geçti; detail = geçişin sunucu tarafında doğrulanması için { token, challengeId, cid }.

Yükseltme sunucu tarafından yönetilir. SDK, bir captcha'yı yalnızca sunucunun kararındaki action değeri challenge ve uygulama eşleşen bir yükseltme eylemiyle yapılandırıldığında gösterir — bunun için istemci tarafında bir geçiş anahtarı yoktur. Kendi kimlik bilgilerinizi sağlamak veya yükseltmeyi atlamak için onChallenge, görünümünü kontrol etmek için challengeConfig kullanın. Bir ziyaretçi geçtikten sonra, sonucu kendi arka ucunuzda detail.token (ve challenge_id/cid) ile doğrulayın — yalnızca istemci tarafındaki passed bayrağına güvenmeyin.

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, istemci tarafındaki bir bayrak değil, sunucu kararı tarafından yönetilir — kararın action değeri challenge olduğunda ve uygulamada bir yükseltme eylemi yapılandırıldığında her zaman çalışır.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // ziyaretçiye bir ek doğrulama gösteriliyor
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // ziyaretçi ek kontrolü geçti — detail.token değerini arka ucunuzda doğrulayı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.
• Varsayılan olarak SDK, verdict.escalate içindeki arka uç tarafından verilen kimlik bilgilerini kullanır (sıfır yapılandırma). Kendi { appKey, serverToken } değerinizi sağlamak veya yükseltmeyi atlamak için onChallenge, görünümünü kontrol etmek için challengeConfig kullanın.
• Bir geçişten sonra, detail.token (ve challenge_id/cid) değerini kendi arka ucunuzda doğrulayın — yalnızca istemci tarafındaki passed bayrağına güvenmeyin.
• 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