コンテンツにスキップ

ヒューマンスコアリング

アプリが判断を下す瞬間に、現在のセッションが実在の人物によるものかどうかを読み取ります。SDK はユーザーが 操作するにつれてセッションを端末上でスコアリングするため、分類の読み取りに待ち時間はなく、ネットワーク 呼び出しも発生しません。

注: 分類はセッションに関するひとつのシグナルであり、それ自体が判断ではありません。bot、 undetermined、insufficient に対するフォールバックの経路を用意してください。スコアがどのように 作られるかはスコアリングの仕組みで説明しています。

このユースケースの内容

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

使いどころ

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

前提条件

  • SDK がインストールされ、初期化されている。クイックスタートを参照してください。
  • ユーザーが同意している。同意がなければ何も記録されず、分類は insufficient のままです。 ユーザー同意を参照してください。
  • ユーザーがアプリを操作している。セッションが モデルの求める数の アクション(組み込みモデルでは 8)に達するまでは 十分ではなく、分類は insufficient です。起動直後は ゼロです。証拠を参照してください。

使い方

分類を読み取る

import 'package:dea_sdk/dea_sdk.dart';

final result =
    DeaSdk.instance?.getClassification().result ?? ClassificationResult.insufficient;

switch (result) {
  case ClassificationResult.human:
    allowAction();
  case ClassificationResult.bot:
  case ClassificationResult.undetermined:
    showChallenge(); // your fallback path
  case ClassificationResult.insufficient:
    showChallenge(); // too early to tell: not a bot, but not proven human either
}

getClassification() は 4 つの結果のいずれかを返します:

結果 条件
insufficient 証拠がまだ足りない、または SDK がスコアリングできない。value は null
human スコアがモデルの human しきい値以上
bot スコアがモデルの bot しきい値未満
undetermined スコアが 2 つのしきい値の間にある

human しきい値を設定しないモデルには基準が 1 つしかありません。bot しきい値以上のスコアは human です。

各結果で何を許可するかはアプリ側の判断です。undetermined は弱い bot ではありません。証拠がどちらとも 決められないという意味です。insufficient も bot ではありません。判断するには早すぎるという意味です。

読み取りは同期的で、直前に起きたジェスチャーも含まれます。呼び出すたびに少し処理が走るため、毎フレーム ではなく判断の時点で呼び出してください。

2 つのしきい値はいずれも SDK が読み込んだスコアリングモデルから来ており、それ以外からは来ません。 アカウント設定も、SDK に組み込まれた値もありません。結果の botThreshold、humanThreshold、 modelVersion が、どの値が使われたかを示します。

読み込まれたモデルに bot しきい値がない場合、getClassification() はモデルのバージョンを modelVersion に載せた ThresholdMissing を投げます。SDK がスコアリングできない場合には決して例外を 投げません。

「証拠がまだ足りない」と否定的な結果を区別する

同じ読み取りで、スコアと、その根拠となる スコアリングされたアクションの数(actions)が 報告されます:

final dea = DeaSdk.instance;
final read = dea?.getClassification();

if (dea == null || !dea.isScoring) {
  // The SDK cannot score. See "Check that the SDK can score" below.
} else if (read!.result == ClassificationResult.insufficient) {
  debugPrint('Only ${read.actions} actions so far — not enough yet');
} else {
  debugPrint('score ${read.value}, result: ${read.result}');
}

すべてのフィールドはひとつのスナップショットから来ているため、常に互いに整合しています。

SDK がスコアリングできることを確認する

final dea = DeaSdk.instance;

if (dea == null) {
  // DeaSdk.init has not been called.
} else if (!dea.isScoring) {
  debugPrint('DEA cannot score: ${dea.error}');
}

isScoring が false のとき、SDK は動作を続け、getClassification() は insufficient を返し、error にその理由が入ります。

SDK が見えない入力を報告する

