ブラウザランタイム

このガイドでは、Noxtica SDK が訪問者のブラウザ内でどのように動作するかを説明します——評価中に何が起こるか、キャッシングがどのように処理を高速化するか、よくある問題のトラブルシューティング方法について。

動作の仕組み

Noxtica SDK をページに追加すると、バックグラウンドで4つのことを静かに行います：

1. 認証：あなたの代わりに管理する認証情報を使って、サイトキーでサインインする
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 は軽量な収集モードで動作し続けますが、改ざん保護は弱くなります。正確なスニペットについては Getting Started → コンテンツセキュリティポリシー をご参照ください。

初回訪問: フル評価が実行され、結果がキャッシュされます。

それ以降の訪問（キャッシュウィンドウ内）: キャッシュされた結果が返され、軽量な訪問が記録されます。重い処理は実行されません。

キャッシュウィンドウの満了後: 新しい評価が実行されます。

手動制御

プログラムによる制御には、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日間 です。設定で変更できます：

// 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 は一度だけ評価が行われるよう管理します：

• 1つのタブだけが実際の処理を行う
• 他のタブは待機してその結果を共有する

これは自動的に行われます——設定は不要です。

イベント

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 は3つの収集モードをサポートしています：

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

保護モード（KHAN VM）

ボットに対抗する上で最も難しい点は、ブラウザで動作するものはすべて、原則として、見えて編集もできるということです。意志ある攻撃者はページのコードを読み、何が測定されているかを把握し、静かに偽の答えを返すことができます。

KHAN VM はそのコストを引き上げます。収集を読み取り可能なコードとしてページ上に露出させる代わりに、Noxtica は機密部分を封印されたサンドボックス環境の中で実行します。何を測定するかを決めるロジックは攻撃者が調べて書き換えられる状態で表示されておらず、生成された結果はブラウザを離れる前に封印されます——改ざんや再生成が格段に難しくなります。

KHAN VM が役立つこと：

• 改ざんに強い結果 — 評価はサンドボックス内で封印されてから送信されるため、ページ上の他のスクリプトが静かに変更したり再生成したりできません。
• リバースエンジニアリングが困難 — 収集ロジックはブラウザのデベロッパーツールで読み取り可能な状態にならず、ランタイム内に隠れたままです。
• リプレイ保護 — 各結果は一度限りで検証されるため、取得したレスポンスを再利用してきれいな訪問者を偽装することはできません。

正直な限界 — 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 はブラウザのローカルストレージを使って結果をキャッシュします。利用できない場合（例：プライベートブラウジングやストレージ無効時）：

• 検知は引き続き機能する
• すべてのページ読み込みで新しい評価が実行される
• タブ間の調整が制限される場合がある

クッキーなし

SDK はクッキーを使用しません。必要なものはすべてブラウザのローカルストレージに保存されます。

パフォーマンスへの影響

初回訪問

収集は非同期で実行され、ページのレンダリングをブロックしません。

それ以降の訪問（キャッシュヒット）

トラブルシューティング

フィンガープリントが収集されない

1. ブラウザコンソールでエラーを確認する
2. サイトキーがドメインと完全に一致しているか確認する（https:// を含む）
3. バックオフィスでドメインが有効になっているか確認する
4. デバッグモードを有効にして詳細なログを確認する

「WebAssembly がコンテンツセキュリティポリシーによってブロックされた」

ブラウザコンソールにこの警告が表示される場合、ページのコンテンツセキュリティポリシーが改ざん耐性ランタイム（KHAN VM）をブロックしています。検知は軽量モードで引き続き機能しますが、最強の保護を得るには許可することをお勧めします。

Noxtica の読み込みと実行を許可するには、以下のスニペットを使用してください：

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

詳細は Getting Started → コンテンツセキュリティポリシー をご参照ください。

同じデバイスで異なるデバイス ID が発生する

以下の場合に起こりえます：

• ブラウザの保存データが消去された
• ブラウザプロファイルが変更された
• 訪問者がプライベート/シークレットモードを使用している
• ブラウザが大きなアップデートを経た

これは想定の範囲内です——認識はデバイスの変化に適応します。

収集に時間がかかりすぎる

1. ネットワークタブで遅い API レスポンスを確認する
2. 高速な収集のために mode: 'minimal' の使用を検討する
3. SDK が async 属性付きで読み込まれているか確認する

イベントが発火しない

1. SDK が実行される前にリッスンしているか確認する
2. auto-init 属性が正しいか確認する
3. 実行をブロックする JavaScript エラーがないか確認する

ベストプラクティス

1. 不必要な収集を最小化するために data-auto-collect の代わりに data-auto-check-once を使用する

2. ページ読み込みをブロックしないよう、async 属性を付けて SDK を非同期で読み込む

3. window.noxticaResult をポーリングするのではなく イベントをリッスンする

4. TTL を不必要に変更しない — デフォルトの7日間はほとんどのユースケースに最適化されています

5. エラーを適切に処理する — 収集の失敗がページを壊さないようにする

次のステップ

• Getting Started — 初期セットアップガイド
• バックエンド連携 — サーバーサイドのデバイス照会