Рантайм у браузері

Цей посібник пояснює, як SDK Noxtica працює у браузерах ваших відвідувачів — що відбувається під час оцінювання, як кешування прискорює роботу і як усувати типові проблеми.

Як це працює

Коли ви додаєте SDK Noxtica на свою сторінку, він непомітно виконує чотири дії:

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>

Використовуєте content-security-policy? Вам потрібно дозволити Noxtica завантажувати і запускати свій стійкий до підробки рантайм — KHAN VM. Якщо це неможливо, Noxtica продовжить працювати з легшою формою збору і слабшим захистом від підробки. Дивіться Початок роботи → Content Security Policy — там є точний фрагмент.

Перше відвідування: виконується повне оцінювання, результат кешується.

Наступні відвідування (у межах кеш-вікна): повертається кешований результат і реєструється легке відвідування. Важкі операції не виконуються.

Після завершення кеш-вікна: виконується нове оцінювання.

Ручне керування

Для програмного контролю використовуйте метод 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 днів. Це можна налаштувати:

// Перевизначити під час збору
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 днів замість 7
});

// Або в секундах
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 день
});

Примусове оновлення

Щоб обійти кеш і зібрати свіжий відбиток:

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

Глобальні змінні

Після збору результати доступні глобально:

// Після завершення збору
console.log(window.noxticaResult);

// Екземпляр клієнта (при автоініціалізації)
console.log(window.noxticaClient);

// Остання помилка (за наявності)
console.log(window.noxticaLastError);

Обробка помилок

Типові помилки

Ручна обробка помилок

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Проблема конфігурації site key
	} else if (error.message.includes('rate')) {
		// Зробіть паузу і спробуйте пізніше
	}
}

Режими збору

SDK підтримує три режими збору:

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

Захищений режим (KHAN VM)

Найскладніша частина боротьби з ботами — те, що будь-що у браузері принципово є видимим і редагованим. Рішучий зловмисник може прочитати код сторінки, зрозуміти, що саме вимірюється, і непомітно підсунути назад підроблені значення.

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

Чим KHAN VM допомагає:

• Результати, стійкі до підробки — оцінювання запечатується всередині пісочниці перед надсиланням, тому інші скрипти на сторінці не можуть непомітно змінити або відтворити його.
• Складніший реверс-інжиніринг — логіка збору залишається прихованою всередині рантайму, а не доступною для читання в DevTools браузера.
• Захист від відтворення — кожен результат є одноразовим і верифікованим, тому захоплена відповідь не може бути просто повторно використана для імітації чистого відвідувача.

Чесні межі — чого це не робить:

• Це функція стійкості до підробки, а не наскрізне шифрування.
• Якщо ваша сторінка скомпрометована (наприклад, через вразливість типу cross-site scripting), зловмисник на цій сторінці бачить ті самі сирі браузерні сигнали, що й Noxtica. KHAN VM захищає обробку і результат, а не сторінку навколо нього.

KHAN VM вмикається з боку сервера і не вимагає жодних змін у вашій інтеграції. Якщо він не може запуститися — наприклад, через те, що content-security-policy його блокує — Noxtica повертається до легшої форми збору, щоб виявлення продовжувало працювати, просто з послабшим захистом від підробки.

Підтримка браузерів

SDK підтримує сучасні браузери:

Старіші браузери можуть мати нижчу точність сигналів, але все одно будуть працювати.

Режим налагодження

Увімкніть логування для усунення проблем:

// До завантаження SDK
globalThis.NOXTICA_DEBUG = true;

// Або на рівні клієнта
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Або через атрибут скрипта
<script src="..." data-debug></script>;

Режим налагодження логує:

• Прогрес збору
• Життєвий цикл токена
• Влучання й промахи кешу
• Будь-які виявлені помилки

Примітка: режим налагодження мовчить за замовчуванням у продакшені. Вивід у консоль не з’являтиметься, якщо його не ввімкнено явно.

Зберігання

Сховище браузера

SDK використовує локальне сховище браузера для кешування результатів. Якщо воно недоступне (наприклад, у приватному режимі або при вимкненому сховищі):

• Виявлення продовжує працювати
• При кожному завантаженні сторінки виконується нове оцінювання
• Координація між вкладками може бути послаблена

Без файлів cookie

SDK не використовує файли cookie. Усе необхідне зберігається в локальному сховищі браузера.

Вплив на продуктивність

Перше відвідування

Збір виконується асинхронно і не блокує рендеринг сторінки.

Наступні відвідування (влучання в кеш)

Усунення проблем

Відбиток не збирається

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

«WebAssembly blocked by Content Security Policy»

Якщо ви бачите це попередження в консолі браузера, 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

Дивіться Початок роботи → Content Security Policy для повного довідника.

Різні Device ID на одному й тому самому пристрої

Це може відбуватись у таких випадках:

• Збережені дані браузера були очищені
• Профіль браузера змінився
• Відвідувач використовує приватний або інкогніто-режим
• Браузер пройшов значне оновлення

Це очікувана поведінка — розпізнавання адаптується до змін пристрою з часом.

Збір триває надто довго

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

Події не спрацьовують

1. Переконайтеся, що ви підписуєтесь на події до запуску SDK
2. Перевірте, що атрибути автоініціалізації вказані правильно
3. Переконайтеся, що немає помилок JavaScript, які блокують виконання

Найкращі практики

1. Використовуйте data-auto-check-once замість data-auto-collect, щоб мінімізувати зайвий збір

2. Завантажуйте SDK асинхронно з атрибутом async, щоб не блокувати завантаження сторінки

3. Прослуховуйте події замість опитування window.noxticaResult

4. Не змінюйте TTL без потреби — стандартний 7-денний інтервал оптимізований для більшості випадків

5. Обробляйте помилки коректно — збій збору не повинен ламати вашу сторінку

Подальші кроки

• Початок роботи — посібник з початкового налаштування
• Інтеграція з бекендом — серверні запити до пристроїв