Среда выполнения в браузере

Это руководство объясняет, как 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>

Используете политику безопасности контента (CSP)? Вам нужно разрешить 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}

Что кешируется

• 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 улучшает:

• Защищённые от вмешательства результаты — оценка запечатывается внутри песочницы до отправки, поэтому другие скрипты на странице не могут незаметно изменить или воспроизвести её.
• Сложнее поддаётся обратной разработке — логика сбора остаётся скрытой внутри среды, а не читается в инструментах разработчика браузера.
• Защита от воспроизведения — каждый результат одноразовый и проверяется, поэтому захваченный ответ нельзя просто переиспользовать для подделки чистого посетителя.

Честные ограничения — чего он не делает:

• Это функция защиты от вмешательства, а не сквозное шифрование.
• Если ваша страница скомпрометирована (например, через уязвимость межсайтового скриптинга), атакующий на этой странице видит те же сырые сигналы браузера, что и Noxtica. KHAN VM защищает обработку и результат, но не страницу вокруг него.

KHAN VM включается со стороны сервера и не требует изменений в вашей интеграции. Если он не может запуститься — например, из-за блокировки политикой безопасности контента — Noxtica переключается на облегчённый режим сбора, чтобы обнаружение продолжало работать, пусть и с более слабой защитой от вмешательства.

Поддержка браузеров

SDK поддерживает современные браузеры:

В более старых браузерах точность сигналов может быть ниже, но SDK продолжит работу.

Режим отладки

Включите отладочное логирование для устранения проблем:

// До загрузки SDK
globalThis.NOXTICA_DEBUG = true;

// Или на уровне клиента
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

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

В режиме отладки логируются:

• Прогресс сбора
• Жизненный цикл токена
• Попадания и промахи кеша
• Любые возникающие ошибки

Примечание: режим отладки молчит по умолчанию в продакшне. Вывод в консоль не появится, если он не включён явно.

Особенности хранилища

Хранилище браузера

SDK использует локальное хранилище браузера для кеширования результатов. Если оно недоступно (например, в режиме инкогнито или при отключённом хранилище):

• Обнаружение продолжает работать
• При каждой загрузке страницы выполняется свежая оценка
• Координация между вкладками может быть снижена

Без куков

SDK не использует куки. Всё, что ему нужно, хранится в локальном хранилище браузера.

Влияние на производительность

Первый визит

Сбор выполняется асинхронно и не блокирует отрисовку страницы.

Повторные визиты (попадание в кеш)

Устранение неполадок

Фингерпринт не собирается

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

Полную справку см. в разделе Начало работы → 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. Корректно обрабатывайте ошибки — сбой при сборе не должен ломать вашу страницу

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

• Начало работы — руководство по первоначальной настройке
• Интеграция с бэкендом — серверные запросы по устройствам