Başlarken

Bu kılavuz, Noxtica’yı web uygulamanıza yalnızca birkaç dakika içinde eklemenize yardımcı olacaktır.

Ön Koşullar

• Bir Noxtica hesabı (iletişim üzerinden erişim talep edin)
• Site Anahtarınız (hesap kurulumundan sonra sağlanır)

Hızlı Entegrasyon

Hesabınız kurulduktan ve Site Anahtarınız elinizde olduktan sonra toplayıcımızı HTML’inize ekleyin — kurulum bu kadar.

Otomatik Toplama (Önerilen)

Başlamanın en kolay yolu, bir-kez-çalıştır modunu kullanarak Noxtica’nın kendiliğinden çalışmasına izin vermektir:

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

Bu şunları yapar:

• İlk ziyarette ziyaretçiyi değerlendirir
• Önbellek penceresi içindeki tekrar ziyaretlerde bu sonucu yeniden kullanır (varsayılan: 7 gün)
• Tam değerlendirmeyi yeniden yapmadan dönüş ziyaretlerini sessizce kaydeder
• Ziyaretçinin yalnızca bir kez değerlendirilmesi için açık sekmeler arasında koordinasyon sağlar

Sonuçlara şu şekilde ulaşılır:

// Sonuçları dinleyin
document.addEventListener('noxtica:collected', function (e) {
	console.log('Fingerprint collected:', e.detail);
	console.log('Risk score:', e.detail.score);
	console.log('Risk level:', e.detail.risk_level);
});

// Veya toplamadan sonra doğrudan erişin
console.log(window.noxticaResult);

Manuel Toplama

Daha fazla kontrol için JavaScript API’sini kullanın:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Site Anahtarınızla bir istemci oluşturun
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Tek çağrıda toplayın ve gönderin
	client.collectAndSubmit().then((result) => {
		console.log('Risk score:', result.score);
		console.log('Risk level:', result.risk_level);
		console.log('Flags:', result.flags);
	});
</script>

checkOnce() ile Akıllı Toplama

En hafif ayak izi için checkOnce() kullanın — sunucu üzerinde yapılandırdığınız toplama aralığına saygı gösterir, bu sayede ziyaretçiler gereken sıklıktan daha fazla yeniden değerlendirilmez:

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

// Yalnızca kontrol aralığı penceresi dışındaysa toplar (varsayılan: 7 gün)
// Aksi hâlde bir ziyaret kaydeder ve önbelleğe alınmış sonucu döndürür
const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached result, next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh collection submitted');
}
console.log('Risk level:', result.risk_level);

Performans ve Site Etkisi

Toplayıcı, sayfa yüklemesi ve kullanıcının fark ettiği gecikme üzerinde minimum etki bırakacak şekilde tasarlanmıştır:

Nasıl hafif tutuyoruz:

• async betik özelliği — toplayıcı arka planda yüklenir ve sayfanızın görünür veya etkileşimli hale gelmesini hiçbir zaman geciktirmez.
• Bir-kez-çalıştır modu (data-auto-check-once) — ilk değerlendirmeden sonra, önbellek penceresi içindeki tekrar ziyaretler yalnızca küçük bir ziyaret işareti (~150 bayt) gönderir.
• Sekme koordinasyonu — birden fazla açık sekme tek bir değerlendirmede birleşir.
• İlk yükten sonra önbelleklenir — kurcalamaya dirençli KHAN VM tarayıcı tarafından önbelleğe alınır, sonraki ziyaretlerde anında yüklenir.
• Arka plan işleme — desteklendiği yerlerde işlem ana iş parçacığından uzak tutulur ve sayfanız yanıt vermeye devam eder.

SDK eklendikten sonra yavaşlama fark ederseniz, await client.collectAndSubmit({ telemetry: true }) ile bir profil yakalayın — dönen result.telemetry zamanlama dökümünü içerir.

Sandbox ve Üretim

İki Site Anahtarınız olacak: biri geliştirme ve hazırlık için, biri üretim için. Her biri kendi ilkeleri altında çalışır ve verilerini tamamen ayrı tutar.

Site Anahtarını her ortam için ayrı tutun. Üretim trafiğinde asla pk_sand_* anahtarı kullanmayın — sandbox verisi üretim panolarınızda görünmez ve risk skorlaması çok izin verici olur. Tersine, geliştirmede pk_prod_* anahtarı kullanmak üretim istek sınırı bütçenizi tüketir.

Yaygın bir desen:

