コンテンツにスキップ

ヒューマンスコアリング

アプリが判断を下す瞬間に、現在のセッションが実在の人物によるものかどうかを読み取ります。SDK はユーザーの操作に 合わせて分類を最新の状態に保つため、読み取りは即座に完了します。ネットワークを待たず、メインスレッドから 安全に呼び出せます。

注: getClassification() でユーザーをブロックする前に、現在のリリースにおける モデルの状態について 本番環境への移行を読んでください。 スコアリングの仕組みでは、 アクション、証拠、しきい値を説明しています。

このユースケースの内容

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

使いどころ

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

前提条件

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

使い方

分類を読み取る

import ai.dea.sdk.ClassificationResult
import ai.dea.sdk.DeaSdk

when (DeaSdk.instance?.getClassification()?.result) {
    ClassificationResult.HUMAN -> {
        // A person. Allow the action.
    }
    ClassificationResult.BOT -> {
        // A bot, by the SDK's reading.
    }
    ClassificationResult.UNDETERMINED -> {
        // Between the thresholds. Take your fallback path.
    }
    ClassificationResult.INSUFFICIENT, null -> {
        // Too early to tell, or no SDK. Not a bot: take your fallback path.
    }
}

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

result 条件
INSUFFICIENT 証拠がまだ足りない、または SDK がスコアリングできない。value は null
HUMAN スコアがモデルの humanThreshold 以上
BOT スコアがモデルの botThreshold 未満
UNDETERMINED スコアが 2 つのしきい値の間

humanThreshold を設定していないモデルでは基準は 1 つで、botThreshold 以上のスコアは HUMAN です。

それぞれの結果で何を許可するかはアプリの判断です。しきい値の間の結果は人物として数えません。人物だけを 通す場所では UNDETERMINED は通らないので、チャレンジなどのフォールバックを用意してください。読み取りには ユーザーの直前のタッチも含まれます。

「証拠がまだ足りない」を他の結果と区別する

import ai.dea.sdk.ClassificationResult
import ai.dea.sdk.DeaSdk

val answer = DeaSdk.instance?.getClassification() ?: return

if (answer.result == ClassificationResult.INSUFFICIENT) {
    // Too early to tell. Let the user keep going, or ask them to interact a little more.
    showHint("Keep going")
}

getClassification() は Classification を返します。

フィールド 型 説明
result ClassificationResult HUMAN、BOT、UNDETERMINED、INSUFFICIENT のいずれか
value Double? セッションのスコア(0〜1)。result が INSUFFICIENT のときに限り null
actions Int value の根拠となるスコアリングされたアクションの数。読み込まれたモデルが求める数(組み込みモデルでは 8)に達すると、結果は INSUFFICIENT から抜けます
botThreshold Double? 読み込まれたモデルのbot しきい値
humanThreshold Double? 読み込まれたモデルの人物しきい値。モデルが設定していない場合は null
modelVersion Int? しきい値の元となるモデル。組み込みモデルでは 0

しきい値は読み込まれたモデルからのみ得られます。すべてのフィールドは 1 回の読み取りから得られるため、常に 互いに整合しています。セッション中に SDK が新しいモデルをダウンロードすると、次の読み取りはそのモデルから 行われ、modelVersion が変わります。

しきい値のないモデルを扱う

読み込まれたモデルがbot しきい値を設定していない場合(しきい値がモデルの一部になる前のモデルファイル)、 getClassification() は ThresholdMissing を投げます。SDK には代わりに使えるしきい値がないため、これを キャッチして未判定のパスに進んでください。

import ai.dea.sdk.ClassificationResult
import ai.dea.sdk.DeaSdk
import ai.dea.sdk.ThresholdMissing
import android.util.Log

val result = try {
    DeaSdk.instance?.getClassification()?.result
} catch (missing: ThresholdMissing) {
    Log.w("MyApp", "model ${missing.modelVersion} has no thresholds")
    ClassificationResult.UNDETERMINED
}

SDK がスコアリングできるか確認する

import ai.dea.sdk.DeaSdk
import android.util.Log

val dea = DeaSdk.instance

if (dea == null) {
    // DeaSdk.init has not been called.
} else if (!dea.ready) {
    Log.w("MyApp", "DEA cannot score: ${dea.coreFault}")
}

ready が false のとき、SDK は動作していますがスコアリングはできません。getClassification() は value が null の INSUFFICIENT を返し、coreFault がその理由を示します。

例

サインアップボタンを制御する

import ai.dea.sdk.ClassificationResult
import ai.dea.sdk.DeaSdk
import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity

class SignUpActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_sign_up)

        findViewById<Button>(R.id.create_account).setOnClickListener {
            if (DeaSdk.instance?.getClassification()?.result == ClassificationResult.HUMAN) {
                signUp()
            } else {
                showChallenge() // e.g. show a captcha
            }
        }
    }

    private fun signUp() { /* … */ }

    private fun showChallenge() { /* … */ }
}

API

メンバー 戻り値 説明
getClassification() Classification HUMAN、BOT、UNDETERMINED、INSUFFICIENT のいずれかと、その根拠となるスコアとしきい値。しきい値のないモデルでは ThresholdMissing を投げます
ready Boolean SDK がスコアリングできるかどうか
coreFault String? SDK がスコアリングできない場合、その理由