ヒューマンスコアリング¶
アプリが判断を下す瞬間に、現在のセッションが実在の人物によるものかどうかを読み取ります。SDK はユーザーの 操作に合わせて分類を最新の状態に保つため、読み取りはネットワークを呼び出しません。アプリがすでに受け取った 入力のスコアリングが終わるのを待ち(通常は何もありません)、結果を読み取るだけです。
スコア、その背後にある証拠、モデルのしきい値がどう組み合わさる かは、スコアリングの仕組みで説明しています。
このユースケースの内容¶
| ページ | 内容 |
|---|---|
| ヒューマンスコアリング(このページ) | 判断ポイントで分類を読み取る |
| ユーザー同意 | 何かを記録する前にユーザーに許可を求める |
| 機密性の高い画面 | パスワードや支払いのフィールドが画面にある間、取得を一時停止する |
| カスタムイベント | アプリ内の瞬間をセッションのタイムライン上にマークする |
| セッション | ログアウトやアカウント切り替えで新しいセッションを開始する |
使いどころ¶
- アカウントの作成、フォームの送信、プロモーションの利用の前
- ボットが悪用するステップの前: 投稿、投票、カートへの追加、報酬の受け取り
- 自分のフローのどちらの分岐に進むかを決めるとき — ユーザーを通すか、チャレンジを追加するか
前提条件¶
- SDK がインストールされ、開始されている。クイックスタートを参照してください。
- ユーザーが同意している。同意がなければ何も記録されず、結果は
.insufficientのままです。 ユーザー同意を参照してください。 - ユーザーがアプリを操作している。セッションがモデルの求める数(組み込みモデルでは 8)の
アクションを持つまでは、
十分ではなく、結果は
.insufficientです。 起動直後にはアクションはありません。 証拠を参照してください。
使い方¶
分類を読み取る¶
import DeaSDK
let result = (try? Dea.sdk?.getClassification())?.result ?? .insufficient
switch result {
case .human:
allowAction()
case .bot:
refuseAction() // or your strictest fallback
case .undetermined:
showChallenge() // not certain either way
case .insufficient:
showChallenge() // not enough evidence yet: too early, not a bot
}
allowAction、refuseAction、showChallenge は自分のものに置き換えてください。
答えは 2 つではなく 4 つあります。
| 結果 | 条件 |
|---|---|
.insufficient |
まだ証拠が足りない、または SDK がスコアリングできない。value は nil |
.human |
スコアがモデルの human しきい値以上 |
.bot |
スコアがモデルの bot しきい値未満 |
.undetermined |
スコアが 2 つのしきい値の間 |
human しきい値を設定していないモデルには基準が 1 つしかありません。bot しきい値以上のスコアは .human
です。SDK に組み込まれたモデルは両方のしきい値を設定しています。
各結果で何を許可するかはアプリ側の判断です。.insufficient も .undetermined も否定的な分類では
ありません。アプリを開いたばかりのユーザーは、組み込みモデルではセッションが 8 アクションを持つまで
.insufficient と読み取られます。
進捗を表示する、または結果を説明する¶
import DeaSDK
guard let dea = Dea.sdk else { return }
do {
let reading = try dea.getClassification()
if reading.result == .insufficient {
print("\(reading.actions) action(s) so far; keep going")
} else {
print(reading.result, reading.value ?? 0, reading.botThreshold ?? 0,
reading.humanThreshold ?? .nan)
}
} catch let missing as ThresholdMissing {
print("model \(missing.modelVersion) carries no bot threshold")
} catch {}
| フィールド | 型 | 説明 |
|---|---|---|
result |
ClassificationResult |
.human、.bot、.undetermined、.insufficient のいずれか |
value |
Double? |
0 から 1 までのスコア。result が .insufficient のときに限り nil |
actions |
Int |
スコアの根拠となるスコアリングされたアクションの数。読み込まれたモデルが求める数(組み込みモデルでは 8)に達すると、結果は .insufficient から変わる |
botThreshold |
Double? |
読み込まれたモデルの bot しきい値 |
humanThreshold |
Double? |
読み込まれたモデルの human しきい値。モデルが設定していない場合は nil |
modelVersion |
Int? |
しきい値の由来となるモデル。組み込みモデルでは 0 |
しきい値は読み込まれたモデルからのみ得られます。SDK に組み込まれたモデルか、SDK がダウンロードした より新しいモデルです(モデルオプションを参照)。 すべてのフィールドは同じ瞬間のものなので、結果は常に隣の数値と整合します。
getClassification() が ThresholdMissing を throw するのは、読み込まれたモデルが bot しきい値を持たない
ときだけです。DEA が提供するすべてのモデルはこれを持っています。
トラブルシューティングを参照してください。
SDK がスコアリングできることを確認する¶
import DeaSDK
if let dea = Dea.sdk, !dea.ready {
print("DEA cannot score: \(dea.coreFault ?? "unknown")")
}
ready が false のとき、SDK は動作して取得は続けますがスコアリングはできず、coreFault が理由を
示します。このとき getClassification() は value が nil の .insufficient を返し、throw しません。
タイピングを報告する¶
スマートフォンのキーボードはテキストフィールドに文字を渡し、キーイベントは渡さないため、SDK は自力では
タイピングを取得できません。各キーストロークを captureKey で報告してください。渡すのはそのクラス
だけで、文字そのものは決して渡しません。
import DeaBase
import DeaSDK
Dea.sdk?.captureKey(KeyClass.of("a")) // .letter
Dea.sdk?.captureKey(.delete) // backspace
eventsに.keyDownを追加してください。これがないとcaptureKeyは何もしません。- パスワードフィールドではキーストロークを報告しないでください。 クラスとしてもです。タイピングの リズムだけでパスワードの推測を絞り込めることがあります。
KeyClass.of(_:)は.letter(あらゆる文字体系)、.digit、.space、.otherのいずれかを 返します。削除は自分で.deleteとして報告してください。- ソフトキーボードにはキーの解放がないため、押下だけを送ります。アプリが解放を検知できる場合
(ハードウェアキーボード)は
pressed: falseで報告し、eventsに.keyUpを追加してください。 - キー押下は、タッチと同様に、取得の一時停止中とユーザーの同意前は拒否されます。
例¶
サインアップボタンをゲートする(SwiftUI)¶
import DeaSDK
import SwiftUI
struct SignUpButton: View {
let onSignUp: () -> Void
let onChallenge: () -> Void
var body: some View {
Button("Create account") {
if (try? Dea.sdk?.getClassification())?.result == .human {
onSignUp()
} else {
onChallenge() // e.g. show a captcha
}
}
}
}
サインアップボタンをゲートする(UIKit)¶
import DeaSDK
import UIKit
class SignUpViewController: UIViewController {
@IBAction func createAccountTapped(_ sender: UIButton) {
if (try? Dea.sdk?.getClassification())?.result == .human {
submitSignUp()
} else {
showChallenge() // e.g. show a captcha
}
}
private func submitSignUp() { /* your sign-up */ }
private func showChallenge() { /* your fallback */ }
}
テキストフィールドのタイピングを報告する(UIKit)¶
キーの種類を追加して SDK を作成します。
import DeaBase
import DeaSDK
let dea = DeaSdk(
options: DeaSdkOptions(
appId: "YOUR_APP_ID",
appKey: "YOUR_APP_KEY",
events: CaptureEvent.pointerKinds + [.keyDown]
)
)
次に、フィールドのデリゲートから報告します。
import DeaBase
import DeaSDK
import UIKit
class CommentViewController: UIViewController, UITextFieldDelegate {
private let commentField = UITextField()
override func viewDidLoad() {
super.viewDidLoad()
commentField.delegate = self
view.addSubview(commentField)
}
func textField(
_ textField: UITextField,
shouldChangeCharactersIn range: NSRange,
replacementString string: String
) -> Bool {
if string.isEmpty {
Dea.sdk?.captureKey(.delete)
} else if string.count == 1 {
Dea.sdk?.captureKey(KeyClass.of(string))
}
return true
}
}
貼り付けたテキストや自動修正による置換は複数の文字が一度に届きます。この例ではそれらをタイピングとして 報告していません。
API¶
| メンバー | 戻り値 | 説明 |
|---|---|---|
getClassification() |
Classification |
結果、スコア、比較に使われたしきい値を 1 回の読み取りで返す。ThresholdMissing を throw する |
ready |
Bool |
SDK がスコアリングできるかどうか |
coreFault |
String? |
SDK がスコアリングできない場合、その理由 |
captureKey(_:pressed:mods:repeat:field:) |
Void |
1 回のキーストロークをそのクラスで報告する。events に .keyDown が必要 |
関連¶
- ユーザー同意 — 同意前には何もスコアリングされない
- API リファレンス