Karar Referansı

Her Fraud Prevention kararı — ister Web SDK içindeki onVerdict geri çağırmanıza teslim edilsin, ister Data API üzerinden çekilsin — aynı BotVerdict nesnesidir. Bu sayfa her alanı ve buna göre nasıl hareket edileceğini belgeler.

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "reasons": [],
  "consistency": { "ok": true },
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

Alanlar

Alan	Tür	Açıklama
is_bot	boolean	Ana karar. true = ziyaret otomatik veya geçersiz trafik olarak değerlendirilir; false = gerçek bir kişi gibi görünür. Çoğu entegrasyonun dallandığı tek alan budur.
score	number (0–100)	Ziyaretin ne kadar şüpheli olduğu. Yüksek olması daha şüpheli demektir. Kendi eşiklerinizi belirlemek için kullanın — ör. seçtiğiniz bir kesim değerinin üzerindeki ziyaretleri hariç tutun. Tam değer risk modelimiz tarafından üretilir ve tersine mühendislik yapılması amaçlanmamıştır.
level	enum	score değerinin kaba bandı: low, medium, high, critical. Ham bir sayı yerine kovalar istediğinizde kullanışlıdır.
action	enum	Ziyaret için önerdiğimiz işleme: record_only, challenge, flag veya deny. Aşağıya bakın. Bilinmeyen değerleri flag olarak ele alın; böylece yeni değerler eklendiğinde entegrasyonunuz çalışmaya devam eder.
reasons	string[]	Riskli bir kararı açıklayan en fazla üç genel neden kategorisi. Temiz ziyaretlerde boştur.
consistency	object	Sinyaller arası bir tutarlılık sonucu. consistency.ok değerini okuyun (boolean): true = ziyaretin sinyalleri beklendiği gibi örtüşür; false = bir şey uyuşmadı ve ziyaret ekstra incelemeyi hak ediyor. Bu sonucun arkasındaki iç ayrıntılar açığa çıkarılmaz.
degraded	boolean	Karar tam olarak hesaplanamadığında (servise ulaşılamaması, hata vb.) ve muhafazakâr bir yedek döndürüldüğünde true. Düşürülmüş kararları "temiz" değil "bilinmeyen" olarak ele alın.
verdict_id	string	Bu kararın benzersiz id'si. Kararı daha sonra Data API ile sorgulamak için kullanın.
verdict_token	string	Bu kararın, sunucunuzun doğrulaması için imzalı kanıtı. Bkz. Sunucu tarafı doğrulama. Yedek kararlarda bulunmaz.
verdict_token_exp	number	verdict_token değerinin süresinin dolduğu Unix zamanı (saniye).

action — ne yapmalı

action bizim önerimizdir; nihai karar üzerindeki kontrol sizde kalır.

action	Anlamı	Ne yapmalı
record_only	Ziyaret normal görünüyor.	Her zamanki gibi devam edin. Sadece kararı raporlama ve mutabakat için kaydedin.
flag	Ziyaret şüpheli ama kesin olarak kötü değil.	Sayfayı sunmaya devam edin, ancak ziyareti düşük kaliteli olarak işaretleyin — metriklerinizden çıkarın, alt akış süreçlerinden ayırın ve kendi kararlarınızda ağırlıklandırın (ör. dönüşüm atıfı veya ziyarete ne kadar güvendiğiniz).
challenge	Ziyaret, challenge eşiğinize ulaştı (varsayılan olarak yüksek risk).	Ziyaretçiyi insan olarak ele almadan önce bir ek doğrulama isteyin. Uygulamanızın işleme eylemi challenge olarak ayarlandığında Web SDK bunu sizin için çalıştırır (bkz. Yükseltme); aksi halde kendi geçidinizi uygulayın.
deny	Ziyaret bir engelleme kuralıyla eşleşti — örneğin bir kara liste kaydı veya engelleme için yapılandırdığınız bir politika.	Korunan içeriği sunmayın. Doğrulama sunulmaz. Eski SDK sürümleri bu değeri değiştirmeden iletir; bu yüzden onu onVerdict içinde ele alın.

Yapılandırılabilir işleme eylemi

Yüksek riskli bir ziyaret için action değerinin ne raporladığı uygulama başına yapılandırmadır ve kontrol panelinde uygulamanızın ayrıntıları altında ayarlanır. Karar sunucu-yetkilidir: action yalnızca ziyaret yüksek risk bandına ulaştığında ve uygulamanız eşleşen eylemle yapılandırıldığında challenge veya flag olur. Bu bandın altında karar record_only olarak kalır.

Ayar	Yüksek riskte döndürülen action	Anlamı
record_only (varsayılan)	record_only	Yalnızca kaydet. Karar raporlama ve mutabakat için kaydedilir; ziyaretçiden hiçbir şey istenmez.
challenge	challenge	Bir yeniden-doğrulama CAPTCHA'sı tetikler. Web SDK bir challenge açar (stillendirme SDK'nın challengeConfig ayarıyla kontrol edilir).
flag	flag	Ziyareti işaretle. Karar flag taşır; entegrasyonunuz buna nasıl tepki vereceğine karar verir (engelle / ayır / işle).

Karar sunucu tarafında verildiği için kodunuz basit kalır: onVerdict içinde verdict.action değerini okuyun ve buna göre hareket edin — devam edin, engelleyin veya SDK'nın bir challenge sunmasına izin verin. Riski kendiniz yeniden türetmenize gerek yoktur.