SDK は Flutter がルーティングするすべてのポインターを取得します。Flutter に届かない入力が 2 種類あるため、 それらはアプリ側から渡す必要があります。キー入力と、Web ビュー内のタッチです。どちらもスコアに加算され、 どちらも取得の一時停止中、同意前、dispose() 後には破棄されます。

キー入力を報告する

スマートフォンのキーボードはテキストフィールドに文字を渡し、キーイベントは渡しません。そのため SDK は キー入力を自力で取得できません。各キーストロークを captureKey で報告してください。渡すのはキーの クラスだけで、文字そのものは決して渡しません:

import 'package:dea_sdk/dea_sdk.dart';

DeaSdk.instance?.captureKey(KeyClass.of('a'));  // KeyClass.letter
DeaSdk.instance?.captureKey(KeyClass.delete);   // backspace
  • events に EventKind.keyDown を追加してください。 これがないと captureKey は何もしません。
  • パスワードフィールドでは、クラスとしてであっても、キーストロークを決して報告しないでください。 入力のリズムだけでパスワードの推測範囲を狭められます。
  • 組み込みの同意ダイアログは、記録されないものの一覧に「入力した内容」を挙げています。キー入力を報告する 場合はその文言を変更してください。文言を変えるを参照してください。
  • KeyClass.of(char) は letter(任意の文字体系の文字)、digit(0 から 9)、space、または other を返します。削除は KeyClass.delete として自分で報告してください。
  • ソフトキーボードにはキーの解放がないため、押下のみを送ります。アプリがキーの解放を検知できる場合 (ハードウェアキーボード)は、pressed: false で報告し、events に EventKind.keyUp を追加して ください。

Web ビュー内のタッチを報告する

Web ビューは自身のタッチを自分で処理し、Flutter はそのいずれも SDK にルーティングしません。したがって、 ユーザーが Web ビュー内で完了するタスクは、アプリがそのタッチを capturePointer で転送しない限り、証拠を 追加しません:

DeaSdk.instance?.capturePointer(
  kind: EventKind.down,
  pointerId: 0,
  x: 120.0,                // logical pixels, relative to the app window
  y: 480.0,
  atEpochMs: 1767225600000, // when the touch happened, Unix milliseconds
);
  • x と y は論理ピクセル単位で、アプリウィンドウ全体に対する座標です。Web ビュー内で計測した 座標には、Web ビュー自身のオフセットを加えてください。
  • atEpochMs はタッチが起きた時刻であり、転送した時刻ではありません。これにより、まとめて転送した タッチもタイミングを保ちます。
  • 各タッチについて down、次に move の列、最後に up(または cancel)を、指ごとに 1 つの pointerId で送ります。

例

サインアップボタンをゲートする

import 'package:dea_sdk/dea_sdk.dart';
import 'package:flutter/material.dart';

class SignUpButton extends StatelessWidget {
  const SignUpButton({super.key, required this.onSignUp, required this.onChallenge});

  final VoidCallback onSignUp;
  final VoidCallback onChallenge;

  @override
  Widget build(BuildContext context) {
    return FilledButton(
      onPressed: () {
        final read = DeaSdk.instance?.getClassification();
        if (read?.result == ClassificationResult.human) {
          onSignUp();
        } else {
          onChallenge(); // e.g. show a captcha
        }
      },
      child: const Text('Create account'),
    );
  }
}

テキストフィールドでキー入力を報告する

キー種別を追加して初期化します:

DeaSdk.init(
  const DeaOptions(
    appId: 'YOUR_APP_ID',
    events: [...pointerKinds, EventKind.keyDown],
  ),
  appKey: 'YOUR_APP_KEY',
);

次に、フィールドから報告します:

import 'package:dea_sdk/dea_sdk.dart';
import 'package:flutter/material.dart';

class TrackedTextField extends StatefulWidget {
  const TrackedTextField({super.key, required this.label});

  final String label;

  @override
  State<TrackedTextField> createState() => _TrackedTextFieldState();
}

