Tarayıcı Çalışma Zamanı

Bu kılavuz, Noxtica SDK’nın ziyaretçilerinizin tarayıcılarında nasıl çalıştığını açıklar — değerlendirme sırasında neler olduğunu, önbelleğin işleri nasıl hızlı tuttuğunu ve sık karşılaşılan sorunları nasıl gidereceğinizi.

Nasıl Çalışır

Noxtica SDK’sını sayfanıza eklediğinizde arka planda sessizce dört şey yapar:

1. Kimlik Doğrulama: Sizin için yönettiği kimlik bilgileriyle Site Anahtarınızı kullanarak oturum açar
2. Toplama: Tarayıcının zaten açığa çıkardığı olağan sinyalleri okur
3. Gönderim: Bunları puanlama için Noxtica’ya gönderir
4. Önbellekleme: Sonucu yerelde saklar, böylece her ziyarette aynı işi tekrarlamaz

Bunların hepsi arka planda çalışır ve sayfanızı hiçbir zaman engellemez.

Toplama Akışı

Otomatik (Önerilen)

data-auto-check-once kullanıldığında SDK akıllı toplamayı devreye sokar:

<script
	src="https://collect.noxtica.com/collector/noxtica.js"
	data-site-key="pk_prod_your_site_key"
	data-auto-init
	data-auto-check-once
	async
></script>

İçerik güvenlik ilkesi kullanıyor musunuz? Noxtica’nın kurcalamaya dirençli çalışma ortamı olan KHAN VM’i yükleyip çalıştırabilmesi için izin vermeniz gerekir. Etkinleştirilemezse Noxtica, isteği başarısız kılmak yerine daha hafif bir toplama biçimiyle çalışmaya devam eder ve kurcalama koruması zayıflar. Tam kod parçacığı için bkz. Başlarken → İçerik Güvenlik İlkesi.

İlk ziyaret: Tam değerlendirme çalışır ve sonuç önbelleğe alınır.

Sonraki ziyaretler (önbellek penceresi içinde): Önbelleğe alınan sonuç döndürülür ve hafif bir ziyaret kaydedilir. Ağır işlem tekrar çalışmaz.

Önbellek süresi dolduktan sonra: Yeni bir değerlendirme çalışır.

Manuel Kontrol

Programatik kontrol için checkOnce() yöntemini kullanın:

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_your_site_key',
});

const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached fingerprint');
	console.log('Next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh fingerprint collected');
}

Önbellekleme Davranışı

SDK her sonucu tarayıcıda önbelleğe alır; böylece aynı ziyaretçiyi her sayfa görüntülemesinde yeniden değerlendirmez.

Önbellek Anahtarı

nox_fp_{your_site_key}

Önbelleğe Alınanlar

• Cihaz kimliği
• Son gönderim zaman damgası
• Son görülme zaman damgası
• Önceki risk skoru ve seviyesi

TTL (Yaşam Süresi)

Varsayılan önbellek süresi 7 gündür. Yapılandırılabilir:

// Toplama sırasında geçersiz kılın
const result = await client.checkOnce({
	checkIntervalDays: 14, // 7 yerine 14 gün
});

// Veya saniye cinsinden
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 gün
});

Yenilemeyi Zorla

Önbelleği atlayıp taze parmak izi toplamak için:

const result = await client.checkOnce({
	forceRefresh: true,
});

Sekme Koordinasyonu

Ziyaretçi sitenizin birden fazla sekmesini aynı anda açtığında SDK yalnızca bir kez değerlendirme yapılmasını sağlar:

• Gerçek işi yalnızca bir sekme yapar
• Diğer sekmeler bekler ve o sonucu paylaşır

Bu otomatik olarak gerçekleşir — yapılandırma gerekmez.

Olaylar

SDK dinleyebileceğiniz olaylar yayımlar:

noxtica:collected

Başarılı toplama sonrasında veya önbelleğe alınmış sonuç döndüğünde tetiklenir:

document.addEventListener('noxtica:collected', (e) => {
	console.log('Fingerprint ID:', e.detail.fingerprintId);
	console.log('Risk Level:', e.detail.risk_level);
	console.log('Score:', e.detail.score);
	console.log('From Cache:', e.detail.fromCache);
});

