شروع سریع

این راهنما به شما کمک می‌کند Noxtica را در چند دقیقه به اپلیکیشن وبتان اضافه کنید.

پیش‌نیازها

یک حساب Noxtica (از طریق تماس درخواست دسترسی دهید)
Site Key شما (پس از راه‌اندازی حساب ارائه می‌شود)

یکپارچه‌سازی سریع

بعد از اینکه حسابتان راه‌اندازی شد و Site Key دارید، کالکتور ما را به HTML خود اضافه کنید — این کل نصب است.

جمع‌آوری خودکار (توصیه‌شده)

ساده‌ترین راه برای شروع این است که بگذارید Noxtica خودش اجرا شود، با حالت یک‌بار اجرا:

<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>

این:

بازدیدکننده را در اولین بازدیدش ارزیابی می‌کند
آن نتیجه را برای بازدیدهای تکراری در پنجره ذخیره موقت (پیش‌فرض: ۷ روز) استفاده مجدد می‌کند
بازگشت‌ها را بی‌سروصدا ثبت می‌کند بدون تکرار ارزیابی کامل
در تب‌های باز هماهنگ می‌کند تا بازدیدکننده فقط یک بار ارزیابی شود

نتایج از طریق این روش‌ها در دسترس هستند:

// Listen for results
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);
});

// Or access directly after collection
console.log(window.noxticaResult);

جمع‌آوری دستی

برای کنترل بیشتر، از JavaScript API استفاده کنید:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Create a client with your Site Key
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Collect and submit in one call
	client.collectAndSubmit().then((result) => {
		console.log('Risk score:', result.score);
		console.log('Risk level:', result.risk_level);
		console.log('Flags:', result.flags);
	});
</script>

جمع‌آوری هوشمند با `checkOnce()`

برای کمترین ردپا، از checkOnce() استفاده کنید — به بازه جمع‌آوری‌ای که روی سرور پیکربندی می‌کنید احترام می‌گذارد، پس بازدیدکنندگان بیشتر از آنچه لازم است ارزیابی مجدد نمی‌شوند:

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

// Only collects if outside the check interval window (default: 7 days)
// Otherwise records a visit and returns cached result
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);

عملکرد و تأثیر بر سایت

کالکتور طراحی شده تا تأثیر حداقلی بر بارگذاری صفحه و تأخیر قابل مشاهده کاربر داشته باشد:

معیار	مقدار
اندازه اولیه اسکریپت	حدوداً ۱۶۷ کیلوبایت minified، حدوداً ۵۵ کیلوبایت brotli
زمان تا جمع‌آوری (میانه، اولین بار)	کمتر از ۵۰ms روی دسکتاپ مدرن / کمتر از ۱۲۰ms روی تلفن میان‌رده
زمان تا پاسخ امتیازدهی‌شده با ریسک	میانه کمتر از ۱۵۰ms (لبه کالکتور → لبه API)
بازدید با ذخیره موقت (پس از اولین بار)	کمتر از ۱۰ms (بدون کار اثرانگشت؛ فقط یک فانوس)
مسدودسازی رشته اصلی	هیچ — جمع‌آوری در تکه‌های ناهمزمان اجرا می‌شود

چطور آن را سبک نگه می‌داریم:

ویژگی اسکریپت async — کالکتور در پس‌زمینه بارگذاری می‌شود و هرگز صفحه را از قابل مشاهده یا تعامل‌پذیر شدن تأخیر نمی‌دهد.
حالت یک‌بار اجرا (data-auto-check-once) — پس از اولین ارزیابی، بازدیدهای تکراری در پنجره ذخیره موقت فقط یک پینگ بازدید کوچک (~۱۵۰ بایت) ارسال می‌کنند.
هماهنگی چند تب — چند تب باز به یک ارزیابی واحد تقلیل می‌یابند.
ذخیره‌شده پس از اولین بارگذاری — KHAN VM مقاوم در برابر دستکاری توسط مرورگر ذخیره می‌شود، پس در بازدیدهای بعدی آنی بارگذاری می‌شود.
پردازش پس‌زمینه جایی که پشتیبانی می‌شود، تا کار خارج از رشته اصلی بماند و صفحه شما واکنش‌گرا بماند.

