Початок роботи

Цей посібник допоможе вам додати 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>

Це дозволить:

• Оцінити відвідувача під час першого візиту
• Повторно використовувати результат для повторних відвідувань у межах кеш-вікна (стандартно: 7 днів)
• Непомітно реєструвати повторні відвідування без повторного оцінювання
• Координувати роботу між відкритими вкладками, щоб відвідувач оцінювався лише один раз

Результати доступні через:

// Прослуховувати результати
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);
});

// Або звертатися безпосередньо після збору
console.log(window.noxticaResult);

Ручний збір

Для більшого контролю використовуйте JavaScript API:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Створіть клієнт з вашим Site Key
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Зберіть і надішліть одним викликом
	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',
});

// Збирає лише поза вікном інтервалу (стандартно: 7 днів)
// Інакше реєструє відвідування і повертає кешований результат
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);

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

Колектор розроблено з мінімальним впливом на завантаження сторінки і помітну користувачем затримку:

Як ми зберігаємо легкість:

• Атрибут async — колектор завантажується у фоні і ніколи не затримує відображення або взаємодії сторінки.
• Режим одноразового запуску (data-auto-check-once) — після першого оцінювання повторні відвідування в межах кеш-вікна надсилають лише крихітний пінг (~150 байт).
• Координація між вкладками — кілька відкритих вкладок зводяться до одного оцінювання.
• Кешування після першого завантаження — стійкий до підробки KHAN VM кешується браузером, тому при наступних відвідуваннях завантажується миттєво.
• Фонова обробка там, де це підтримується, — робота залишається поза головним потоком, і сторінка залишається чуйною.

Якщо ви помітили сповільнення після додавання SDK, зробіть профіль за допомогою await client.collectAndSubmit({ telemetry: true }) — повернений result.telemetry містить розбивку за часом.

Sandbox vs. Production

У вас буде два Site Key: один для розробки та staging, один для продакшену. Кожен працює за власними правилами і зберігає дані повністю окремо.

Завжди змінюйте Site Key залежно від середовища. Ніколи не використовуйте ключ pk_sand_* для продакшн-трафіку — дані sandbox не відображатимуться у ваших продакшн-дашбордах і оцінювання ризику буде надто ліберальним. І навпаки: використання ключа pk_prod_* при розробці витрачає бюджет ліміту запитів продакшну.

Поширений патерн:

<script>
	// Вибирайте ключ за hostname; у розробці — sandbox.
	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 не доходить до тегу скрипта, автоініціалізація не запуститься. Налаштуйте її самостійно в коді:

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

• ❌ Деякі контейнери тегів із жорсткою пісочницею (рідко) заважають запуску стійкого до підробки рантайму. SDK продовжує працювати з легшою формою збору і виводить попередження в консоль.

Якщо ви маєте інтегруватися через менеджер тегів, налаштуйте його, щоб теґ Noxtica спрацьовував на All Pages — Window Loaded (або еквіваленті), а не на DOM Ready — це гарантує, що стан згоди буде остаточним до початку роботи.

Content Security Policy

Якщо ваш сайт використовує content-security-policy, вам потрібно дозволити 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_...) — це публічний ідентифікатор, що аутентифікує запити з вашого домену. Кожен домен, доданий у Backoffice, отримує унікальний Site Key.

Важливі зауваження:

