コンテンツにスキップ

DEA SDK for Android

アプリのセッションが実在の人物によるものかどうかを検出します。SDK は Android アプリの各画面にわたって タッチ、スタイラス、マウス、スクロール、端末の動きの入力を観測し、セッションを端末上でスコアリングします。

このページの内容: 前提条件 · インストール · SDK の初期化 · 同意を求める · 分類を使う · セットアップの確認 · リリース前に · 次のステップ

前提条件

  • このアプリ用の appId と appKey。アカウントとキーを参照してください
  • minSdk 21(Android 5.0)以降。アテステーションには API 23 (Android 6.0)以降の端末が必要です。
  • Kotlin または Java。API は Kotlin で書かれており、このガイドのサンプルも Kotlin です。

SDK は Kotlin 2.2.20 と Android Gradle Plugin 9.4.0 でコンパイルされ、compileSdk 35、Java 17 の ソース・ターゲット互換性を対象としています。arm64-v8a、armeabi-v7a、x86、x86_64 向けの ネイティブコードを同梱しているため、実機でもエミュレーターでも動作します。

インストール

注: SDK は Maven Central ではなく、DEA の Maven リポジトリからインストールします。リリースごとに 独立したリポジトリがあり、リポジトリの URL がリリースを指定します。

Gradle

settings.gradle.kts に、リリースに対応する DEA のリポジトリを追加します:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://sdk.dep-protocol.com/0.26.0/android")
            content { includeGroup("ai.dea") }
        }
    }
}

続けて、アプリモジュールに SDK を追加します:

// app/build.gradle.kts
dependencies {
    implementation("ai.dea:dea-sdk:0.26.0")
}

content フィルターにより、Gradle は DEA のリポジトリに DEA のパッケージだけを問い合わせます。 google() は残してください。SDK は Google の Play Integrity ライブラリをそこから取得します。 アップグレードするには、リポジトリの URL と依存関係の両方でバージョンを変更します。

ai.dea:dea-sdk パッケージは、同じバージョンの付随ライブラリ ai.dea:dea-base と ai.dea:dea-automation-detection(Gradle が同じリポジトリから取得します)と、Google の Play Integrity ライブラリに依存します。dea-base や dea-automation-detection を別のバージョンで自分で宣言しないで ください。

プラットフォームのセットアップ

取得のための設定は不要です。SDK はマニフェストのマージによって INTERNET 権限をアプリのマニフェストに追加し、 実行時権限は一切要求しません。Android のモーションセンサーには権限が不要です。

アプリが ndk { abiFilters ... } や ABI 分割で ABI を制限している場合は、ユーザーの端末が必要とする ABI を 残してください。除外された ABI では SDK はスコアリングできません。

アテステーションには、追加の Play Integrity の設定が必要です。

SDK の初期化

最初の画面からセッション全体を取得できるように、Application.onCreate() で一度だけ初期化します。

import ai.dea.sdk.DeaConfig
import ai.dea.sdk.DeaSdk
import android.app.Application

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        DeaSdk.init(
            this,
            DeaConfig(
                appId = "YOUR_APP_ID",
                appKey = "YOUR_APP_KEY",
            ),
        )
    }
}

まだ Application クラスがない場合は、AndroidManifest.xml に登録します。

<application
    android:name=".MyApp"
    ... >

appId と appKey は、DEA がこの Android アプリ用に発行したペアです。 アカウントとキーを参照してください。SDK は端末キーを DEA に登録するとき (アテステーション)に、appKey を X-App-Key ヘッダーで送信します。 appKey がない場合、attest() は DEA に接続せずに UNSUPPORTED を返します。分類の読み取りには appKey を 使いません。スコアリングは端末上で行われます。

  • init はメインスレッドで呼び出してください。
  • init は複数回呼び出しても安全です。再度の呼び出しは実行中のインスタンスを返し、そのオプションを維持します。
  • init は例外を投げません。スコアリングエンジンを起動できない場合、 SDK はスコアなしで取得を続け、分類は INSUFFICIENT のままになり、SDK は問題を coreFault で報告します。 モデル更新、自動化の検出、証明も停止します。トラブルシューティングを参照してください。
  • automationDetection = true の場合、自動化がアプリを操作している確かな兆候を最初に見つけた時点で、SDK は すべてのアカウントとビルドで直ちに停止します。何も取得、スコアリング、署名、登録されず、分類は INSUFFICIENT のままです。停止は reset() または新しい起動(アプリの再起動、または dispose() の後の init)まで続き、その間 stopped は null ではありません。外付けタッチスクリーンでは SDK は停止しません。 root 化された端末では停止します(テストビルドを除く)。 自動化の検出と root 化・ジェイルブレイクされた端末を参照してください。
  • Application を渡してください。SDK は渡された Context を実行中ずっと保持するため、ここで Activity を渡すと その Activity は破棄された後もメモリに残ります。
  • 取得はグローバルです。すべてのアクティビティのウィンドウ、モーションセンサー、アプリのライフサイクルを対象とします。 継承すべき基底 Activity も、ラップすべきビューも、画面ごとに登録するものもありません。ダイアログや ポップアップウィンドウの内側のタッチは、Android が別のウィンドウを与えるため、取得されません。
  • 起動時に SDK はバックグラウンドで、DEA のモデルホストに新しいスコアリング モデルがないか確認します。 モデルオプションと プライバシーとネットワークを参照してください。
  • ユーザーが同意するまで何も記録されません。 次のステップを参照してください。

