DEA SDK for Android¶
アプリのセッションが実在の人物によるものかどうかを検出します。SDK は Android アプリの各画面にわたって タッチ、スタイラス、マウス、スクロール、端末の動きの入力を観測し、セッションを端末上でスコアリングします。
このページの内容: 前提条件 · インストール · SDK の初期化 · 同意を求める · 分類を使う · セットアップの確認 · リリース前に · 次のステップ
前提条件¶
- このアプリ用の
appIdとappKey。アカウントとキーを参照してください minSdk21(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 を追加します:
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 に登録します。
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 で実行中のインスタンスを取得します。
同意を求める¶
デフォルトでは、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()でユーザーをブロックする前に、現在のリリースにおけるモデルの状態について 本番環境への移行を読んでください。
セットアップの確認¶
- デバッグログを有効にします。
- デバッグビルドを実行し、Android Studio の Logcat を
[dea]でフィルタして開きます。同意プロンプトを 承諾して画面に触れます。testチャネルの SDK ビルドでは、取得されたイベントごとに 1 行表示されます。 出荷する SDK は何も出力しないため、どのビルドでもステップ 3 で確認します。
画面に触れても何も表示されない場合は、トラブルシューティングを参照してください。
- コードから 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 を無効にしてください。
リリース前に¶
- [ ]
debugがfalseになっている - [ ]
appKeyをDeaSdk.initに渡している。オプションを参照 - [ ] アプリが同意を求めている。ユーザー同意を参照
- [ ] 判断ポイントで分類を読み取り、
UNDETERMINEDとINSUFFICIENTのフォールバックを用意している。ヒューマンスコアリングを参照 - [ ] パスワード画面と決済画面で取得を一時停止している。機密性の高い画面を参照
- [ ] ログアウト時に
reset()を呼び出している。セッションを参照 - [ ]
attest()とrenewAttestation()をメインスレッド以外で呼び出している。アテステーションを参照 - [ ] アプリに Play Integrity の設定が済んでいる。アテステーションを参照
- [ ] 本番環境への移行を読んだ
次のステップ¶
- ユーザー同意 — 同意の記録、撤回、再確認
- ヒューマンスコアリング — 判断ポイントで分類を読み取る
- 機密性の高い画面 — パスワード画面と決済画面で取得を一時停止する
- セッション — ログアウト時に新しいセッションを開始する
- アテステーション — 端末キーを DEA に登録する
- オプション —
initが受け付けるオプション - スコアリングの仕組みとプライバシーとネットワーク
- トラブルシューティング