<ribaunt-widget>, öğede addEventListener ile dinleyebileceğiniz üç DOM özel olayı yayar — verify, error ve state-change. React’te addEventListener yerine türü belirtilmiş geri çağrı prop’larını kullanın; sarmalayıcı, dinleyicileri sizin için otomatik olarak bağlar ve kaldırır.
verify
verify olayı, widget tüm challenge’ları başarıyla çözdüğünde ve bir verify-endpoint sağladıysanız sunucunun çözümlerin geçerli olduğunu onayladığında gönderilir. verify-endpoint ayarlanmadıysa, olay yerel iş kanıtı tamamlanır tamamlanmaz tetiklenir.
Olay türü: CustomEvent<{ solutions: ChallengeSolution[] }>
Burada ChallengeSolution = { nonce: string; hash: string }.
widget.addEventListener('verify', (e) => {
const { solutions } = e.detail;
console.log('Verified! Solutions:', solutions);
// Enable submit button, proceed with form, etc.
});
onVerify={(detail) => ...}
error
error olayı, widget herhangi bir aşamada bir başarısızlıkla karşılaştığında gönderilir — challenge uç noktanızdan token alma, iş kanıtı çözücüsünü çalıştırma veya verify uç noktanızdan OK olmayan bir yanıt alma.
Olay türü: CustomEvent<{ error: string; timeout?: boolean }>
widget.addEventListener('error', (e) => {
const { error, timeout } = e.detail;
if (timeout) {
console.warn('Timed out:', error);
} else {
console.error('CAPTCHA failed:', error);
}
});
onError={(detail) => ...}
timeout alanı, olay ayrıntısında yalnızca solve-timeout yapılandırıldığında ve çözüm süresi bu sınırı aştığında mevcuttur. Mevcut olduğunda her zaman true’dur.
state-change
state-change olayı, widget dahili durumlar arasında her geçiş yaptığında gönderilir. Bunu, widget’ın görsel durumunu kendi UI’nızda yansıtmak için kullanabilirsiniz — örneğin, doğrulama devam ederken bir gönder düğmesini devre dışı bırakmak için.
Olay türü: CustomEvent<{ state: 'initial' | 'verifying' | 'done' | 'error' }>
widget.addEventListener('state-change', (e) => {
const { state } = e.detail;
// 'initial' | 'verifying' | 'done' | 'error'
});
onStateChange={(detail) => ...}
React geri çağrı prop’ları
React sarmalayıcısını kullanırken, tüm geri çağrıları doğrudan prop olarak iletebilirsiniz. Sarmalayıcı, yeniden işlemeler arasında kararlı olay dinleyicisi referansları sağlar, böylece geri çağrılarınız her zaman en son closure değerlerini alır:
<RibauntWidget
challengeEndpoint="/api/captcha/challenge"
verifyEndpoint="/api/captcha/verify"
onVerify={(detail) => console.log('Solutions:', detail.solutions)}
onError={(detail) => console.error('Error:', detail.error)}
onStateChange={(detail) => console.log('State:', detail.state)}
onReady={(detail) => console.log('Ready with state:', detail.state)}
onLoad={(detail) => console.log('Widget loaded:', detail.state)}
onEvent={(type, detail) => console.log('Event:', type, detail)}
/>
Yalnızca React’e özgü olaylar
Web bileşeninde karşılık gelen bir DOM özel olayı olmayan iki ek geri çağrı React sarmalayıcısında kullanılabilir:
onReady — widget bağlandıktan sonra bir kez, ayrıntı yükünde başlangıç widget durumu ile tetiklenir. Widget’ın etkileşime hazır olduğunu bilmek için bunu kullanın.onLoad — işlevsel olarak onReady ile aynıdır. Daha önceki bir sürümde onLoad’u zaten kullanıyor olmanız durumunda geriye dönük uyumluluk için bir takma ad olarak sağlanmıştır.onEvent — her olay türü için ('verify', 'error', 'state-change' ve 'ready'), olayın ayrıntı nesnesiyle birlikte tetiklenen bir yakalama işleyicisi. Tüm widget olaylarını işlemek veya kaydetmek için tek bir yer istiyorsanız bunu kullanın.
Widget, yaşam döngüsü boyunca tanımlanmış bir dizi durumdan geçer. Bu durum dizelerini state-change olaylarında ve getState() dönüş değerinde göreceksiniz:
| Durum | Açıklama |
|---|
initial | Widget yüklendi, kullanıcı tıklamasını veya otomatik doğrulamayı bekliyor |
verifying | Çözücü çalışıyor (iş kanıtı devam ediyor) |
done | Challenge başarıyla çözüldü ve doğrulandı |
error | Veri çekme, çözme veya doğrulama sırasında bir hata oluştu |