اگر پس از اضافه کردن SDK کندی مشاهده کردید، یک پروفایل با await client.collectAndSubmit({ telemetry: true }) ضبط کنید — result.telemetry برگشتی یک تجزیه زمان‌بندی دارد.

Sandbox در مقابل Production

دو Site Key خواهید داشت: یکی برای توسعه و staging، یکی برای production. هر کدام زیر سیاست‌های خودش اجرا می‌شود و داده‌هایش را کاملاً جدا نگه می‌دارد.

جنبه	Sandbox (`pk_sand_*`)	Production (`pk_prod_*`)
پیشوند Site Key	`pk_sand_`	`pk_prod_`
لیست سفید مبدأ	Localhost + مبدأهای staging شما	سخت — فقط مبدأهای ثبت‌شده شما
محدودیت نرخ	سخاوتمندانه (~۱۰۰۰/دقیقه/IP)	محدودیت‌های هر پلن اجرا می‌شود
سیاست امتیازدهی ریسک	سخاوتمندانه — حداقل مسدودسازی ربات	سیاست‌های production اعمال می‌شود
نگهداری داده	۷ روز	پیکربندی هر tenant (پیش‌فرض ۹۰ روز)
نگهداری لاگ ممیزی	۷ روز	پیکربندی هر tenant (پیش‌فرض ۹۰ روز)
MFA قدم اضافی	اختیاری	برای عملیات مخرب اجباری

همیشه Site Key را به ازای هر محیط عوض کنید. هرگز از یک کلید pk_sand_* در ترافیک production استفاده نکنید — داده‌های sandbox در داشبورد production شما ظاهر نمی‌شوند و امتیازدهی ریسک خیلی سخاوتمندانه خواهد بود. برعکس، استفاده از یک کلید pk_prod_* در توسعه بودجه محدودیت نرخ production را هدر می‌دهد.

یک الگو رایج:

<script>
	// Pick the key by hostname; fall back to sandbox in dev.
	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>

سازگاری با مدیر تگ

کالکتور درون Google Tag Manager، Adobe Launch، Tealium، و Segment کار می‌کند، اما با محدودیت‌هایی:

توصیه‌شده (ترجیحی): اسکریپت را مستقیماً به HTML خود اضافه کنید، بلافاصله قبل از </body> یا در <head> با async. شروع در اسرع وقت به کالکتور بهترین پیش‌آهنگی می‌دهد، پس تا بازدیدکننده تعامل می‌کند آماده است.

مدیرهای تگ — کار می‌کند، با محدودیت‌هایی:

✅ بیشتر مدیرهای تگ مدرن (GTM Custom HTML، Adobe Launch Custom Code، Segment Custom Source) کالکتور را با موفقیت بارگذاری می‌کنند.
⚠️ دروازه‌های رضایت که اسکریپت‌ها را تا پذیرش بازدیدکننده مسدود می‌کنند اولین ارزیابی را تأخیر می‌دهند — معمولاً تا پنل رضایت رد نشود چیزی اجرا نمی‌شود. این رفتار درست است؛ فقط بدانید می‌تواند معیارهای «زمان تا تصمیم» شما را کج کند.
⚠️ برخی مدیرهای تگ قدیمی‌تر ویژگی‌های data-* سفارشی را حذف می‌کنند. اگر data-site-key به تگ اسکریپت نرسید، auto-init شروع نمی‌کند. به جایش در کد تنظیم کنید:
```
NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();
```
❌ چند مدیر تگ با سندباکس شدید (نادر) از شروع محیط اجرایی مقاوم در برابر دستکاری جلوگیری می‌کنند. SDK با یک فرم سبک‌تر از جمع‌آوری به کار ادامه می‌دهد و یک هشدار کنسول لاگ می‌کند.

اگر باید از طریق مدیر تگ یکپارچه کنید، آن را پیکربندی کنید تا تگ Noxtica روی All Pages — Window Loaded (یا معادل) فعال شود نه DOM Ready — این مطمئن می‌شود وضعیت رضایت قبل از اجرای هر چیزی نهایی است.

سیاست امنیت محتوا

اگر سایتتان از سیاست امنیت محتوا استفاده می‌کند، باید به Noxtica اجازه بارگذاری، اجرای محیط اجرایی مقاوم در برابر دستکاری (KHAN VM)، و صحبت با API ما بدهید. مثال زیر هر سه را پوشش می‌دهد:

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