class _TrackedTextFieldState extends State<TrackedTextField> {
  String _previous = '';

  void _onChanged(String text) {
    final dea = DeaSdk.instance;
    if (dea != null) {
      if (text.length < _previous.length) {
        dea.captureKey(KeyClass.delete);
      } else if (text.length > _previous.length) {
        dea.captureKey(KeyClass.of(text.substring(text.length - 1)));
      }
    }
    _previous = text;
  }

  @override
  Widget build(BuildContext context) {
    return TextField(
      decoration: InputDecoration(labelText: widget.label),
      onChanged: _onChanged,
    );
  }
}

Web ビューからタッチを転送する

webview_flutter を使う場合、ページ内の小さなスクリプトが 各タッチをアプリに送り、アプリがそれをウィンドウ座標で転送します:

import 'dart:convert';

import 'package:dea_sdk/dea_sdk.dart';
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

const _forwardTouches = '''
(function () {
  var kinds = {touchstart: 'down', touchmove: 'move', touchend: 'up', touchcancel: 'cancel'};
  Object.keys(kinds).forEach(function (type) {
    document.addEventListener(type, function (e) {
      var at = Math.round(performance.timeOrigin + e.timeStamp);
      for (var i = 0; i < e.changedTouches.length; i++) {
        var t = e.changedTouches[i];
        DeaTouch.postMessage(JSON.stringify(
          {kind: kinds[type], id: t.identifier, x: t.clientX, y: t.clientY, at: at}));
      }
    }, {passive: true, capture: true});
  });
})();
''';

class TaskWebView extends StatefulWidget {
  const TaskWebView({super.key, required this.url});

  final Uri url;

  @override
  State<TaskWebView> createState() => _TaskWebViewState();
}

class _TaskWebViewState extends State<TaskWebView> {
  final _viewKey = GlobalKey();

  late final WebViewController _controller = WebViewController()
    ..setJavaScriptMode(JavaScriptMode.unrestricted)
    ..addJavaScriptChannel('DeaTouch', onMessageReceived: _onTouch)
    ..setNavigationDelegate(NavigationDelegate(
      onPageFinished: (_) => _controller.runJavaScript(_forwardTouches),
    ))
    ..loadRequest(widget.url);

  void _onTouch(JavaScriptMessage message) {
    final box = _viewKey.currentContext?.findRenderObject() as RenderBox?;
    if (box == null) return;

    final touch = jsonDecode(message.message) as Map<String, dynamic>;
    final origin = box.localToGlobal(Offset.zero);

    DeaSdk.instance?.capturePointer(
      kind: switch (touch['kind']) {
        'down' => EventKind.down,
        'move' => EventKind.move,
        'up' => EventKind.up,
        _ => EventKind.cancel,
      },
      pointerId: touch['id'] as int,
      x: origin.dx + (touch['x'] as num).toDouble(),
      y: origin.dy + (touch['y'] as num).toDouble(),
      atEpochMs: (touch['at'] as num).toInt(),
    );
  }

  @override
  Widget build(BuildContext context) {
    return WebViewWidget(key: _viewKey, controller: _controller);
  }
}

これは、ページが <meta name="viewport" content="width=device-width"> を設定していてズームされて おらず、CSS ピクセル 1 つが論理ピクセル 1 つに等しいことを前提としています。ユーザーがパスワードを 入力するページからはタッチを転送しないでください。

API

メンバー 戻り値 説明
getClassification() Classification human、bot、undetermined、または insufficient。その根拠となるスコア、証拠、モデルのしきい値を含む
isScoring bool SDK がスコアリングできるかどうか
error Object? SDK がスコアリングできない場合、その理由
captureKey(keyClass, {pressed, mods, repeat, field}) void アプリが検知したキーストローク 1 件を報告する
capturePointer({kind, pointerId, x, y, atEpochMs, tool, force, contact, target}) void Web ビューなど、Flutter がルーティングしないサーフェスからのタッチ 1 件を報告する