コンテンツにスキップ

ヒューマンスコアリング

アプリが判断を下す瞬間に、現在のセッションが実在の人物によるものかどうかを読み取ります。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 が必要