Асяроддзе выканання ў браўзеры

Гэтае кіраўніцтва тлумачыць, як Noxtica SDK працуе ўнутры браўзераў вашых наведвальнікаў — што адбываецца падчас ацэнкі, як кэшаванне паскарае работу і як вырашаць частыя праблемы.

Як гэта працуе

Калі вы дадаяце Noxtica SDK на старонку, ён ціха робіць чатыры рэчы:

1. Аўтэнтыфікуецца: ўваходзіць з вашым Site Key, выкарыстоўваючы ўліковыя дадзеныя, якімі кіруе самастойна
2. Збірае: счытвае звычайныя сігналы, якія браўзер і так адкрывае
3. Адпраўляе: перасылае іх у Noxtica для ацэнкі
4. Кэшуе: захоўвае вынік лакальна, каб не паўтараць работу пры кожным візіце

Усё гэта адбываецца ў фонавым рэжыме і ніколі не блакуе вашу старонку.

Паток збору

Аўтаматычна (рэкамендуецца)

Пры выкарыстанні data-auto-check-once SDK прымяняе разумны збор:

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

Выкарыстоўваеце палітыку бяспекі кантэнту? Вам трэба будзе дазволіць Noxtica загружаць і запускаць яго ўстойлівы да ўмяшання рант-тайм — KHAN VM. Калі гэта немагчыма, Noxtica працягвае працаваць у больш лёгкім рэжыме збору з меншай абаронай ад умяшання. Глядзіце Пачатак працы → Палітыка бяспекі кантэнту для дакладнага фрагмента.

Першае наведванне: выконваецца поўная ацэнка і захоўваецца ў кэшы.

Наступныя наведванні (у межах акна кэшу): вяртаецца кэшаваны вынік і запісваецца лёгкі візіт. Цяжкая работа не паўтараецца.

Пасля заканчэння кэшу: выконваецца новая ацэнка.

Ручны кантроль

Для праграмнага кантролю выкарыстоўвайце метад checkOnce():

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');
}

Паводзіны кэшу

SDK кэшуе кожны вынік у браўзеры, каб не праводзіць паўторную ацэнку аднаго і таго ж наведвальніка пры кожным прагляде старонкі.

Ключ кэшу

nox_fp_{your_site_key}

Што кэшуецца

• Device ID
• Метка часу апошняй адпраўкі
• Метка часу апошняга з’яўлення
• Папярэдні бал рызыкі і ўзровень

TTL (час жыцця)

TTL кэшу па змаўчанні — 7 дзён. Гэта можна наладзіць:

// Override at collection time
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 days instead of 7
});

// Or in seconds
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 day
});

Прымусовае абнаўленне

Каб абыйсці кэш і сабраць свежы адбітак:

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

Каардынацыя паміж укладкамі

Калі наведвальнік адначасова адкрывае некалькі ўкладак вашага сайта, SDK гарантуе, што ацэнка праводзіцца толькі аднойчы:

• толькі адна ўкладка выконвае сапраўдную работу
• астатнія чакаюць і дзеляць вынік

Гэта адбываецца аўтаматычна — ніякай наладкі не патрабуецца.

Падзеі

SDK генеруе падзеі, на якія вы можаце падпісацца:

noxtica:collected

Выклікаецца пасля паспяховага збору або пры вяртанні кэшаванага выніку:

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

Выклікаецца канкрэтна тады, калі вяртаецца кэшаваны вынік:

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

noxtica:error

Выклікаецца пры збоі збору:

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

Глабальныя зменныя

Пасля збору вынікі даступныя глабальна:

// After collection completes
console.log(window.noxticaResult);

// Client instance (when using auto-init)
console.log(window.noxticaClient);

// Last error (if any)
console.log(window.noxticaLastError);

Апрацоўка памылак

Частыя памылкі

Ручная апрацоўка памылак

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Site key configuration issue
	} else if (error.message.includes('rate')) {
		// Back off and retry later
	}
}

Рэжымы збору

SDK падтрымлівае тры рэжымы збору:

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

Абаронены рэжым (KHAN VM)

Самая складаная частка ў барацьбе з ботамі — тое, што ўсё, што запускаецца ў браўзеры, у прынцыпе даступна для прагляду і рэдагавання. Дасведчаны зламыснік можа прачытаць код старонкі, зразумець, што вымяраецца, і ціха падаць фальшывыя значэнні ў адказ.

KHAN VM павышае кошт гэтага. Замест таго каб пакідаць збор адкрытым як чытаны код на старонцы, Noxtica запускае адчувальную частку ўнутры ізаляванай асяроддзі. Логіка, якая вырашае, што вымяраць, не ляжыць на бачнасці для зламысніка, а вынік запячатваецца перш, чым пакінуць браўзер — так яго значна цяжэй падрабіць або паўторна выкарыстаць.

Чым дапамагае KHAN VM:

• Устойлівыя да ўмяшання вынікі — ацэнка запячатваецца ўнутры асяроддзі перад адпраўкай, таму іншыя скрыпты на старонцы не могуць ціха змяніць або паўторна адправіць яе.
• Цяжэй зваротна распрацаваць — логіка збору застаецца схаванай унутры рант-тайму, а не даступнай у інструментах распрацоўніка браўзера.
• Абарона ад паўторнага прайгравання — кожны вынік аднаразовы і правераны, таму захоплены адказ нельга проста паўторна выкарыстаць для імітацыі чыстага наведвальніка.