注: 代わりに Activity から初期化する場合(たとえば独自のオンボーディングの後)、すでに表示されている ウィンドウが取得されるのは、そのアクティビティを Context として渡したときだけで、その場合 SDK は そのアクティビティをメモリに保持し続けます。init 後に開始されたアクティビティは、どの Context を渡しても 取得されます。

コードの他の場所では、DeaSdk.instance で実行中のインスタンスを取得します。

val dea = DeaSdk.instance // null before init

デフォルトでは、SDK はユーザーが同意するまで何も記録しません。このステップは必須です。同意を求めないアプリは データを収集せず、分類も得られません。

SDK には既製の同意ダイアログがあります。最初の画面で表示してください。

import ai.dea.sdk.DeaConsentDialog
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity

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

        DeaConsentDialog.show(this) { granted ->
            // The user's answer, or the answer already on file.
        }
    }
}
  • 回答は端末に保存されます。ユーザーが一度回答すると、show は何も表示せず、保存された回答で即座に コールバックするため、起動ごとに呼び出して構いません。
  • 戻るボタンでダイアログを閉じた場合、このコールバックでは「いいえ」として扱われますが保存はされず、 次回また尋ねられます。
  • 表示中のアクティビティを使い、メインスレッドで呼び出してください。

代わりに独自の UI で尋ねる場合は、consent.isAnswered が false のときにプロンプトを表示し、 setConsent で回答を記録します。

import ai.dea.sdk.DeaSdk
import android.app.AlertDialog
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity

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

        val dea = DeaSdk.instance ?: return
        if (!dea.consent.isAnswered) {
            AlertDialog.Builder(this)
                .setTitle("Help us keep bots out")
                .setMessage("We measure how you interact with the app to tell people apart from bots.")
                .setCancelable(false)
                .setPositiveButton("Allow") { _, _ -> dea.setConsent(true) }
                .setNegativeButton("Not now") { _, _ -> dea.setConsent(false) }
                .show()
        }
    }
}

ダイアログの文言、同意の撤回、再度の確認、共有端末についてはユーザー同意 を参照してください。

分類を使う

判断を下す瞬間に分類を読み取ります。読み取りは同期的で、 メインスレッドで実行できる速さです。

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

fun onSignUp(form: SignUpForm) {
    when (DeaSdk.instance?.getClassification()?.result) {
        ClassificationResult.HUMAN -> submitSignUp(form)
        ClassificationResult.BOT -> rejectSignUp()
        else -> showChallenge() // UNDETERMINED or INSUFFICIENT: a captcha, a delay, a manual review
    }
}

getClassification() は HUMAN、BOT、UNDETERMINED、INSUFFICIENT のいずれかを返します。 それぞれで何を許可するかはアプリの判断です。起動直後は INSUFFICIENT です。セッションは、モデルが求める数の アクション(タップ、ドラッグ、スクロール)が集まるまで 十分になりません。組み込みモデルでは 8 です。 証拠を参照してください。

注: getClassification() でユーザーをブロックする前に、現在のリリースにおけるモデルの状態について 本番環境への移行を読んでください。

セットアップの確認

  1. デバッグログを有効にします。
DeaSdk.init(this, DeaConfig(appId = "YOUR_APP_ID", appKey = "YOUR_APP_KEY", debug = true))
  1. デバッグビルドを実行し、Android Studio の Logcat を [dea] でフィルタして開きます。同意プロンプトを 承諾して画面に触れます。test チャネルの SDK ビルドでは、取得されたイベントごとに 1 行表示されます。 出荷する SDK は何も出力しないため、どのビルドでもステップ 3 で確認します。
I/System.out: [dea] PointerObject session=3f0c…
I/System.out: [dea] MotionObject session=3f0c…

画面に触れても何も表示されない場合は、トラブルシューティングを参照してください。

  1. コードから SDK を確認します。
import android.util.Log
import ai.dea.sdk.DeaSdk

val dea = DeaSdk.instance!!
Log.d("MyApp", "ready: ${dea.ready}")              // true
Log.d("MyApp", "fault: ${dea.coreFault}")          // null
Log.d("MyApp", "consent: ${dea.consent.decision}") // GRANTED
Log.d("MyApp", "model: ${dea.modelInfo}")          // its version, and where it came from

val info = dea.sessionInfo
Log.d("MyApp", "session: ${info.session}")         // a UUID
Log.d("MyApp", "sdk: ${info.sdk.version}")

出荷前に debug を無効にしてください。

リリース前に

次のステップ