<script>
	// Anahtarı sunucu adına göre seçin; geliştirmede sandbox'a geri dönün.
	const KEY = location.hostname === 'www.example.com' ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
	const s = document.createElement('script');
	s.src = 'https://collect.noxtica.com/collector/noxtica.js';
	s.async = true;
	s.dataset.siteKey = KEY;
	s.dataset.autoInit = '';
	s.dataset.autoCheckOnce = '';
	document.head.appendChild(s);
</script>

Etiket Yöneticisi Uyumluluğu

Toplayıcı Google Tag Manager, Adobe Launch, Tealium ve Segment içinde çalışır; ANCAK bazı çekinceleri vardır:

Önerilen (tercih edilen): Betiği doğrudan HTML’inize, </body>’den hemen önce veya <head> içine async ile ekleyin. En erken başlamak toplayıcıya en iyi başlangıç fırsatını tanır; böylece ziyaretçi etkileşime geçtiğinde hazır olur.

Etiket yöneticileri — çalışır, çekinceleri var:

• ✅ Çoğu modern etiket yöneticisi (GTM Özel HTML, Adobe Launch Özel Kod, Segment Özel Kaynak) toplayıcıyı başarıyla yükler.
• ⚠️ Betikleri ziyaretçi kabul edene kadar engelleyen rıza kapıları ilk değerlendirmeyi geciktirir — genellikle rıza başlığı kapatılana kadar hiçbir şey çalışmaz. Bu doğru davranıştır; yalnızca “karar süresini” ölçen metriklerinizi etkileyebileceğini bilin.
• ⚠️ Bazı eski etiket yöneticileri özel data-* özelliklerini düşürür. data-site-key betik etiketine ulaşmazsa otomatik başlatma çalışmaz. Bunun yerine kodda kendiniz kurulumu yapın:

  NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();

• ❌ Birkaç yoğun biçimde korumalı etiket kapsayıcısı (nadir) kurcalamaya dirençli çalışma ortamının başlamasını engeller. SDK daha hafif bir toplama biçimiyle çalışmaya devam eder ve konsola uyarı yazar.

Etiket yöneticisi üzerinden entegre etmek zorundaysanız, Noxtica etiketinin DOM Hazır yerine Tüm Sayfalar — Pencere Yüklendi (veya eşdeğeri) üzerinde tetiklenmesini yapılandırın — bu, herhangi bir şey çalışmadan önce rıza durumunun kesinleşmesini sağlar.

İçerik Güvenlik İlkesi

Siteniz içerik güvenlik ilkesi kullanıyorsa, Noxtica’nın yüklenmesine, kurcalamaya dirençli çalışma ortamını (KHAN VM) çalıştırmasına ve API’mizle iletişim kurmasına izin vermeniz gerekir. Aşağıdaki örnek üçünü de kapsar:

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

İlke 'wasm-unsafe-eval' belirtecini dışarıda bırakırsa, tarayıcı kurcalamaya dirençli çalışma ortamını engeller ve konsolda ilgili bir uyarı görürsünüz. Noxtica çalışmaya devam eder — daha hafif bir toplama biçimine geri döner — ancak kurcalama koruması zayıflar. Yukarıdaki belirteci eklemek tam deneyimi geri kazandırır.

Site Anahtarları

Site Anahtarınız (pk_...), alan adınızdan gelen istekleri doğrulayan herkese açık bir tanımlayıcıdır. Backoffice’te eklediğiniz her alan adı kendine özgü bir Site Anahtarı alır.

Önemli notlar:

• Site Anahtarları herkese açıktır ve HTML’inize güvenle gömülebilir
• Her Site Anahtarı belirli bir kaynağa bağlıdır (örn. https://example.com)
• API, kaynağı Site Anahtarının kayıtlı alan adıyla eşleşmeyen istekleri reddeder

Yapılandırma Seçenekleri

const client = NoxticaCollector.createClient({
	// Site Anahtarınız (zorunlu)
	siteKey: 'pk_prod_your_site_key_here',

	// API uç noktası (varsayılan olarak üretim)
	apiUrl: 'https://collect.noxtica.com',

	// Toplama modu: 'max' (varsayılan), 'standard' veya 'minimal'
	// max modunu kullanmak için belirtmeyin (önerilen)
	// mode: 'standard', // max-only sinyallerden vazgeçmek için yorumu kaldırın
});

Toplama Modları

Yanıt Formatı

Toplayıp gönderdikten sonra şunları alırsınız:

{
	"success": true,
	"fingerprintId": "abc123...",
	"score": 15,
	"risk_level": "minimal",
	"confidence": 0.5,
	"flags": [],
	"details": {
		"summary": "Detected 0 risk indicator(s)."
	}
}

Risk Seviyeleri

Kimlik Doğrulama

SDK her ziyareti, Site Anahtarınıza bağlı kısa ömürlü ve otomatik döndürülen kimlik bilgileriyle doğrular. Bunları talep eder, yeniler ve her gönderime ekler.

Bunları yönetmenize gerek yok — SDK her şeyi otomatik olarak halleder.

Katılım Süreci

1. Erişim talep edin: Demo talep etmek veya başlamak için bize ulaşın
2. Hesap kurulumu: Platformda kiracı hesabınızı oluştururuz
3. Alan adları ekleyin: Backoffice’a giriş yapın, Alan Adları bölümüne gidin ve kaynaklarınızı ekleyin
4. Site Anahtarını kopyalayın: Her alan adı kendine özgü bir Site Anahtarı alır
5. Entegre edin: Site Anahtarınızı içeren betiği sayfalarınıza ekleyin
6. İzleyin: Parmak izlerini ve analitikleri Backoffice panosunda görüntüleyin

Birden Fazla Alan Adı Yönetimi

Noxtica hesap başına birden fazla alan adını destekler:

• Üretim: https://www.yoursite.com
• Hazırlık: https://staging.yoursite.com
• Mobil: https://m.yoursite.com

Her alan adının kendi Site Anahtarı vardır. Şunları yapabilirsiniz:

• Alan adlarını anahtarları yeniden oluşturmadan etkinleştirin/devre dışı bırakın
• Güvenliği ihlal edilmiş Site Anahtarlarını döndürün
• Analitikleri alan adına göre filtrelenmiş görüntüleyin

SDK Sürümü

Mevcut SDK sürümü: 3.3.0 (Şema: 2026-05-24)

3.3.0’daki yenilikler

• Hafif davranışsal sinyaller (her zaman açık) — bir oturumun ne kadar sürdüğü ve ziyaretçinin ilk ne kadar hızla etkileşime geçtiği gibi basit zamanlama ipuçları. Biyometrik veri değildir ve son kullanıcı rızası gerekmez.
• Davranışsal biyometri (isteğe bağlı) — Backoffice → Ayarlar → Davranışsal Biyometri’den açtığınızda, Noxtica fare hareketi ritmine, tıklama zamanlamasına ve kaydırma davranışına da bakar. Bu, katı gizlilik mevzuatı kapsamında biyometrik veri sayılır; bu nedenle açık son kullanıcı rızası gereklidir. Aşağıdaki Davranışsal Biyometri bölümüne bakın.
• Apple Pay tutarlılık kontrolü — iPhone olduğunu iddia eden bir cihazın gerçekten öyle davranıp davranmadığını doğrular; yaygın bir sahtekârlık numarasını yakalar.
• Ağ parmak izi eşleştirme — yaygın otomasyon araçlarının tanınan bağlantı desenlerini tespit eder; betikler ve botlardan gelen trafik, tarayıcı inandırıcı görünse bile öne çıkar.
• IP itibarı — kötü itibarı olan ağlardan gelen ziyaretçileri işaretler; kendi tercih ettiğiniz tehdit istihbarat akışını ekleme seçeneğiyle.

Davranışsal Biyometri (İsteğe Bağlı, Opt-In)

Noxtica, birinin fareyi nasıl hareket ettirdiğinin, tıklama ve kaydırma ritmini de inceleyebilir. Varsayılan olarak kapalı olan isteğe bağlı bir özelliktir.

Neden isteğe bağlı? Bu tür davranışsal veriler katı gizlilik mevzuatı kapsamında hassas kişisel veri sayılır; bu nedenle yakalamak son kullanıcıdan açık rıza gerektirir. Ne zaman ve nasıl kullanıldığını siz kontrol edebilesiniz diye isteğe bağlı yapıyoruz.

Etkinleştirmek için:

1. Backoffice → Ayarlar → Davranışsal Biyometri’ye giriş yapın
2. Gizlilik veya hukuk ekibinizle uyum bildirimini inceleyin
3. Bu yakalamayı ifşa etmek için gizlilik politikanızı ve rıza başlığınızı güncelleyin
4. Özelliği açın

Etkinleştirildikten sonra Noxtica bu davranışsal sinyalleri otomatik olarak gelecekteki değerlendirmelere dahil eder ve pano, alan adı başına oluşan davranışsal skoru gösterir.

Sonraki Adımlar

• Parmak izi almayı canlı görmek için canlı demoyu deneyin
• Sunucu tarafı sorgular için Backend Entegrasyonu kılavuzunu okuyun
• Toplanan verileri keşfetmek için panoya erişin