• Site Key є публічним і може безпечно вбудовуватися у ваш HTML
• Кожен Site Key прив’язаний до конкретного origin (наприклад, https://example.com)
• API відхиляє запити, де origin не відповідає зареєстрованому домену Site Key

Параметри конфігурації

const client = NoxticaCollector.createClient({
	// Ваш Site Key (обов'язковий)
	siteKey: 'pk_prod_your_site_key_here',

	// Ендпоінт API (стандартно — продакшн)
	apiUrl: 'https://collect.noxtica.com',

	// Режим збору: 'max' (стандартно), 'standard' або 'minimal'
	// Пропустіть, щоб використати max-режим (рекомендовано)
	// mode: 'standard', // Розкоментуйте, щоб відмовитися від сигналів лише у max
});

Режими збору

Формат відповіді

Після збору і надсилання ви отримуєте:

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

Рівні ризику

Аутентифікація

SDK аутентифікує кожне відвідування за допомогою короткочасних, автоматично змінюваних облікових даних, прив’язаних до вашого Site Key. Він запитує їх, оновлює і прикріплює до кожного надсилання за вас.

Вам не потрібно цим керувати — SDK робить усе автоматично.

Процес онбордингу

1. Запросіть доступ: зв’яжіться з нами, щоб запросити демо або почати роботу
2. Налаштування облікового запису: ми створимо ваш тенант-обліковий запис на платформі
3. Додайте домени: увійдіть до Backoffice, перейдіть до Domains і додайте свої origins
4. Скопіюйте Site Key: кожен домен отримує унікальний Site Key
5. Інтегруйте: додайте скрипт із вашим Site Key на ваші сторінки
6. Спостерігайте: переглядайте відбитки та аналітику в панелі Backoffice

Керування кількома доменами

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

• Production: https://www.yoursite.com
• Staging: https://staging.yoursite.com
• Mobile: https://m.yoursite.com

Кожен домен має власний Site Key. Ви можете:

• Вмикати/вимикати домени без перегенерації ключів
• Ротувати Site Key у разі компрометації
• Переглядати аналітику з фільтрацією за доменом

Версія SDK

Поточна версія SDK: 3.3.0 (Schema: 2026-05-24)

Що нового в 3.3.0

• Легкі поведінкові сигнали (завжди увімкнені) — прості тимчасові підказки, як-от тривалість сесії та швидкість першої взаємодії відвідувача. Жодних біометричних даних, жодної згоди кінцевого користувача.
• Поведінкова біометрія (за вибором) — коли ви вмикаєте це в Backoffice → Settings → Behavioral Biometrics, Noxtica також аналізує ритм руху миші, тайминг кліків і прокрутки. Це відноситься до біометричних даних відповідно до суворих правил конфіденційності, тому потрібна явна згода кінцевого користувача. Дивіться Поведінкова біометрія нижче.
• Перевірка узгодженості Apple Pay — підтверджує, що пристрій, який заявляє себе як iPhone, поводиться відповідно, виявляючи поширений трюк зі спуфінгом.
• Зіставлення мережевих відбитків — розпізнає характерні патерни підключення поширених інструментів автоматизації, завдяки чому трафік зі скриптів і ботів виділяється навіть при переконливому вигляді браузера.
• Репутація IP — позначає відвідувачів із мереж із поганою репутацією, з можливістю підключити власний бажаний фід розвідки загроз.

Поведінкова біометрія (необов’язково, за вибором)

Noxtica також може аналізувати ритм руху миші, кліків і прокрутки. Це функція за вибором, вимкнена за замовчуванням.

Чому за вибором? Такі поведінкові дані відносяться до чутливих персональних даних відповідно до суворих правил конфіденційності, тому їх збір потребує явної згоди вашого кінцевого користувача. Ми робимо це опцією, щоб ви контролювали, коли і як це використовується.

Щоб увімкнути:

1. Увійдіть до Backoffice → Settings → Behavioral Biometrics
2. Перегляньте повідомлення про відповідність разом зі своєю командою з питань конфіденційності або юридичним відділом
3. Оновіть свою політику конфіденційності та банер згоди, щоб розкрити цей збір
4. Увімкніть функцію

Після увімкнення Noxtica автоматично враховує ці поведінкові сигнали в майбутніх оцінюваннях, і ваш дашборд відображає відповідний поведінковий показник для кожного домену.

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

• Спробуйте live demo, щоб побачити фінгерпринтинг у дії
• Прочитайте посібник з інтеграції з бекендом для серверних запитів
• Відкрийте дашборд, щоб вивчити зібрані дані