Doğrulama eşiği ve türü

Eylem challenge olduğunda panelin aynı bölümünde iki ayar daha görünür:

• Doğrulama eşiği — yapılandırılan eylemin hangi risk seviyesinden itibaren döndürüleceği. Varsayılan yüksek risk ve üzeridir. Katı mod bunu orta riskli ziyaretlere de uygular: daha fazla kazıyıcı ve yapay zekâ ajanı durdurulur, ancak daha fazla gerçek ziyaretçi doğrulama görür.
• Doğrulama türü — yükseltmede gösterilecek en düşük CAPTCHA türü: kaydırıcı (varsayılan), döndürme, tıklama veya 3D tıklama. Güçlü türleri otomasyon ve yapay zekâ araçları daha zor çözer.

escalate_result

Yönetilen bir captcha yükseltmesi çalıştıktan sonra bulunur — yani action challenge olduğunda ve SDK captcha'yı çalıştırdığında. Hiç yükseltme çalışmadığında null. Ayrıca onEscalateDone(passed, detail)'a iletilir.

alan	açıklama
passed	ziyaretçinin captcha'yı geçip geçmediği
token	captcha pass token'ı — geçişi doğrulamak için sunucu tarafında doğrulayın (yalnızca istemcideki passed'a güvenmeyin)
challenge_id	captcha challenge id'si
cid	bir click token mevcutsa bu yükseltmenin bağlı olduğu click id

reasons — neden kategorileri

reasons, bir ziyaretin neden riskli göründüğünü genel hatlarıyla anlatır. En fazla üç kategori içerir, en güçlüsü önce gelir. Hiçbir zaman tek tek sinyalleri veya puan dökümünü içermez.

Kategori	Anlamı
automation	Betikli veya headless tarayıcılar gibi otomasyon araçlarına dair işaretler.
network	Ağ riskli veya tutarsız görünüyor; örneğin bir proxy, veri merkezi veya anonimleştirici ağ ya da engellenmiş bir adres.
abnormal_requests	Çok fazla istek, tekrarlanan hatalar veya otomatik trafik geçmişi gibi olağandışı istek kalıpları.
device	Cihaza veya ortamına güvenilemedi ya da tanınamadı.
behavior	Ziyaret bir insan gibi davranmadı; örneğin hiç etkileşim olmaması veya yeniden kullanılan bir bağlantı.
other	Kendi kurallarınız ve yedek kararlar dahil diğer tüm nedenler.

Bu listeyi kural oluşturmak için bir sinyal olarak değil, raporlama için bir açıklama olarak ele alın. Bunun yerine is_bot, action veya score üzerinden dallanın. İleride yeni kategoriler eklenebilir.

Sunucu tarafı doğrulama

Sayfanın aldığı her şey ziyaretçi tarafından değiştirilebilir. İçeriği koşula bağlıyorsanız (bir sayfayı, API yanıtını veya indirmeyi yalnızca gerçek kişiler görebilir), tarayıcıdaki is_bot bayrağına güvenmeyin. verdict_token değerini kendi sunucunuza gönderin ve orada doğrulayın:

1. onVerdict içinde verdict.verdict_token değerini backend'inize gönderin, örneğin bir header veya cookie içinde.
2. Backend'iniz token ve ziyaretçinin IP adresiyle POST /v1/bot/verdict/verify çağrısı yapar.
3. İçeriği yalnızca yanıtta valid: true olduğunda ve karar sizin için kabul edilebilir olduğunda (örneğin verdict.is_bot false ise) sunun.

Token uygulamanıza, bu karara ve ziyaretçinin ağına bağlıdır ve kısa bir süre sonra (varsayılan olarak 10 dakika) sona erer. Varsayılan olarak bir token birçok kez kontrol edilebilir; böylece tek bir token bir ziyaretin sayfa görüntülemelerini kapsayabilir. Bir token'ın yalnızca bir kez kullanılması gerektiğinde, örneğin bir form gönderiminde, consume: true iletin.

Ziyaretçi ardından bir yükseltme doğrulamasını geçerse token yine de ilk kararı gösterir. escalate_result içindeki captcha pass token'ını da captcha sunucu tarafı API'si ile doğrulayın.

level ile score

level, kolaylık için sağlanan, score değerinin yalnızca bir bantlamasıdır:

level	Ne zaman kullanılır
low	Temiz trafik olarak ele alın.
medium	Sınırda — kaydetmek sorun değil, yüksek değerli hunilerden hariç tutmayı düşünün.
high	Kuvvetle şüpheli — işaretleyin ve hariç tutun.
critical	Neredeyse kesinlikle geçersiz — işaretleyin/hariç tutun ve ideal olarak yükseltin.

İş akışınıza uyan alanı seçin

• Basit evet/hayır geçidi → is_bot üzerinde dallanın.
• Öneri odaklı → action üzerinde dallanın.
• Özel eşikler → score üzerinde dallanın (veya kovalar için level).

Düşürülmüş kararları ele alma

degraded değeri true olduğunda, karar tam olarak hesaplanmamıştır. Yedek değer kasıtlı olarak muhafazakârdır (is_bot: false, action: record_only); böylece gerçek kullanıcılar asla engellenmez. Raporlamada bunları onaylı-temiz trafik olarak saymak yerine bilinmeyen olarak ele alın.

Sonraki adımlar

• Web SDK — kararları sayfanızda alın
• Data API — kararları ve istatistikleri sunucu tarafında çekin