اگر سیاست توکن 'wasm-unsafe-eval' را نداشته باشد، مرورگر محیط اجرایی مقاوم در برابر دستکاری را مسدود می‌کند و یک هشدار مرتبط در کنسول می‌بینید. Noxtica به کار ادامه می‌دهد — به یک فرم سبک‌تر از جمع‌آوری بازمی‌گردد — اما با حفاظت ضعیف‌تر در برابر دستکاری. اضافه کردن توکن بالا تجربه کامل را بازمی‌گرداند.

Site Key‌ها

Site Key شما (pk_...) یک شناسه عمومی است که درخواست‌ها را از دامنه شما احراز هویت می‌کند. هر دامنه‌ای که در بک‌آفیس اضافه می‌کنید یک Site Key منحصربه‌فرد دریافت می‌کند.

نکات مهم:

Site Key‌ها عمومی هستند و می‌توانند به‌طور ایمن در HTML جاسازی شوند
هر Site Key به یک مبدأ مشخص متصل است (مثلاً https://example.com)
API درخواست‌هایی که مبدأشان با دامنه ثبت‌شده Site Key مطابقت ندارد رد می‌کند

گزینه‌های پیکربندی

const client = NoxticaCollector.createClient({
	// Your Site Key (required)
	siteKey: 'pk_prod_your_site_key_here',

	// API endpoint (defaults to production)
	apiUrl: 'https://collect.noxtica.com',

	// Collection mode: 'max' (default), 'standard', or 'minimal'
	// Omit to use max mode (recommended)
	// mode: 'standard', // Uncomment to opt out of max-only signals
});

حالت‌های جمع‌آوری

حالت	سیگنال‌ها	بهترین برای
`minimal`	یک مجموعه اصلی کوچک از سیگنال‌ها	سریع‌ترین جمع‌آوری، کمترین ردپا
`standard`	یک مجموعه گسترده از سیگنال‌ها	سایت‌هایی که مجموعه سبک‌تری از سیگنال را ترجیح می‌دهند
`max`	مجموعه کامل سیگنال‌ها	حداکثر دقت (پیش‌فرض)

فرمت پاسخ

پس از جمع‌آوری و ارسال، دریافت می‌کنید:

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

سطوح ریسک

امتیاز	سطح	معنی
۰-۱۹	`minimal`	ریسک خیلی پایین، احتمالاً معتبر
۲۰-۳۹	`low`	ریسک پایین، ناهنجاری‌های جزئی
۴۰-۵۹	`medium`	ریسک متوسط، برخی پرچم‌ها
۶۰-۷۹	`high`	ریسک بالا، احتمالاً اتوماسیون
۸۰-۱۰۰	`critical`	ریسک خیلی بالا، ربات تأیید‌شده

احراز هویت

SDK هر بازدید را با اعتبارنامه‌های کوتاه‌مدت و به‌طور خودکار چرخشی متصل به Site Key شما احراز هویت می‌کند. آن‌ها را درخواست می‌کند، تازه می‌کند، و به هر ارسال برای شما ضمیمه می‌کند.

نیازی نیست هیچ‌کدام از این‌ها را مدیریت کنید — SDK آن را به‌طور خودکار مدیریت می‌کند.

فرایند ورود

۱. درخواست دسترسی: با ما تماس بگیرید تا درخواست دمو کنید یا شروع کنید ۲. راه‌اندازی حساب: ما حساب tenant شما را در پلتفرم ایجاد می‌کنیم ۳. اضافه کردن دامنه‌ها: وارد بک‌آفیس شوید، به Domains بروید، و مبدأهایتان را اضافه کنید ۴. کپی Site Key: هر دامنه یک Site Key منحصربه‌فرد دریافت می‌کند ۵. یکپارچه‌سازی: اسکریپت را با Site Key خود به صفحاتتان اضافه کنید ۶. نظارت: اثرانگشت‌ها و آنالیتیکس را در داشبورد بک‌آفیس مشاهده کنید

مدیریت چند دامنه

Noxtica از چند دامنه در هر حساب پشتیبانی می‌کند:

Production: https://www.yoursite.com
Staging: https://staging.yoursite.com
موبایل: https://m.yoursite.com

هر دامنه Site Key خودش را دارد. می‌توانید:

دامنه‌ها را بدون بازسازی کلیدها فعال/غیرفعال کنید
Site Key‌ها را در صورت به خطر افتادن بچرخانید
آنالیتیکس فیلترشده بر اساس دامنه را مشاهده کنید

نسخه SDK

نسخه فعلی SDK: 3.3.0 (Schema: 2026-05-24)

جدید در ۳.۳.۰

سیگنال‌های رفتاری سبک (همیشه روشن) — نشانه‌های زمان‌بندی ساده مثل مدت نشست و سرعت اولین تعامل بازدیدکننده. بدون داده بیومتریک، و نیازی به رضایت کاربر نهایی نیست.
بیومتریک رفتاری (opt-in) — وقتی آن را در Backoffice ← Settings ← Behavioral Biometrics روشن کنید، Noxtica همچنین ریتم حرکت موس، زمان‌بندی کلیک، و اسکرول را بررسی می‌کند. این طبق مقررات سخت‌گیرانه حریم‌خصوصی به‌عنوان داده بیومتریک حساب می‌شود، پس رضایت صریح کاربر نهایی لازم است. بیومتریک رفتاری زیر را ببینید.
بررسی سازگاری Apple Pay — تأیید می‌کند دستگاهی که ادعا می‌کند iPhone است واقعاً مثل iPhone رفتار می‌کند، یک ترفند رایج جعل را می‌گیرد.
تطبیق اثرانگشت شبکه — الگوهای اتصال مشخصه ابزارهای اتوماسیون رایج را تشخیص می‌دهد، تا ترافیک اسکریپت‌ها و ربات‌ها حتی وقتی مرورگر متقاعدکننده به نظر می‌رسد برجسته شود.
شهرت IP — بازدیدکنندگانی که از شبکه‌هایی با شهرت بد می‌آیند پرچم‌گذاری می‌کند، با گزینه وصل کردن فید اطلاعات تهدید ترجیحی خودتان.

بیومتریک رفتاری (اختیاری، Opt-In)

Noxtica همچنین می‌تواند ریتم نحوه حرکت موس، کلیک، و اسکرول فرد را بررسی کند. این یک ویژگی opt-in است که به‌طور پیش‌فرض خاموش است.

چرا opt-in؟ این نوع داده رفتاری طبق مقررات سخت‌گیرانه حریم‌خصوصی به‌عنوان داده شخصی حساس حساب می‌شود، پس ضبط آن نیاز به رضایت صریح از کاربر نهایی شما دارد. ما آن را opt-in می‌کنیم تا شما کنترل داشته باشید از چه زمانی و چگونه استفاده می‌شود.

برای فعال‌سازی:

۱. وارد Backoffice ← Settings ← Behavioral Biometrics شوید ۲. اطلاعیه انطباق را با تیم حریم‌خصوصی یا حقوقی خود بررسی کنید ۳. سیاست حریم‌خصوصی و بنر رضایت خود را برای افشای این ضبط به‌روز کنید ۴. ویژگی را روشن کنید

بعد از فعال‌سازی، Noxtica به‌طور خودکار این سیگنال‌های رفتاری را در ارزیابی‌های آینده در نظر می‌گیرد، و داشبوردتان امتیاز رفتاری به‌ازای هر دامنه را نشان می‌دهد.

گام‌های بعدی

دمو زنده را امتحان کنید تا اثرانگشت را در عمل ببینید
راهنمای یکپارچه‌سازی بک‌اند را برای جست‌وجوهای سمت سرور بخوانید
به داشبورد دسترسی داشته باشید تا داده‌های جمع‌آوری‌شده را کاوش کنید

شروع سریع

پیش‌نیازها

یکپارچه‌سازی سریع

جمع‌آوری خودکار (توصیه‌شده)

جمع‌آوری دستی

جمع‌آوری هوشمند با checkOnce()

عملکرد و تأثیر بر سایت

Sandbox در مقابل Production

سازگاری با مدیر تگ

سیاست امنیت محتوا

Site Key‌ها

گزینه‌های پیکربندی

حالت‌های جمع‌آوری

فرمت پاسخ

سطوح ریسک

احراز هویت

فرایند ورود

مدیریت چند دامنه

نسخه SDK

جدید در ۳.۳.۰

بیومتریک رفتاری (اختیاری، Opt-In)

گام‌های بعدی

جمع‌آوری هوشمند با `checkOnce()`