Сумленныя межы — чаго ён не робіць:

• Гэта функцыя ўстойлівасці да ўмяшання, а не поўнае шыфраванне.
• Калі ваша ўласная старонка скампраметавана (напрыклад, праз уразлівасць міжсайтавага скрыптынгу), зламыснік на гэтай старонцы бачыць тыя ж сырыя сігналы браўзера, якія бачыць Noxtica. KHAN VM абараняе апрацоўку і вынік, а не старонку вакол яго.

KHAN VM уключаецца з боку сервера і не патрабуе ніякіх змен у вашай інтэграцыі. Калі ён не можа запусціцца — напрыклад, таму што палітыка бяспекі кантэнту блакуе яго — Noxtica пераходзіць на больш лёгкі рэжым збору, каб выяўленне працягвалася, але з меншай абаронай ад умяшання.

Падтрымка браўзераў

SDK падтрымлівае сучасныя браўзеры:

Больш старыя браўзеры могуць мець зніжаную дакладнасць сігналаў, але будуць працаваць.

Рэжым адладкі

Уключыце вядзенне журнала адладкі для ліквідацыі непаладак:

// Before SDK loads
globalThis.NOXTICA_DEBUG = true;

// Or per-client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Or via script attribute
<script src="..." data-debug></script>;

Рэжым адладкі запісвае ў лог:

• ход збору
• жыццёвы цыкл токена
• трапленні і прамахі кэшу
• любыя памылкі

Заўвага: рэжым адладкі маўчыць па змаўчанні ў вытворчасці. Кансольны вывад не з’яўляецца, калі ён яўна не ўключаны.

Меркаванні наконт сховішча

Сховішча браўзера

SDK выкарыстоўвае лакальнае сховішча браўзера для кэшавання вынікаў. Калі яно недаступна (напрыклад, у прыватным рэжыме або пры адключаным сховішчы):

• выяўленне ўсё роўна працуе
• кожная загрузка старонкі выконвае новую ацэнку
• каардынацыя паміж укладкамі можа быць зніжана

Без cookies

SDK не выкарыстоўвае cookies. Усё неабходнае захоўваецца ў лакальным сховішчы браўзера.

Уплыў на прадукцыйнасць

Першае наведванне

Збор выконваецца асінхронна і не блакуе адмалёўванне старонкі.

Наступныя наведванні (трапленне ў кэш)

Ліквідацыя непаладак

Адбітак не сабраны

1. Праверце кансоль браўзера на наяўнасць памылак
2. Пераканайцеся, што Site Key дакладна адпавядае вашаму дамену (уключаючы https://)
3. Пераканайцеся, што дамен уключаны ў Backoffice
4. Уключыце рэжым адладкі, каб убачыць падрабязныя логі

«WebAssembly blocked by Content Security Policy»

Калі вы бачыце гэтае папярэджанне ў кансолі браўзера, вашая палітыка бяспекі кантэнту блакуе ўстойлівы да ўмяшання рант-тайм (KHAN VM). Выяўленне працягвае працаваць у больш лёгкім рэжыме, але для найлепшай абароны варта дазволіць яго.

Выкарыстоўвайце фрагмент ніжэй, каб дазволіць Noxtica загружаць і запускацца:

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

Глядзіце Пачатак працы → Палітыка бяспекі кантэнту для поўнай даведкі.

Розныя Device ID на адной прыладзе

Гэта можа здарыцца, калі:

• захоўванне дадзеных браўзера было ачышчана
• профіль браўзера змяніўся
• наведвальнік выкарыстоўвае прыватны / інкогніта рэжым
• браўзер прайшоў праз буйнае абнаўленне

Гэта чаканае паводзіны — распазнаванне адаптуецца, калі прылада змяняецца з часам.

Збор займае занадта шмат часу

1. Праверце ўкладку сеткі на павольныя адказы API
2. Разгледзьце выкарыстанне mode: 'minimal' для больш хуткага збору
3. Пераканайцеся, што SDK загружаецца з атрыбутам async

Падзеі не генеруюцца

1. Пераканайцеся, што вы слухаеце да запуску SDK
2. Праверце правільнасць атрыбутаў auto-init
3. Пераканайцеся, што няма памылак JavaScript, якія блакуюць выкананне

Лепшыя практыкі

1. Выкарыстоўвайце data-auto-check-once замест data-auto-collect, каб мінімізаваць лішні збор

2. Загружайце SDK асінхронна з атрыбутам async, каб не блакаваць загрузку старонкі

3. Слухайце падзеі замест апытвання window.noxticaResult

4. Не мяняйце TTL без неабходнасці — інтэрвал у 7 дзён па змаўчанні аптымізаваны для большасці выпадкаў

5. Апрацоўвайце памылкі карэктна — збой збору не павінен ламаць вашу старонку

Наступныя крокі

• Пачатак працы — кіраўніцтва па пачатковай наладзе
• Інтэграцыя з бэкэндам — серверныя запыты прылад