Начало работы

Это руководство поможет вам добавить 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 и Production

У вас будет два Site Key: один для разработки и тестирования, другой для продакшна. Каждый работает по собственным политикам и хранит данные полностью отдельно.

Всегда переключайте Site Key для каждого окружения. Никогда не используйте ключ pk_sand_* в продакшн-трафике — sandbox-данные не появятся в ваших продакшн-дашбордах, а оценка риска будет слишком мягкой. И наоборот, использование pk_prod_* в разработке расходует производственный лимит запросов.

Распространённый паттерн:

<script>
	// Выбираем ключ по имени хоста; в разработке используем 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

Если ваш сайт использует политику безопасности контента, вам нужно разрешить 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 Keys

Ваш Site Key (pk_...) — это публичный идентификатор, который аутентифицирует запросы с вашего домена. Каждый домен, добавленный в Backoffice, получает уникальный Site Key.

Важные примечания:

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

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

const client = NoxticaCollector.createClient({
	// Ваш Site Key (обязательно)
	siteKey: 'pk_prod_your_site_key_here',

	// Эндпоинт API (по умолчанию production)
	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 и добавьте ваши источники
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 Keys при компрометации
• Просматривать аналитику с фильтрацией по домену

Версия SDK

Текущая версия SDK: 3.3.0 (Schema: 2026-05-24)

Что нового в 3.3.0

• Лёгкие поведенческие сигналы (всегда включены) — простые временны́е подсказки: как долго длится сессия и как быстро посетитель впервые взаимодействует. Никаких биометрических данных, явного согласия конечного пользователя не требуется.
• Поведенческая биометрия (опционально, opt-in) — когда вы включаете её в Backoffice → Settings → Behavioral Biometrics, Noxtica также изучает ритм движений мыши, тайминг кликов и прокрутку. Это считается биометрическими данными согласно строгому законодательству о конфиденциальности, поэтому требуется явное согласие конечного пользователя. Подробнее — в разделе Поведенческая биометрия ниже.
• Проверка согласованности Apple Pay — подтверждает, что устройство, заявляющее себя iPhone, действительно ведёт себя как iPhone, выявляя распространённый трюк подделки.
• Сопоставление сетевого фингерпринта — распознаёт характерные паттерны подключения распространённых инструментов автоматизации, чтобы трафик от скриптов и ботов выделялся даже при убедительном внешнем виде браузера.
• Репутация IP — отмечает посетителей, приходящих из сетей с плохой репутацией, с возможностью подключить собственный предпочтительный фид разведки угроз.

Поведенческая биометрия (опционально, opt-in)

Noxtica также может изучать ритм движений мыши, кликов и прокрутки. Это функция opt-in, отключённая по умолчанию.

Почему opt-in? Такие поведенческие данные считаются чувствительными персональными данными согласно строгому законодательству о конфиденциальности, поэтому их сбор требует явного согласия от конечного пользователя. Мы делаем это opt-in, чтобы вы контролировали, когда и как это используется.

Как включить:

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

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

Следующие шаги

• Попробуйте живую демонстрацию, чтобы увидеть фингерпринтинг в действии
• Прочитайте руководство по интеграции с бэкендом для серверных запросов
• Откройте дашборд, чтобы изучить собранные данные