コンテンツにスキップ

ヒューマンスコアリング

アプリが判断を下す瞬間に、現在のセッションが実在の人物によるものかどうかを読み取ります。SDK はユーザーが 操作するにつれてスコアを常に最新に保つため、読み取りは即時です。ネットワークを待ちません。

このユースケースの内容

ページ 内容
ヒューマンスコアリング(このページ) 判断ポイントで分類を読み取る
ユーザー同意 何かを記録する前にユーザーに許可を求める
機密性の高い画面 パスワードや支払いのフィールドが画面にある間、取得を一時停止する
カスタムイベント アプリ内の瞬間をセッションのタイムラインに記録する
セッション ログアウトやアカウント切り替えで新しいセッションを開始する

使いどころ

  • アカウント作成、フォーム送信、プロモーションの利用の前
  • ボットに悪用されやすいステップの前: 投稿、投票、カートへの追加、報酬の受け取り
  • 自身のフローのどちらの分岐を取るかを決めるとき — ユーザーを通すか、チャレンジを追加するか

前提条件

  • SDK がインストールされ、初期化されていること。クイックスタートを参照してください。
  • ユーザーがページを操作していること。セッションが モデルの求める数の アクションを持つまでは 十分ではなく、結果は 'insufficient' です。 組み込みモデルでは、デスクトップブラウザーで 20 個(ポインター、スクロール、キーボードのうち少なくとも 2 種類の入力から、それぞれ 3 個以上)、スマートフォンやタブレットのブラウザーで 8 個です。ページ読み込み 直後はゼロです。証拠を参照してください。

使い方

分類を読み取る

import { DeaSdk } from '@dea/sdk';

switch (DeaSdk.current?.getClassification().result) {
  case 'human':
    // Allow the action.
    break;
  case 'bot':
    // Block it, or take your strictest path.
    break;
  default:
    // 'undetermined', 'insufficient', or no SDK: take your fallback path.
}

getClassification() は、セッションのスコアを読み込まれているモデルの 2 つのしきい値と比較します。

結果 条件
'insufficient' 証拠がまだ足りない、または SDK が読み込み中か読み込めなかった。スコアはなく、value は null
'human' スコアが humanThreshold 以上。humanThreshold を設定しないモデルでは基準は 1 つで、botThreshold 以上が 'human'
'bot' スコアが botThreshold 未満
'undetermined' スコアが 2 つのしきい値の間

各結果で何を許可するかはアプリが決めます。'insufficient' と 'undetermined' は異なる答えです。前者は 「まだ早い」、後者は「判断がつかない」です。同じ呼び出しで、スコア(value)、その根拠となる スコアリングされたアクションの数(actions)、両方の しきい値、それらの元となる modelVersion が返されます。 スコアリングの仕組みでそれぞれを説明しています。

読み込まれているモデルにボットのしきい値がない場合、getClassification() は ThresholdMissing を投げます。 トラブルシューティングを参照してください。

収集された証拠の量を確認する

sufficiency() は、セッションがこれまでに収集したもの(実行時間と、入力の種類ごとのアクション数)を 報告します。getClassification() は証拠が足りない間すでに 'insufficient' を返しますが、何が足りないかを 見るには sufficiency() を使います。たとえば、ユーザーが操作する機会を得るまでチャレンジを遅らせる場合です。

import { DeaSdk } from '@dea/sdk';

const s = DeaSdk.current?.sufficiency();

if (s === null || s === undefined) {
  // No SDK, or its scoring engine is not running yet: "no answer yet", not "not enough evidence".
} else if (!s.sufficient) {
  console.log(`Collected ${s.actions} actions over ${s.durationMs} ms — not enough yet`);
}

例

サインアップフォームをゲートする

import { init, DeaSdk } from '@dea/sdk';

init({ appId: 'YOUR_APP_ID', appKey: 'YOUR_APP_KEY' });

document.querySelector<HTMLFormElement>('#sign-up')!.addEventListener('submit', async (event) => {
  event.preventDefault();

  if (DeaSdk.current?.getClassification().result === 'human') {
    await fetch('/api/sign-up', { method: 'POST', body: new FormData(event.currentTarget as HTMLFormElement) });
  } else {
    showCaptcha();
  }
});

showCaptcha はアプリ側のフォールバックを表します。

React

import { DeaSdk } from '@dea/sdk';

export function ClaimRewardButton({ onClaim }: { onClaim: () => void }) {
  const handleClick = () => {
    if (DeaSdk.current?.getClassification().result === 'human') {
      onClaim();
    } else {
      openVerificationDialog();
    }
  };

  return <button onClick={handleClick}>Claim reward</button>;
}

openVerificationDialog はアプリ側のフォールバックを表します。

API

メンバー 戻り値 説明
getClassification() Classification 'human'、'bot'、'undetermined'、'insufficient' のいずれかと、その根拠となるスコアとしきい値
sufficiency() Sufficiency \| null これまでに収集された証拠。スコアリングエンジンが動作していない間は null
ready() Promise<void> SDK の読み込みが成功・失敗を問わず完了した時点で解決する
error Error \| null SDK が分類を生成できない場合、その理由