noxtica:cache-hit

Özellikle önbelleğe alınmış bir sonuç döndüğünde tetiklenir:

document.addEventListener('noxtica:cache-hit', (e) => {
	console.log('Cache hit, days since submission:', e.detail.daysSinceSubmit);
});

noxtica:error

Toplama başarısız olduğunda tetiklenir:

document.addEventListener('noxtica:error', (e) => {
	console.log('Error source:', e.detail.source);
	console.log('Error message:', e.detail.message);
});

Global Değişkenler

Toplamadan sonra sonuçlara global olarak erişilebilir:

// Toplama tamamlandıktan sonra
console.log(window.noxticaResult);

// İstemci örneği (otomatik başlatma kullanıldığında)
console.log(window.noxticaClient);

// Son hata (varsa)
console.log(window.noxticaLastError);

Hata Yönetimi

Sık Karşılaşılan Hatalar

Hataları Manuel Yönetmek

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Site anahtarı yapılandırma sorunu
	} else if (error.message.includes('rate')) {
		// Geri çekilip daha sonra tekrar deneyin
	}
}

Toplama Modları

SDK üç toplama modunu destekler:

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	mode: 'max', // veya 'minimal', 'standard'
});

Korumalı Mod (KHAN VM)

Botlarla savaşmanın en zor yanı, tarayıcıda çalışan her şeyin prensipte görünür ve düzenlenebilir olmasıdır. Kararlı bir saldırgan sayfanın kodunu okuyabilir, nelerin ölçüldüğünü anlayabilir ve sahte yanıtları sessizce geri besleyebilir.

KHAN VM bu işlemin maliyetini artırır. Toplamayı sayfada okunabilir kod olarak açıkta bırakmak yerine Noxtica, hassas bölümü mühürlü, korumalı bir çalışma ortamında çalıştırır. Neyin ölçüleceğine karar veren mantık, saldırganın inceleyip yeniden yazabileceği şekilde görünürde değildir; üretilen sonuç tarayıcıdan ayrılmadan önce mühürlenir — bu nedenle kurcalanması veya tekrar oynatılması çok daha güçtür.

KHAN VM’in yardımcı olduğu şeyler:

• Kurcalamaya dirençli sonuçlar — değerlendirme, gönderilmeden önce korumalı alanın içinde mühürlenir; sayfadaki diğer betikler onu sessizce değiştiremez veya tekrar oynatamaz.
• Tersine mühendisliği zorlaştırma — toplama mantığı, tarayıcının geliştirici araçlarında okunabilir halde durmak yerine çalışma zamanının içinde gizli kalır.
• Tekrar oynatma koruması — her sonuç tek kullanımlıktır ve doğrulanmış, böylece yakalanan bir yanıt temiz bir ziyaretçiyi taklit etmek için yeniden kullanılamaz.

Dürüst sınırlar — ne yapmaz:

• Bu bir kurcalamaya direnç özelliğidir, uçtan uca şifreleme değildir.
• Kendi sayfanız ele geçirilmişse (örneğin siteler arası komut dosyası çalıştırma açığıyla), o sayfadaki bir saldırgan Noxtica’nın gördüğü ham tarayıcı sinyallerinin aynısını görebilir. KHAN VM işlemi ve sonucu korur, etrafındaki sayfayı değil.

KHAN VM sunucu tarafından açılır ve entegrasyonunuzda değişiklik gerektirmez. Başlatamazsa — örneğin bir içerik güvenlik ilkesi engellerse — Noxtica, tespit çalışmaya devam etsin diye daha hafif bir toplama biçimine geri döner, yalnızca kurcalama koruması zayıflar.

Tarayıcı Desteği

SDK modern tarayıcıları destekler:

Daha eski tarayıcılarda sinyal doğruluğu azalabilir, ancak çalışmaya devam eder.

Hata Ayıklama Modu

Sorunları gidermek için hata ayıklama günlüklerini etkinleştirin:

// SDK yüklenmeden önce
globalThis.NOXTICA_DEBUG = true;

// Veya istemci başına
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Veya betik özelliği aracılığıyla
<script src="..." data-debug></script>;

Hata ayıklama modu şunları günlükler:

• Toplama ilerlemesi
• Token yaşam döngüsü
• Önbellek isabetleri ve kaçırmaları
• Karşılaşılan hatalar

Not: Hata ayıklama modu üretimde varsayılan olarak sessizdir. Açıkça etkinleştirilmedikçe konsol çıktısı görünmez.

Depolama Konuları

Tarayıcı Depolaması

SDK sonuçları önbelleğe almak için tarayıcının yerel depolamasını kullanır. Kullanılamadığında (örneğin gizli tarama veya depolama devre dışıyken):

• Tespit yine de çalışır
• Her sayfa yüklemesi yeni bir değerlendirme çalıştırır
• Sekme koordinasyonu azalabilir

Çerez Yok

SDK çerez kullanmaz. İhtiyaç duyduğu her şey tarayıcının yerel depolamasında tutulur.

Performans Etkisi

İlk Ziyaret

Toplama asenkron çalışır ve sayfa oluşturmayı engellemez.

Sonraki Ziyaretler (Önbellek İsabeti)

Sorun Giderme

Parmak İzi Toplanmıyor

1. Tarayıcı konsolunda hata olup olmadığını kontrol edin
2. Site Anahtarının alan adınızla tam eşleştiğini doğrulayın (https:// dahil)
3. Alan adının Backoffice’te etkin olduğundan emin olun
4. Ayrıntılı günlükleri görmek için hata ayıklama modunu etkinleştirin

”WebAssembly blocked by Content Security Policy”

Tarayıcı konsolunda bu uyarıyı görüyorsanız, sayfanızın içerik güvenlik ilkesi kurcalamaya dirençli çalışma ortamını (KHAN VM) engelliyor demektir. Tespit daha hafif bir modda çalışmaya devam eder, ancak tam korumayı geri kazanmak için buna izin vermeniz önerilir.

Noxtica’nın yüklenip çalışmasına izin vermek için aşağıdaki kodu kullanın:

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval' https://collect.noxtica.com; connect-src 'self' https://collect.noxtica.com

Tam referans için bkz. Başlarken → İçerik Güvenlik İlkesi.

Aynı Cihazda Farklı Cihaz Kimlikleri

Bu şu durumlarda olabilir:

• Tarayıcının depolanmış verisi temizlendiğinde
• Tarayıcı profili değiştiğinde
• Ziyaretçi gizli/özel tarama modu kullandığında
• Tarayıcı büyük bir güncelleme geçirdiğinde

Bu beklenen bir davranıştır — tanıma, cihaz zamanla değiştikçe buna uyum sağlar.

Toplama Çok Uzun Sürüyor

1. Yavaş API yanıtları için ağ sekmesini kontrol edin
2. Daha hızlı toplama için mode: 'minimal' kullanmayı değerlendirin
3. SDK’nın async özelliğiyle yüklendiğinden emin olun

Olaylar Tetiklenmiyor

1. SDK çalışmadan önce dinlemeye başladığınızdan emin olun
2. Otomatik başlatma özelliklerinin doğru olduğunu kontrol edin
3. Yürütmeyi engelleyen JavaScript hatası olmadığını doğrulayın

En İyi Uygulamalar

1. Gereksiz toplamaları en aza indirmek için data-auto-collect yerine data-auto-check-once kullanın

2. Sayfa yüklemesini engellemekten kaçınmak için SDK’yı async özelliğiyle asenkron yükleyin

3. window.noxticaResult’u sürekli sorgulamak yerine olayları dinleyin

4. TTL’yi gereksiz yere geçersiz kılmayın — varsayılan 7 günlük aralık çoğu kullanım senaryosu için optimize edilmiştir

5. Hataları düzgün yönetin — toplama hatası sayfanızı bozmamalıdır

Sonraki Adımlar

• Başlarken — İlk kurulum kılavuzu
• Backend Entegrasyonu — Sunucu tarafı cihaz sorguları